@mmerterden/multi-agent-pipeline 20.26.0 → 20.27.0

package/pipeline/multi-agent-refs/platform-parity.md

@@ -128,7 +128,7 @@ is not reported.
 | 1 | Services | Does the counterpart screen call the same endpoints? An endpoint one side calls and the other does not is the finding - including a service that exists only on one platform. |
 | 2 | Parameters | Same request fields, query parameters and headers, with the same optionality. A field sent by one side and omitted by the other is a finding even when both requests succeed. |
 | 3 | Business rules | The conditions around the call and the response: validation, eligibility, retry, empty and error handling, feature-flag checks. A rule present on one side only is the finding. |
-| 4 | Localization keys | The keys the changed screen uses on each side. Different key for the same string, a key one side has and the other does not, and a key that resolves to different copy. |
+| 4 | Localization keys | The keys the changed screen uses on each side. Different key for the same string, a key one side has and the other does not, and a key that resolves to different copy. A key the change ADDS whose display text another key already holds on either side is a duplicate: the existing key is reused (`features/localization-reuse.md`). |
 
 Nothing else. Layout, naming, architecture and idiom differ between the
 platforms by design, and reporting them buries the four things that matter.

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -101,16 +101,16 @@ Register each phase:
 
 ```bash
 bash $HOME/.claude/scripts/phase-tracker.sh add 0 "Init"
-bash $HOME/.claude/scripts/phase-tracker.sh add 1 "Analysis"
+bash $HOME/.claude/scripts/phase-tracker.sh add 1 "Plan"
 # ...
 ```
 
 ### Claude Code  -  also register a TaskList tile per phase
 
 ```text
-For each phase in the current mode, IN PHASE-NUMBER ORDER (0 → 1 → 2 → ... → 5):
+For each `TaskCreate` line `phase-tracker.sh tiles` prints, IN THAT ORDER:
   TaskCreate({
-    subject: "Phase 0: Init",
+    subject: "Phase 0 Init",
     description: "Repo discovery, branch, worktree, identity bind",
     activeForm: "Initializing pipeline"
   })
@@ -118,6 +118,8 @@ For each phase in the current mode, IN PHASE-NUMBER ORDER (0 → 1 → 2 → ...
   bash phase-tracker.sh meta 0 tasklist_id "<taskId>"
 ```
 
+**The subject is the tracker's line, verbatim.** `phase-tracker.sh tiles` prints each subject from the phase names the command registered (`0:Init 1:Plan 2:Dev 3:Review 4:Commit 5:Report` for a full run). Copy it as printed: no task-id prefix, no renamed, merged or annotated phase (`Analysis + Plan`, `Review + Verify`). What a phase does inside goes in `activeForm` or a sub-step tile, never in the phase name. A tile that disagrees with the tracker is a second, wrong progress record.
+
 The `tasklist_id` meta field is persisted so that `:resume` can rebuild the TaskList from the state file in a fresh session.
 
 #### The card is not the widget
@@ -310,13 +312,15 @@ fabricating numbers.
 **Completion tile suffix (Claude Code).** The native widget cannot show
 per-phase tokens, but subject edits after creation are safe (tile order is
 fixed at TaskCreate time). So on phase completion, in addition to the
-narration line, append the spend to the tile subject:
+narration line, set the subject to what `phase-tracker.sh subjects <N>` prints,
+which is the tracker's own line with model, elapsed time and spend; the suffix is
+the tracker's, never typed by hand:
 
 ```text
-TaskUpdate({taskId: <phase_task>, subject: "Phase 2: Dev · ~35k tok · ~$0.26"})
+TaskUpdate({taskId: <phase_task>, subject: "Phase 2 Dev - sonnet - 4m 12s - 35k tok - ~$0.26"})
 ```
 
