@mmerterden/multi-agent-pipeline 20.11.1 → 20.13.0

package/pipeline/commands/multi-agent/analysis-jira/SKILL.md

@@ -2,8 +2,8 @@
 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."
 description-tr: "Yazılmış bir analiz dokümanını Jira story ağacına çevirir: story'leri dokümanın kendi kural kimliklerinden türetir, kapsamı iki yönlü kontrol eder, yazılacak her baytı önizler, sonra yalnız var olmayanı açar."
 allowed-tools: Bash, Read, AskUserQuestion
-argument-hint: "[analysis.md] [--project KEY]  -  optional; with no argument, pick from the documents this run emitted"
-parameters: [{"name":"document","kind":"path"},{"name":"--project","kind":"text"}]
+argument-hint: "[analysis.md] [--project KEY] [--epic KEY]  -  optional; with no argument, pick from the documents this run emitted"
+parameters: [{"name":"document","kind":"path"},{"name":"--project","kind":"text"},{"name":"--epic","kind":"text"}]
 gui: form
 destructive: false
 confirm: none
@@ -22,13 +22,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.
@@ -52,12 +65,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
@@ -83,11 +103,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
@@ -97,9 +120,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/commands/multi-agent/analysis-resolve/SKILL.md

@@ -45,7 +45,7 @@ Inherited decisions: `$HOME/.claude/multi-agent-refs/analysis/locked.md`.
 - 1 match: use it; echo the path, no question.
 - 0 or 2+ matches: AskUserQuestion, `header: "Doc"`, question `<localized: "Which analysis document should we resolve?">`, options = matches (max 3) + Other for a free-typed path.
 
-**Validate**: file exists; front-matter parses with `template_version: v3` (a `v2` doc gets `WARN: v2 doc has no resolvable Section 20 contract; re-run /multi-agent:analysis` and the run halts); a `## <n>. Riskler ve Acik Sorular` / `## <n>. Risks and Open Questions` heading exists (numbering may have re-flowed per the omission rule - match by title, not by the literal number 20).
+**Validate**: file exists; front-matter parses with `template_version: v3` (a `v2` doc gets `WARN: v2 doc has no resolvable Section 20 contract; re-run /multi-agent:analysis` and the run halts); a `## <n>. Riskler ve Acik Sorular` / `## <n>. Risks and Open Questions` heading exists (match by title, not by the literal number 20: the profiles number the section differently).
 
 **Step 2 - Repo root for "from repo" candidates.** Default order: front-matter platform's repo from `state.analysisSpec.repos[]` if the session holds it, else the repo containing the doc, else cwd. Confirm via AskUserQuestion only when no default resolves (`header: "Repo"`, options `Use current working directory` + Other).
 
@@ -60,7 +60,7 @@ Inherited decisions: `$HOME/.claude/multi-agent-refs/analysis/locked.md`.
 
 | Path | Reason |
 |------|--------|
-| `$HOME/.claude/multi-agent-refs/analysis-template.md` | Section 20 / Section 23 table contracts, front-matter shape, omission re-flow |
+| `$HOME/.claude/multi-agent-refs/analysis-template.md` | Section 20 / Section 23 table contracts, front-matter shape, section omission |
 | `$HOME/.claude/multi-agent-refs/conventions-defaults.md` | `convention-fallback` default values per platform |
 | `~/.claude/lib/extract-conventions.sh` | fresh single-field extraction for convention-fallback candidates |
 | `ai-common-toolkit:humanizer` | tone reference for longer merged fragments (short fragments only need the punctuation gate) |

package/pipeline/commands/multi-agent/autopilot/SKILL.md

@@ -18,6 +18,12 @@ confirm: none
 
 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 |

