@mmerterden/multi-agent-pipeline 20.25.1 → 20.27.0

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.",
@@ -2098,6 +2148,42 @@
         "sha": { "type": "string" }
       }
     },
+    "jiraFamily": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "The issue family of a run that started from a Jira story or sub-task (multi-agent-refs/features/jira-family.md), written by Phase 0 from scripts/jira-family.mjs resolve and read by the channels Jira adapter. writes[] is the outcome of lib/jira-family-write.sh apply.",
+      "properties": {
+        "inputKey": { "type": ["string", "null"] },
+        "inputRole": { "enum": ["subtask", "story"] },
+        "storyKey": { "type": ["string", "null"] },
+        "devTaskKey": { "type": ["string", "null"] },
+        "devCandidates": { "type": "array", "items": { "type": "string" } },
+        "testTaskKey": { "type": ["string", "null"] },
+        "testCandidates": { "type": "array", "items": { "type": "string" } },
+        "storyFormat": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "status": { "enum": ["conforms", "nonconforming", "empty", "unknown", "not-a-story"] },
+            "reasons": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "writes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "issue", "status"],
+            "properties": {
+              "id": { "enum": ["story", "dev", "test", "story-tests"] },
+              "issue": { "type": "string" },
+              "status": { "enum": ["written", "exists", "skipped", "failed", "dry-run"] },
+              "reason": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
     "decisions": {
       "type": "array",
       "description": "Choices an autopilot run made where an attended run would have asked (multi-agent-refs/features/autopilot-decisions.md): parks (gate-ledger.mjs), blockers lowered to important (review-decision-gate.mjs), rework escalations (rework-escalation.mjs), pickers resolved without asking, split consensus taken on the triage verdict, a date-gate model fallback (decisions-log.mjs add). Written only while the quality gates are active. Rendered, redacted, in the Phase 5 report and appended to the autopilot PR body; an empty or absent list renders nothing.",

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,
@@ -2372,6 +2383,29 @@
               "type": "string",
               "default": "Blocks",
               "description": "The link type written from a prerequisite story to the story that depends on it (a `Depends on:` clause in the analysis document), by this site's name. The prerequisite is the link's source."
+            },
+            "familyWrites": {
+              "type": "boolean",
+              "default": true,
+              "description": "When a run starts from a Jira story or one of its sub-tasks, write to the whole family (features/jira-family.md): the story description reformatted into the story format, the Phase 5 comment on the development sub-task, the test scenarios on the test sub-task. false keeps the single Phase 5 comment on the issue the run started from."
+            },
+            "storyIssueTypes": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": [],
+              "description": "Issue type names, by this site's own name, that count as a story for the issue family: only such an issue's description is reformatted into the story format. Empty means storyIssueType (Story when unset)."
+            },
+            "testSubtaskTypes": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": [],
+              "description": "Sub-task type names, by this site's own name, that mark a test sub-task. Empty means discover: the project's sub-task types from createmeta whose name carries the word test (e.g. Sub Test Execution, Test Task)."
+            },
+            "devSubtaskTypes": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": [],
+              "description": "Sub-task type names that mark a development sub-task, used when a run starts from the story. Empty means a type whose name carries dev, development or geliştirme."
             }
           }
         },

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 {