-Skip the suffix when the phase recorded zero tokens (subject stays clean).
+A phase with no recorded tokens gets no token part from `subjects`; nothing is added by hand.
 
 **Honesty note:** on Claude Code the orchestrator does not receive its own
 usage metering, so per-phase counts are content-size estimates (chars/4 for

package/pipeline/schemas/agent-state.schema.json

@@ -1863,6 +1863,17 @@
         }
       }
     },
+    "evidence": {
+      "type": "object",
+      "description": "Evidence gathered during the run for the report channels. Other evidence kinds live beside flowRuns.",
+      "properties": {
+        "flowRuns": {
+          "type": "array",
+          "description": "Flow-runner run ids (the runId in <RUN_ROOT>/history.jsonl) of the UI scenario runs that verify this task. Channels renders their Xray Test Execution in the 'Test Koşumu (Xray)' block; empty means channels discovers candidate runs instead.",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
     "visualEvidence": {
       "type": ["object", "null"],
       "additionalProperties": false,
@@ -1987,6 +1998,45 @@
             }
           }
         },
+        "scenarios": {
+          "type": "array",
+          "description": "Per-scenario evidence: one screenshot and/or one recording for each test scenario a UI run covered, attached to the Jira issue. Rendered as one evidence line under that scenario by scripts/render-jira-evidence.mjs.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Scenario id, as the test scenarios section names it."
+              },
+              "image": {
+                "type": "object",
+                "additionalProperties": true,
+                "properties": {
+                  "file": { "type": "string" },
+                  "jiraFilename": { "type": "string" },
+                  "url": {
+                    "type": "string",
+                    "description": "Jira attachment content URL, as jira-attach.sh printed it."
+                  }
+                }
+              },
+              "video": {
+                "type": "object",
+                "additionalProperties": true,
+                "properties": {
+                  "file": { "type": "string" },
+                  "jiraFilename": { "type": "string" },
+                  "url": {
+                    "type": "string",
+                    "description": "Jira attachment content URL, as jira-attach.sh printed it."
+                  }
+                }
+              }
+            }
+          }
+        },
         "gaps": {
           "type": "array",
           "description": "Every artefact that is required and absent, with its reason. A recorded reason satisfies the Phase 4 blocker; silence does not.",

package/pipeline/schemas/prefs.schema.json

@@ -829,6 +829,11 @@
               "default": false,
               "description": "v6.1.0+ - Per-phase token cost summary (phase name, tokens_in, tokens_out, est. USD). Source: phase-tracker.sh token tallies + optional OTel spans (MULTI_AGENT_OTEL_SPANS=1). Greyed out if tracker has no token data for the task. Opt-in - off by default so baseline PR body stays unchanged."
             },
+            "testRun": {
+              "type": "boolean",
+              "default": false,
+              "description": "'Test Koşumu (Xray)' block: the Xray Test Execution of the task's UI scenario run, read from the flow runner's history.jsonl by render-flow-run.mjs. Ticked automatically when the run comes from --flow-run or state.evidence.flowRuns; greyed out when no run resolves."
+            },
             "workSummary": {
               "type": "boolean",
               "default": false,
@@ -2231,6 +2236,12 @@
               "default": true,
               "description": "Off disables capture, upload and both render sections. The Phase 4 blocker goes with it."
             },