package/pipeline/commands/multi-agent/autopilot-off/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Turn off continuous mode on this machine: the schedule is removed, work already running finishes, the repo selection is kept. Use when the machine should stop picking work up."
+disable-model-invocation: true
 description-tr: "Bu makinede sürekli modu kapatır: zamanlama kaldırılır, koşan iş biter, repo seçimi saklanır."
 argument-hint: "[--now]  -  --now also stops the item currently running"
 parameters: [{"name":"--now","kind":"flag"}]

package/pipeline/commands/multi-agent/doctor/SKILL.md

@@ -22,6 +22,12 @@ same way - late, mid-run, after the pickers had been answered. A missing script
 fails at the call. Malformed preferences fail after Phase 0 has asked five
 questions. A token in a remote URL does not fail at all; it leaks.
 
+## Gotchas
+
+- Exit 4 means the layout did not resolve and nothing was checked. It is not a pass.
+- Without `--probe` no credential is sent anywhere, so a revoked token still reads as mapped.
+- `usage-report` SKIP means nothing has been sent from this machine yet, not that reporting works.
+
 ## Run it
 
 ```bash

package/pipeline/commands/multi-agent/feedback/SKILL.md

@@ -1,6 +1,6 @@
 ---
-description: "Send one message to the maintainer: a bug, an idea or a question. Only the text you type is sent - no logs, no repo names, no paths. Shows the payload and asks before sending."
-description-tr: "Bakımcıya tek mesaj gönderir: hata, fikir ya da soru. Yalnızca yazdığın metin gider - log yok, repo adı yok, yol yok. Göndermeden önce içeriği gösterip onay ister."
+description: "Send one message to the maintainer: a bug, an idea or a question. Only the text you type is sent - no logs, no repo names, no paths. Shows the payload and asks before sending. Use when a run went wrong and the maintainer should know."
+description-tr: "Bakımcıya tek mesaj gönderir: hata, fikir ya da soru. Yalnızca yazdığın metin gider - log yok, repo adı yok, yol yok. Göndermeden önce içeriği gösterip onay ister. Bir koşu ters gittiğinde ve bakımcının bilmesi gerektiğinde kullanılır."
 argument-hint: "[\"<message>\"] [bug | idea | question]  -  with no argument, you are asked for the text"
 parameters: [{"name":"message","kind":"text"},{"name":"category","kind":"enum","enum":["bug","idea","question"]}]
 gui: form

package/pipeline/commands/multi-agent/forget/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms. Use when a saved routine is no longer wanted and should be removed."
+disable-model-invocation: true
 description-tr: "Kaydedilmiş bir /multi-agent rutinini (/multi-agent:save ile oluşturulan) siler: local-only komutunu ve registry kaydını kaldırır. Hangisini soracak ve onay alacak."
 argument-hint: "[name]  -  routine to remove; asked if omitted"
 parameters: [{"name":"name","kind":"text"}]

package/pipeline/commands/multi-agent/garbage-collect/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts), worktree residue (orphan .worktrees dirs, gitlink index entries) and offloaded tool payloads under .multi-agent/refs/ from past runs. With --abandoned, also reaps runs that stopped and were never picked back up, stashing any uncommitted work. Dry-run first; confirms before deleting. Use when scratch files from earlier runs need clearing out, or when stopped runs are holding worktrees."
+disable-model-invocation: true
 description-tr: "Geçmiş çalışmalardan kalan /tmp scratch'ini (picker durumu, review diff'leri, kanal payload'ları, analiz taslakları), worktree kalıntılarını (sahipsiz .worktrees klasörleri, gitlink index kayıtları) ve .multi-agent/refs/ altındaki offload edilmiş araç çıktılarını süpürür. --abandoned ile durup bir daha dönülmemiş koşuları da toplar, commit edilmemiş işi stash'ler. Önce dry-run; silmeden önce onay alır."
 argument-hint: "[--older-than=<minutes>] [--abandoned [--days=N]] [--yes]  -  dry-run unless confirmed"
 parameters: [{"name":"--older-than","kind":"text"},{"name":"--abandoned","kind":"flag"},{"name":"--days","kind":"text"},{"name":"--yes","kind":"flag"}]

package/pipeline/commands/multi-agent/kill/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Stop the given task, then remove its worktree and branch. Asks for confirmation. Use when a running or stuck task should be stopped and its worktree removed."
+disable-model-invocation: true
 description-tr: "Verilen görevi durdurur, ardından worktree'sini ve branch'ini kaldırır. Onay ister."
 argument-hint: "#id [--yes]  -  task ID to delete (e.g. #2); --yes answers the confirmation"
 parameters: [{"name":"task","kind":"run-id","required":true},{"name":"--yes","kind":"flag"}]

package/pipeline/commands/multi-agent/model/SKILL.md

@@ -38,6 +38,13 @@ This command sets both, together:
 Flipping one without the other is the defect this closes, so the pair moves as
 one write or not at all.
 
+The same step re-applies the installed agents (`lib/agent-model-sync.mjs`): every
+agent under `~/.claude/agents` whose `preferredModel` is `fable` gets
+`model: fable` while the switch is on and `model: opus` while it is off. An agent
+spawned without an explicit model runs on that line, so without this the switch
+would cover routed dispatches only. The installer applies the same rule on every
+install and update, so a sync never puts the agents back on a rung that is off.
+
 ## What it reports with no argument
 
 The current rung, the pricing model, and **what the switch means on this host** -

package/pipeline/commands/multi-agent/prune-logs/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Delete per-task project logs under ~/.claude/logs/multi-agent (filter by age/project/task). Audit trail + metrics are preserved. Dry-run first; confirms before deleting. Use when task logs have built up and need trimming by age, project or task."
+disable-model-invocation: true
 description-tr: "~/.claude/logs/multi-agent altındaki görev bazlı proje loglarını siler (yaş/proje/görev filtresi). Denetim izi + metrikler korunur. Önce dry-run; silmeden önce onay alır."
 argument-hint: "[--older-than=<days>] [--project=<name>] [--task=<id>] [--yes]"
 parameters: [{"name":"--older-than","kind":"text"},{"name":"--project","kind":"text"},{"name":"--task","kind":"run-id"},{"name":"--yes","kind":"flag"}]

package/pipeline/commands/multi-agent/prune-prompts/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Zero-base prompt review: measure the always-on instruction footprint, classify every rule block, propose keep/trial-removal/delete; applies only approved rows. Use when a new model ships or instructions have accumulated."
+disable-model-invocation: true
 description-tr: "Sıfır-tabanlı prompt incelemesi: sürekli yüklü talimat yükünü ölçer, her kural bloğunu sınıflar, tut/dene/sil önerir; yalnızca onaylananı uygular."
 argument-hint: "[--report-only]"
 parameters: [{"name":"--report-only","kind":"flag"}]

package/pipeline/commands/multi-agent/review/SKILL.md

@@ -26,6 +26,11 @@ Skip Phase 0-3 and review a diff only. Five input shapes, two providers:
 
 Branch-mode runs print to chat only. PR-mode runs print to chat AND post the verdict to the PR per `$HOME/.claude/multi-agent-refs/channels/pr-review-actions.md`: per-finding inline comments + an explicit approve / needs-work state. **No monolithic advisory comment** is ever posted.
 
+## Gotchas
+
+- The counterpart-repo comparison needs exactly one resolved candidate. With several, an unattended run skips it silently, so an autopilot review can have no cross-platform section.
+- The counterpart's stack comes from marker files, never from the repo name.
+
 ## Steps
 
 ### 0. Session bootstrap  -  TASK_ID + tmp cleanup

package/pipeline/commands/multi-agent/review-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
-description: "Review a written analysis document instead of a diff: resolve it from a path, a Confluence page or a Jira issue, run the deterministic gates first, then a parallel model review. Findings cite the Locked rule they break. Never edits the document."
-description-tr: "Diff yerine yazılmış analiz dokümanını review eder: yol, Confluence sayfası veya Jira issue'sundan getirir, önce deterministik geçitleri koşar, sonra paralel model review. Bulgular ihlal edilen Locked kuralını gösterir. Dokümanı düzenlemez."
+description: "Review a written analysis document instead of a diff: resolve it from a path, a Confluence page or a Jira issue, run the deterministic gates first, then a parallel model review. Findings cite the Locked rule they break. Never edits the document. Use when an analysis needs judging before development starts."
+description-tr: "Diff yerine yazılmış analiz dokümanını review eder: yol, Confluence sayfası veya Jira issue'sundan getirir, önce deterministik geçitleri koşar, sonra paralel model review. Bulgular ihlal edilen Locked kuralını gösterir. Dokümanı düzenlemez. Bir analizin geliştirme başlamadan önce değerlendirilmesi gerektiğinde kullanılır."
 argument-hint: "[path | Confluence URL | pageId | JIRA-KEY] [--state <state.json>]  -  optional; with no argument, pick from recent analyses"
 parameters: [{"name":"target","kind":"text"},{"name":"--state","kind":"path"}]
 gui: form
@@ -14,6 +14,11 @@ confirm: none
 
 `/multi-agent:review` judges a diff. This judges the document that diff was supposed to come from, before anyone writes the code it describes. No worktree, no branch, no commit, and the reviewed document is never edited in place.
 
+## Gotchas
+
+- Validator ERRORs are Blockers and WARNs are Important, unless the document states why the warned-about item is acceptable.
+- Every rubric class is printed, with `none` when empty. A class missing from the verdict did not run; it is not a clean result.
+
 ## Flow
 
 Read `$HOME/.claude/multi-agent-refs/analysis/review.md` and execute it:

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -134,12 +134,10 @@ Step 0 gate rules and why: `features/doctor.md`.
        ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true
      ```
-   - **Localized picker descriptions are an installed-tree artifact.** When
-     `outputLanguage=tr`, the installed `description:` values are Turkish and a
-     `description-en:` sidecar holds the English original (see
-     `localize-commands.mjs`). The repo must ALWAYS receive the English form:
-     after copying commands into `pipeline/commands/`, normalize the copy and
-     verify no sidecar or Turkish description leaked:
+   - **Installed-tree artifacts.** Picker descriptions are Turkish with a
+     `description-en:` sidecar when `outputLanguage=tr`, and fable-tier agents
+     carry `model: opus` while `fableEnabled` is off. The repo always gets the
+     English form and `model: fable`, so normalize after copying:
      ```bash
      # normalize: restore English descriptions, strip description-en sidecars
      node ~/multi-agent-pipeline/pipeline/scripts/localize-commands.mjs restore \
@@ -149,6 +147,7 @@ Step 0 gate rules and why: `features/doctor.md`.
      # backstop: repo description lines must be English (Turkish-diacritics proxy)
      grep -rn '^description:.*[çğıöşüÇĞİÖŞÜ]' ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: localized description leaked into pipeline/commands"; exit 1; } || true
+     node ~/multi-agent-pipeline/pipeline/lib/agent-model-sync.mjs --dir ~/multi-agent-pipeline/pipeline/agents --fable-on
      ```
 
 6. **Cross-platform smoke gate** (final step of the REPO sync, before push):