+            "jiraMedia": {
+              "type": "string",
+              "enum": ["links", "thumbnails"],
+              "default": "links",
+              "description": "How the Jira comment references screenshots: links (one evidence line per scenario, default) or thumbnails (small embedded images). Recordings are always links. Consumed by scripts/render-jira-evidence.mjs --mode."
+            },
             "maxAttachmentMb": {
               "type": "integer",
               "minimum": 1,

package/pipeline/schemas/unattended-policy.json

@@ -128,6 +128,7 @@
     "update-issue-progress.sh": null,
     "analysis-jira-write.sh": null,
     "jira-attach.sh": null,
+    "jira-remote-links.sh": ["apply"],
     "md2confluence-v3.py": ["create", "update"],
     "multi-repo-pipeline.sh": ["push", "pr"],
     "keychain-save.sh": null,

package/pipeline/scripts/_sibling-root.mjs

@@ -0,0 +1,38 @@
+/**
+ * @file _sibling-root.mjs  -  the directory that holds this repo's sibling
+ * checkouts (multi-agent-toolkit-mcp, multi-agent-plugins).
+ *
+ * Siblings sit beside the MAIN checkout. A linked worktree lives inside it, at
+ * `<main>/.worktrees/<name>`, so `<root>/..` from there is `.worktrees/` and no
+ * sibling is found. The main checkout is the directory that holds the shared
+ * git dir, so its parent is the answer for every worktree of the repo.
+ *
+ * Outside git, or when the shared git dir is not a `.git` directory (a bare
+ * repo, a submodule's `.git/modules/<name>`), it falls back to `<root>/..`.
+ *
+ * Usage as a command: `node _sibling-root.mjs <root>` prints the directory.
+ *
+ * Zero runtime dependencies (ADR-0004).
+ */
+
+import { spawnSync } from "node:child_process";
+import { basename, dirname, resolve } from "node:path";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+/** @param {string} root */
+export function siblingsParent(root) {
+  const fallback = resolve(root, "..");
+  const r = spawnSync(
+    "git",
+    ["-C", root, "rev-parse", "--path-format=absolute", "--git-common-dir"],
+    { encoding: "utf8" },
+  );
+  if (r.status !== 0) return fallback;
+  const commonDir = r.stdout.trim();
+  if (basename(commonDir) !== ".git") return fallback;
+  return dirname(dirname(commonDir));
+}
+
+if (invokedDirectly(import.meta.url)) {
+  process.stdout.write(`${siblingsParent(process.argv[2] || process.cwd())}\n`);
+}

package/pipeline/scripts/gen-facts.mjs

@@ -37,6 +37,7 @@ import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import { siblingsParent } from "./_sibling-root.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(HERE, "..", "..");
@@ -94,9 +95,10 @@ try {
 let toolCount = null;
 let toolCategories = null;
 let toolkitVersion = null;
-// Sibling checkouts are looked up beside this repo; GEN_FACTS_SIBLINGS_DIR
-// names another parent directory (a test points it at an empty one).
-const siblingsDir = process.env.GEN_FACTS_SIBLINGS_DIR || join(ROOT, "..");
+// Sibling checkouts are looked up beside the main checkout, also from a worktree
+// under .worktrees/; GEN_FACTS_SIBLINGS_DIR names another parent directory (a
+// test points it at an empty one).
+const siblingsDir = process.env.GEN_FACTS_SIBLINGS_DIR || siblingsParent(ROOT);
 const toolkitDir = join(siblingsDir, "multi-agent-toolkit-mcp");
 if (existsSync(join(toolkitDir, "package.json"))) {
   try {

package/pipeline/scripts/plan-remote-links.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * plan-remote-links.mjs  -  the Issue Links an analysis puts on its Jira issue.
+ *
+ * Jira's "Issue Links" panel holds remote links: a URL, a title and a group
+ * name (`relationship`). Links there survive any later edit of the description
+ * and can be read back through the API, so the sources an analysis used belong
+ * there as well as in the body.
+ *
+ * This file only PLANS. It reads the analysis spec and the issue's current
+ * remote links and prints what to write; `lib/jira-remote-links.sh` writes it.
+ * It never plans a delete.
+ *
+ *   - One link per Figma frame, Confluence page, API contract and published
+ *     analysis page, deduplicated by URL.
+ *   - Every link carries a stable `globalId`. Jira treats a POST with a known
+ *     globalId as an update, so a re-run rewrites its own links in place.
+ *     Own ids start with `ma-`; a Confluence page linked through the
+ *     application link uses Jira's native `appId=<id>&pageId=<n>` form.
+ *   - A URL already linked under another globalId (by a person or another tool)
+ *     is skipped, never duplicated or overwritten.
+ *   - A Confluence page becomes a native "Wiki Page" only when the application
+ *     id is known: passed in, or read from a Wiki Page link already on the
+ *     issue for the same host. It is never guessed; without it the page is a
+ *     plain link.
+ *
+ * Usage:
+ *   node plan-remote-links.mjs --spec <analysis-spec.json | agent-state.json>
+ *        [--existing <remotelink GET response>] [--app-id <host>=<id>] [--lang tr|en]
+ *
+ * Output: {"write": [<remotelink payload>], "skip": [{globalId, url, reason}]}
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const CONFLUENCE_APP = { type: "com.atlassian.confluence", name: "Confluence" };
+
+const LABELS = {
+  en: {
+    figma: "Figma",
+    confluence: "Confluence",
+    api: "API Contract",
+    analysis: "Analysis",
+    wiki: "Wiki Page",
+  },
+  tr: {
+    figma: "Figma",
+    confluence: "Confluence",
+    api: "API Sözleşmesi",
+    analysis: "Analiz",
+    wiki: "Wiki Page",
+  },
+};
+
+export function normalizeUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(String(url).trim());
+  } catch {
+    return String(url).trim();
+  }
+  parsed.hash = "";
+  parsed.hostname = parsed.hostname.toLowerCase();
+  const nodeId = parsed.searchParams.get("node-id");
+  if (/(^|\.)figma\.com$/.test(parsed.hostname)) {
+    // A Figma share link carries per-share parameters (t=, m=dev) and a renamable file
+    // slug; the frame is the file key plus the node id.
+    const { kind, fileKey } = figmaParts(parsed.toString());
+    if (fileKey) parsed.pathname = `/${kind}/${fileKey}`;
+    parsed.search = "";
+    if (nodeId) parsed.searchParams.set("node-id", nodeId.replace(/:/g, "-"));
+  } else {
+    parsed.searchParams.sort();
+  }
+  parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+  return parsed.toString();
+}
+
+function hostOf(url) {
+  try {
+    return new URL(url).host.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function shortHash(text) {
+  return createHash("sha1").update(text).digest("hex").slice(0, 12);
+}
+
+function pageIdOf(page) {
+  if (page.pageId) return String(page.pageId);
+  const match = String(page.url || "").match(/[?&]pageId=(\d+)|\/pages\/(\d+)(?:\/|$)/);
+  return match ? match[1] || match[2] : null;
+}
+
+function figmaParts(url) {
+  try {
+    const parsed = new URL(url);
+    // A branch has its own key and its own frames; the branch key identifies them.
+    const key = parsed.pathname.match(
+      /^\/(design|file|proto|board)\/([^/]+)(?:\/branch\/([^/]+))?/,
+    );
+    return {
+      kind: key ? key[1] : null,
+      fileKey: key ? key[3] || key[2] : null,
+      nodeId: parsed.searchParams.get("node-id"),
+    };
+  } catch {
+    return { kind: null, fileKey: null, nodeId: null };
+  }
+}
+
+/** The application id of the Confluence link Jira already uses for pages on `host`, or null. */
+export function confluenceAppId(existing, host) {
+  for (const link of existing || []) {
+    if (link?.application?.type !== CONFLUENCE_APP.type) continue;
+    const match = String(link.globalId || "").match(/^appId=([^&]+)&pageId=/);
+    if (match && hostOf(link.object?.url) === String(host).toLowerCase()) return match[1];
+  }
+  return null;
+}
+
+function specOf(input) {
+  return input?.analysisSpec || input || {};
+}
+
+/** The links the spec asks for, in a stable order, one per URL. */
+export function wantedLinks(input, { lang = "en" } = {}) {
+  const labels = LABELS[lang] || LABELS.en;
+  const spec = specOf(input);
+  const evidence = spec.evidence || {};
+  const wanted = [];
+  for (let frame of evidence.figma || []) {
+    if (!frame?.url) continue;
+    const fromUrl = figmaParts(frame.url);
+    frame = {
+      ...frame,
+      fileKey: frame.fileKey || fromUrl.fileKey,
+      nodeId: frame.nodeId || fromUrl.nodeId,
+    };
+    const nodeId = frame.nodeId ? String(frame.nodeId).replace(/-/g, ":") : null;
+    const name = frame.frames?.find((f) => f?.name)?.name;
+    const title = nodeId
+      ? name
+        ? `${labels.figma} · ${name} (${nodeId})`
+        : `${labels.figma} · ${nodeId}`
+      : `${labels.figma} · ${name || frame.fileKey || "design"}`;
+    const globalId =
+      frame.fileKey && nodeId
+        ? `ma-figma-${frame.fileKey}-${nodeId.replace(/:/g, "-")}`
+        : `ma-figma-${shortHash(normalizeUrl(frame.url))}`;
+    wanted.push({ kind: "figma", url: frame.url, title, relationship: labels.figma, globalId });
+  }
+  for (const page of evidence.confluence || []) {
+    if (!page?.url) continue;
+    const pageId = pageIdOf(page);
+    wanted.push({
+      kind: "confluence",
+      url: page.url,
+      title: page.title || `${labels.confluence} · ${pageId || hostOf(page.url)}`,
+      relationship: labels.confluence,
+      pageId,
+      globalId: `ma-confluence-${shortHash(normalizeUrl(page.url))}`,
+    });
+  }
+  for (const contract of evidence.swagger || []) {
+    if (!contract?.url) continue;
+    let leaf = hostOf(contract.url);
+    try {
+      leaf = new URL(contract.url).pathname.split("/").filter(Boolean).pop() || leaf;
+    } catch {
+      /* keep the host */
+    }
+    wanted.push({
+      kind: "api",
+      url: contract.url,
+      title: `API · ${leaf}`,
+      relationship: labels.api,
+      globalId: `ma-api-${shortHash(normalizeUrl(contract.url))}`,
+    });
+  }
+  for (const page of spec.outputs?.confluencePages || []) {
+    if (!page?.url) continue;
+    const pageId = pageIdOf(page);
+    wanted.push({
+      kind: "analysis",
+      url: page.url,
+      title: `${labels.analysis} · ${page.title || pageId || hostOf(page.url)}`,
+      relationship: labels.analysis,
+      pageId,
+      globalId: `ma-analysis-${shortHash(normalizeUrl(page.url))}`,
+    });
+  }
+  const seen = new Set();
+  return wanted.filter((link) => {
+    const key = normalizeUrl(link.url);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function payloadFor(link, appIdFor, lang) {
+  const labels = LABELS[lang] || LABELS.en;
+  const isPage = link.kind === "confluence" || link.kind === "analysis";
+  const appId = isPage && link.pageId ? appIdFor(hostOf(link.url)) : null;
+  if (appId) {
+    return {
+      globalId: `appId=${appId}&pageId=${link.pageId}`,
+      application: { ...CONFLUENCE_APP },
+      relationship: labels.wiki,
+      object: { url: link.url, title: link.title },
+    };
+  }
+  return {
+    globalId: link.globalId,
+    relationship: link.relationship,
+    object: { url: link.url, title: link.title },
+  };
+}
+
+function sameLink(a, b) {
+  return (
+    a.relationship === b.relationship &&
+    normalizeUrl(a.object?.url) === normalizeUrl(b.object?.url) &&
+    a.object?.title === b.object?.title
+  );
+}
+
+export function planRemoteLinks({ spec, existing = [], appId = null, lang = "en" }) {
+  const current = Array.isArray(existing) ? existing : [];
+  const byGlobalId = new Map(current.filter((l) => l?.globalId).map((l) => [l.globalId, l]));
+  // An explicit id belongs to one Confluence host, like one read from an existing link.
+  const at = typeof appId === "string" ? appId.indexOf("=") : -1;
+  const explicit = at > 0 ? [appId.slice(0, at), appId.slice(at + 1)] : null;
+  const appIdFor = (host) =>
+    explicit && explicit[0].toLowerCase() === host ? explicit[1] : confluenceAppId(current, host);
+  const write = [];
+  const skip = [];
+  const planned = new Set();
+  for (const link of wantedLinks(spec, { lang })) {
+    let payload = payloadFor(link, appIdFor, lang);
+    const target = normalizeUrl(link.url);
+    // A link this tool wrote earlier under its plain id stays the link for that URL:
+    // a global id cannot change without a delete, and nothing here deletes.
+    const ownPlain = current.find(
+      (l) =>
+        String(l?.globalId || "").startsWith("ma-") &&
+        l.globalId !== payload.globalId &&
+        normalizeUrl(l.object?.url) === target,
+    );
+    if (ownPlain)
+      payload = {
+        globalId: ownPlain.globalId,
+        relationship: link.relationship,
+        object: { url: link.url, title: link.title },
+      };
+    if (planned.has(payload.globalId)) {
+      skip.push({ globalId: payload.globalId, url: link.url, reason: "duplicate-global-id" });
+      continue;
+    }
+    planned.add(payload.globalId);
+    const own = byGlobalId.get(payload.globalId);
+    if (own) {
+      // Only an `ma-` link is ours to rewrite; a native Wiki Page link with the same id
+      // may be a person's, so it is left exactly as it is.
+      if (sameLink(own, payload))
+        skip.push({ globalId: payload.globalId, url: link.url, reason: "unchanged" });
+      else if (!String(own.globalId).startsWith("ma-"))
+        skip.push({ globalId: payload.globalId, url: link.url, reason: "already-linked" });
+      else write.push(payload);
+      continue;
+    }
+    const taken = current.some(
+      (l) => l?.globalId !== payload.globalId && normalizeUrl(l?.object?.url) === target,
+    );
+    if (taken) skip.push({ globalId: payload.globalId, url: link.url, reason: "already-linked" });
+    else write.push(payload);
+  }
+  return { write, skip };
+}
+
+function readJson(path, fallback) {
+  if (!path) return fallback;
+  if (!existsSync(path)) throw new Error(`no such file: ${path}`);
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+function main(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (
+      !["--spec", "--existing", "--app-id", "--lang"].includes(arg) ||
+      argv[i + 1] === undefined
+    ) {
+      process.stderr.write(`plan-remote-links: unknown or incomplete argument: ${arg}\n`);
+      return 2;
+    }
+    opts[arg.slice(2)] = argv[++i];
+  }
+  if (!opts.spec) {
+    process.stderr.write("plan-remote-links: --spec is required\n");
+    return 2;
+  }
+  let spec, existing;
+  try {
+    spec = readJson(opts.spec, {});
+    existing = readJson(opts.existing, []);
+  } catch (error) {
+    process.stderr.write(`plan-remote-links: ${error.message}\n`);
+    return 2;
+  }
+  const appId = opts["app-id"];
+  if (appId !== undefined && !(appId.indexOf("=") > 0 && appId.indexOf("=") < appId.length - 1)) {
+    process.stderr.write("plan-remote-links: --app-id must be <host>=<id>\n");
+    return 2;
+  }
+  if (appId) {
+    const host = appId.slice(0, appId.indexOf("=")).toLowerCase();
+    const hosts = wantedLinks(spec)
+      .filter((link) => link.pageId)
+      .map((link) => hostOf(link.url));
+    if (!hosts.includes(host))
+      process.stderr.write(`plan-remote-links: --app-id host ${host} matches no Confluence page\n`);
+  }
+  const plan = planRemoteLinks({
+    spec,
+    existing,
+    appId: opts["app-id"] || null,
+    lang: opts.lang || "en",
+  });
+  process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) process.exit(main(process.argv.slice(2)));