package/pipeline/lib/agent-model-sync.mjs

@@ -0,0 +1,95 @@
+/**
+ * agent-model-sync.mjs  -  installed agents follow the fable switch.
+ *
+ * prefs.global.modelFallback.fableEnabled is the one switch for the fable rung.
+ * The router honours it for every dispatch it resolves, but an agent spawned
+ * without an explicit model runs on its frontmatter `model:`. So every installed
+ * agent whose `preferredModel` is fable has that line written from the switch:
+ * fable while it is on, opus while it is off. Sources keep `model: fable`; only
+ * installed copies change. Called by model-rung.sh on every flip and by the
+ * installer after it lays the agents down.
+ *
+ * Usage:
+ *   node agent-model-sync.mjs [--dir <agents dir>] [--prefs <prefs file>] [--fable-on]
+ *
+ * --fable-on ignores the switch and writes fable: the sync step uses it to put
+ * the repo copy back on its source form.
+ *
+ * @module pipeline/lib/agent-model-sync
+ */
+
+import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
+
+/**
+ * @param {string} dir - an installed agents directory
+ * @param {boolean} fableOn
+ * @returns {string[]} the file names whose model line changed
+ */
+export function applyFableRung(dir, fableOn) {
+  if (!existsSync(dir)) return [];
+  // A linked agents directory is the source tree itself (a maintainer's
+  // --symlink install); writing there would edit the shipped personas.
+  if (lstatSync(dir).isSymbolicLink()) return [];
+  const want = fableOn ? "fable" : "opus";
+  const changed = [];
+  for (const name of readdirSync(dir).sort()) {
+    if (!name.endsWith(".md")) continue;
+    const path = join(dir, name);
+    let text;
+    try {
+      text = readFileSync(path, "utf8");
+    } catch {
+      continue;
+    }
+    const front = FRONTMATTER.exec(text);
+    if (!front || !/^preferredModel:\s*fable\s*$/m.test(front[1])) continue;
+    const nextFront = front[1].replace(/^model:.*$/m, `model: ${want}`);
+    if (nextFront === front[1]) continue;
+    const next = text.replace(front[1], nextFront);
+    if (lstatSync(path).isSymbolicLink()) rmSync(path);
+    writeFileSync(path, next);
+    changed.push(name);
+  }
+  return changed;
+}
+
+/**
+ * @param {string} prefsPath
+ * @returns {boolean}
+ */
+export function fableEnabled(prefsPath) {
+  try {
+    const prefs = JSON.parse(readFileSync(prefsPath, "utf8"));
+    return prefs?.global?.modelFallback?.fableEnabled === true;
+  } catch {
+    return false;
+  }
+}
+
+function arg(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const claude = join(homedir(), ".claude");
+  const dir = arg(argv, "--dir") ?? join(claude, "agents");
+  const prefs =
+    arg(argv, "--prefs") ??
+    (process.env.MULTI_AGENT_PREFS || undefined) ??
+    join(claude, "multi-agent-preferences.json");
+  const on = argv.includes("--fable-on") || fableEnabled(prefs);
+  const changed = applyFableRung(dir, on);
+  if (changed.length) {
+    process.stdout.write(
+      `agents on ${on ? "fable" : "opus"}: ${changed.map((n) => n.replace(/\.md$/, "")).join(", ")}\n`,
+    );
+  }
+}

package/pipeline/lib/analysis-jira-write.sh

@@ -10,8 +10,8 @@
 # decides WHAT to write can be tested without a network.
 #
 # `jira-publish.sh` cannot do this: it writes a comment or a description on an
-# issue that already exists. The only creation path in this repo was a curl
-# hand-written inside a markdown instruction, which is the thing this replaces.
+# issue that already exists. This file is the one place that creates issues, so
+# the gate, the ledger and the label search apply to every creation.
 #
 # THE WRITE IS LEDGERED, AND THE LEDGER IS THE POINT
 #
@@ -32,11 +32,10 @@
 # AN EXISTING NODE IS SKIPPED, NEVER UPDATED
 #
 # Jira has no backup path for fields other than description. Rewriting a body an
-# engineer has since edited would repeat, at tree scale, the defect that made
-# jira-publish.sh take backups in the first place.
+# engineer has since edited would lose that edit with no way back.
 #
 # Usage:
-#   analysis-jira-write.sh --plan plan.json --project KEY [--dry-run] [--ledger FILE]
+#   analysis-jira-write.sh --plan plan.json --project KEY [--dry-run] [--ledger FILE] [--epic KEY]
 #
 # Exit: 0 written (or previewed), 3 the plan does not parse, 4 auth, 5 a Jira
 #       call failed, 64 usage.
@@ -47,14 +46,15 @@ SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 . "$SELF_DIR/_jira-auth.sh"
 
-PLAN=""; PROJECT=""; DRY=0; LEDGER=""
+PLAN=""; PROJECT=""; DRY=0; LEDGER=""; EPIC=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --plan) PLAN="${2:-}"; shift 2 ;;
     --project) PROJECT="${2:-}"; shift 2 ;;
     --ledger) LEDGER="${2:-}"; shift 2 ;;
     --dry-run) DRY=1; shift ;;
-    *) echo "usage: analysis-jira-write.sh --plan FILE --project KEY [--dry-run] [--ledger FILE]" >&2; exit 64 ;;
+    --epic) EPIC="${2:-}"; shift 2 ;;
+    *) echo "usage: analysis-jira-write.sh --plan FILE --project KEY [--dry-run] [--ledger FILE] [--epic KEY]" >&2; exit 64 ;;
   esac
 done
 [ -n "$PLAN" ] && [ -f "$PLAN" ] || { echo "ERR: --plan FILE is required and must exist" >&2; exit 64; }
@@ -90,7 +90,7 @@ fi
 ORPHANS=0
 if [ -f "$LEDGER" ]; then
   ORPHANS=$(jq -rs '[.[] | select(.event=="intent")] as $i
-                  | [.[] | select(.event=="created") | .label] as $c
+                  | [.[] | select(.event=="created" or .event=="exists") | .label] as $c
                   | [$i[] | select(.label as $l | ($c | index($l)) | not)] | length' \
              "$LEDGER" 2>/dev/null || echo 0)
   if [ "${ORPHANS:-0}" -gt 0 ]; then
@@ -109,7 +109,7 @@ existing_for() {  # existing_for <label> -> prints the key, or empty
   printf ''
 }
 
-LABELS="$(jq -r '[.nodes[] | .label, (.subtasks[]?.label)] | join(",")' "$PLAN")"
+LABELS="$(jq -r '[.nodes[] | .label, (.clones[]?.label), (.subtasks[]?.label)] | join(",")' "$PLAN")"
 if [ "$DRY" -eq 0 ] && [ -n "$LABELS" ]; then
   JQL="project=${PROJECT} AND labels in (${LABELS})"
   ENC="$(printf '%s' "$JQL" | jq -sRr @uri)"
@@ -122,13 +122,11 @@ if [ "$DRY" -eq 0 ] && [ -n "$LABELS" ]; then
 fi
 
 # Two channels on purpose. The human line goes to stdout; the created key comes
-# back in CREATED_KEY. Returning the key on stdout too meant a caller using
-# command substitution swallowed the report - the first dry run printed a header
-# and nothing else, and the tree looked empty.
+# back in CREATED_KEY. Keeping the key off stdout lets a caller capture the
+# report with command substitution without losing any of it.
 # Same gate, same five candidate paths, same refusal as jira-publish.sh and
-# post-pr-review.sh. This file is the only ISSUE-CREATION path in the tree, and
-# a summary plus a description is outbound text like any other - it was the one
-# writer the gate did not cover.
+# post-pr-review.sh. A summary plus a description is outbound text like any
+# other, so every issue this file creates passes the gate first.
 ma_outbound_gate_text() {
   local text="$1" og="" tmp rc
   for c in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/outbound-gate.mjs" \
@@ -149,25 +147,52 @@ ma_outbound_gate_text() {
   return $rc
 }
 
+link_issues() {  # link_issues <type> <fromKey> <toKey> <cloneLabel>
+  local ltype="$1" from="$2" to="$3" label="$4" linked
+  if [ "$DRY" -eq 1 ]; then
+    echo "  link    $ltype  ${from:-<story>} <-> ${to:-<clone>}"
+    return 0
+  fi
+  # A link already there is left alone, so a re-run never doubles it.
+  linked="$(jira_api GET "/rest/api/2/issue/${from}?fields=issuelinks" 2>/dev/null \
+    | jq -r --arg t "$to" '[.fields.issuelinks[]? | (.outwardIssue.key // .inwardIssue.key)] | index($t) != null' 2>/dev/null || echo false)"
+  if [ "$linked" = "true" ]; then
+    echo "  linked  $from <-> $to"
+    return 0
+  fi
+  if ! printf '%s' "$(jq -cn --arg t "$ltype" --arg a "$from" --arg b "$to" \
+      '{type: {name: $t}, inwardIssue: {key: $a}, outwardIssue: {key: $b}}')" \
+      | jira_api POST "/rest/api/2/issueLink" --data @- >/dev/null; then
+    echo "ERR: could not link $from to $to" >&2
+    return 5
+  fi
+  ledger link "$label" "$to"
+  echo "  linked  $from <-> $to"
+}
+
 CREATED_KEY=""
-create_issue() {  # create_issue <label> <summary> <issuetype> <parentKey|""> <description>
-  local label="$1" summary="$2" itype="$3" parent="$4" desc="$5" body key existing
+create_issue() {  # create_issue <label> <summary> <issuetype> <parentKey|""> <description> [extraFieldsJson]
+  local label="$1" summary="$2" itype="$3" parent="$4" desc="$5" extra="${6:-}" body key existing
+  [ -n "$extra" ] || extra="{}"
   CREATED_KEY=""
   existing="$(existing_for "$label")"
   if [ -n "$existing" ]; then
     # Skipped, never updated: Jira has no backup path for fields other than
     # description, and an engineer may have edited this body since.
     echo "  exists  $existing  $summary"
+    ledger exists "$label" "$existing"
     CREATED_KEY="$existing"
     return 0
   fi
   body="$(jq -n --arg p "$PROJECT" --arg s "$summary" --arg t "$itype" \
-                --arg l "$label" --arg d "$desc" --arg par "$parent" '
+                --arg l "$label" --arg d "$desc" --arg par "$parent" --argjson x "$extra" '
     {fields: ({project: {key: $p}, summary: $s, issuetype: {name: $t},
                labels: [$l], description: $d}
-              + (if $par == "" then {} else {parent: {key: $par}} end))}')"
+              + (if $par == "" then {} else {parent: {key: $par}} end)
+              + $x)}')"
   if [ "$DRY" -eq 1 ]; then
     echo "  create  $itype  $summary   [$label]"
+    [ "$parent" = "" ] && printf '%s\n' "$desc" | sed 's/^/          /'
     return 0
   fi
   # After the dry-run branch, because a dry run publishes nothing, and before
@@ -196,6 +221,24 @@ echo "analysis-jira-write: ${PROJECT}, coverage ${VERDICT}$([ "$DRY" -eq 1 ] &&
 [ "$VERDICT" = "unverifiable" ] && \
   echo "  NOTE: coverage could not be checked for this document; the tree is unverified."
 
+# The epic the stories join, if one was named. The link field depends on the
+# deployment, so it is resolved once, against the live site, before any write.
+STORY_EXTRA="{}"
+if [ -n "${EPIC:-}" ]; then
+  echo "  epic  $EPIC"
+  if [ "$DRY" -eq 0 ]; then
+    . "$(dirname "${BASH_SOURCE[0]}")/jira-epic-link.sh"
+    E_MODE="$(jq -r '.prefsUsed.epicLinkMode // "auto"' "$PLAN")"
+    E_FIELD="$(jq -r '.prefsUsed.epicLinkFieldId // empty' "$PLAN")"
+    E_SERVER="" E_FIELDS=""
+    if [ "$E_MODE" = "auto" ]; then
+      E_SERVER="$(jira_api GET "/rest/api/2/serverInfo" 2>/dev/null || echo "")"
+      [ -n "$E_FIELD" ] || E_FIELDS="$(jira_api GET "/rest/api/2/field" 2>/dev/null || echo "")"
+    fi
+    STORY_EXTRA="$(epic_link_fields "$E_MODE" "$EPIC" "$E_FIELD" "$E_SERVER" "$E_FIELDS")"
+  fi
+fi
+
 RC=0
 NODES="$(jq -c '.nodes[]' "$PLAN")"
 while IFS= read -r node; do
@@ -204,18 +247,27 @@ while IFS= read -r node; do
   s_title="$(printf '%s' "$node" | jq -r '.title')"
   s_src="$(printf '%s' "$node" | jq -r '.sourceIds | join(", ")')"
   s_type="$(jq -r '.prefsUsed.storyIssueType // "Story"' "$PLAN")"
-  s_desc="Sources: ${s_src:-none (derived from the section heading)}"
-  if ! create_issue "$s_label" "$s_title" "$s_type" "" "$s_desc"; then
-    # A failed story does not get its sub-tasks written anyway. `create_issue`
-    # omits the parent field when the parent key is empty, so without this the
-    # sub-tasks of a story Jira refused were still POSTed - and landed as live,
-    # parentless issues nobody asked for, from a run that had already reported
-    # an error.
+  s_desc="$(printf '%s' "$node" | jq -r '.description // empty')"
+  [ -n "$s_desc" ] || s_desc="Sources: ${s_src:-none (derived from the section heading)}"
+  if ! create_issue "$s_label" "$s_title" "$s_type" "" "$s_desc" "$STORY_EXTRA"; then
+    # A failed story does not get its sub-tasks or clones written. `create_issue`
+    # omits the parent field when the parent key is empty, so they would land as
+    # live, parentless issues from a run that has already reported an error.
     RC=5
     echo "  skipped   this story's sub-tasks: the story itself was not created" >&2
     continue
   fi
   skey="$CREATED_KEY"
+  LINK_TYPE="$(jq -r '.prefsUsed.cloneLinkType // "Relates"' "$PLAN")"
+  while IFS= read -r clone; do
+    [ -n "$clone" ] || continue
+    c_label="$(printf '%s' "$clone" | jq -r '.label')"
+    c_title="$(printf '%s' "$clone" | jq -r '.title')"
+    c_extra="$(printf '%s' "$clone" | jq -c --argjson e "$STORY_EXTRA" \
+      '$e + {components: [.components[] | {name: .}]}')"
+    create_issue "$c_label" "$c_title" "$s_type" "" "$s_desc" "$c_extra" || { RC=5; continue; }
+    link_issues "$LINK_TYPE" "$skey" "$CREATED_KEY" "$c_label" || RC=5
+  done < <(printf '%s' "$node" | jq -c '.clones[]?')
   while IFS= read -r sub; do
     [ -n "$sub" ] || continue
     t_label="$(printf '%s' "$sub" | jq -r '.label')"
@@ -228,7 +280,9 @@ while IFS= read -r node; do
         | jq -r '[.projects[]?.issuetypes[]? | select(.subtask==true) | .name] | first // empty' 2>/dev/null || echo "")"
     fi
     [ -n "$t_type" ] || t_type="Sub-task"
-    create_issue "$t_label" "${s_title} - ${t_role}" "$t_type" "$skey" "$s_desc" || RC=5
+    t_desc="$(printf '%s' "$sub" | jq -r '.description // empty')"
+    [ -n "$t_desc" ] || t_desc="Sources: ${s_src:-none (derived from the section heading)}"
+    create_issue "$t_label" "${s_title} - ${t_role}" "$t_type" "$skey" "$t_desc" || RC=5
   done < <(printf '%s' "$node" | jq -c '.subtasks[]?')
 done <<< "$NODES"