@mmerterden/multi-agent-pipeline 20.25.1 → 20.27.0

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

@@ -0,0 +1,339 @@
+#!/usr/bin/env bash
+#
+# jira-family-write.sh  -  fetch the issue family of a Jira-started run, and
+# apply the writes scripts/jira-family.mjs planned for it.
+#
+# The planning half is offline and testable; this half is the one that talks
+# to Jira, so it stays small. Every write goes through jira-publish.sh, which
+# escapes the body, runs the outbound gate and backs a description up before it
+# replaces one. A write the plan marks `raw` (the story reformat: the author's
+# lines plus escaped macros) is sent with --raw, so the author's lines reach
+# Jira unchanged. Reads go through jira_api in _jira-auth.sh.
+#
+# A write is checked against the site right before it is sent:
+#   comment      skipped when a comment by the authenticated user on the issue
+#                already carries its marker
+#   description  skipped when the story already conforms, or when it changed
+#                since the plan read it (jira-publish.sh --expect-file)
+# so running the same plan twice writes nothing the second time.
+#
+# Usage, from a run (the state file is agent-state.json; the family's files go
+# to jira-family/ beside it):
+#   jira-family-write.sh resolve --state FILE
+#       fetch and resolve the family, record state.jiraFamily; no Jira write
+#   jira-family-write.sh plan --state FILE --dev-body FILE [--skip id,id]
+#                             [--dev-task KEY] [--test-task KEY] [--build TEXT]
+#       re-resolve and plan; run id, PR URL and mode come from the state
+#   jira-family-write.sh apply --state FILE [--dry-run]
+#       apply jira-family/plan.json, write jira-family/writes.json, merge it
+#       into state.jiraFamily.writes by write id
+#
+# Lower level:
+#   jira-family-write.sh fetch --issue KEY --out DIR
+#       DIR/input.json, DIR/story.json (the parent when KEY is a sub-task, else
+#       the same issue), DIR/site-types.txt (empty when unreadable)
+#   jira-family-write.sh apply --plan FILE [--state FILE] [--result FILE] [--dry-run]
+#       --state   the plan's autopilot decisions are recorded there
+#                 (decisions-log.mjs) once their write has gone out
+#       --result  the per-write outcome as JSON, written on every exit
+#
+# Exit: 0 done, 3 the input does not parse or the plan still has questions,
+#       4 auth (also when a write failed on auth), 5 a write failed (the others
+#       went out; --result lists which, and a re-run sends only what is missing),
+#       6 unattended (nothing read or written; the runner owns Jira),
+#       64 usage or a malformed issue key.
+
+set -uo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SELF_DIR/_jira-auth.sh"
+# shellcheck source=/dev/null
+. "$SELF_DIR/unattended.sh"
+
+USAGE="usage:
+  jira-family-write.sh resolve --state FILE
+  jira-family-write.sh plan --state FILE --dev-body FILE [--skip id,id] [--dev-task KEY] [--test-task KEY] [--build TEXT]
+  jira-family-write.sh apply --state FILE [--plan FILE] [--result FILE] [--dry-run]
+  jira-family-write.sh fetch --issue KEY --out DIR
+  jira-family-write.sh apply --plan FILE [--state FILE] [--result FILE] [--dry-run]"
+usage() { echo "$USAGE" >&2; exit 64; }
+
+CMD="${1:-}"; [ -n "$CMD" ] || usage; shift
+case "$CMD" in -h|--help) sed -n '2,45p' "$0"; exit 0 ;; esac
+ISSUE=""; OUT=""; PLAN=""; STATE=""; RESULT=""; DRY=0
+DEV_BODY=""; SKIP=""; DEV_TASK=""; TEST_TASK=""; BUILD=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) sed -n '2,45p' "$0"; exit 0 ;;
+    --dev-body) DEV_BODY="${2:-}"; shift 2 ;;
+    --skip) SKIP="${2:-}"; shift 2 ;;
+    --dev-task) DEV_TASK="${2:-}"; shift 2 ;;
+    --test-task) TEST_TASK="${2:-}"; shift 2 ;;
+    --build) BUILD="${2:-}"; shift 2 ;;
+    --issue) ISSUE="${2:-}"; shift 2 ;;
+    --out) OUT="${2:-}"; shift 2 ;;
+    --plan) PLAN="${2:-}"; shift 2 ;;
+    --state) STATE="${2:-}"; shift 2 ;;
+    --result) RESULT="${2:-}"; shift 2 ;;
+    --dry-run) DRY=1; shift ;;
+    *) usage ;;
+  esac
+done
+
+command -v jq >/dev/null 2>&1 || { echo "ERR: jq is required" >&2; exit 3; }
+
+FAMILY_MJS="$SELF_DIR/../scripts/jira-family.mjs"
+DECISIONS_MJS="$SELF_DIR/../scripts/decisions-log.mjs"
+PUBLISH="$SELF_DIR/jira-publish.sh"
+FIELDS="summary,issuetype,parent,subtasks,description,project,status"
+
+# A key goes into a REST path, so anything but a key is refused before use.
+valid_key() { printf '%s' "$1" | grep -Eq '^[A-Z][A-Z0-9_]+-[0-9]+$'; }
+
+# What a jira-publish.sh exit code means, for the result line.
+publish_reason() {
+  case "$1" in
+    4) echo "Jira host or token could not be resolved (exit 4)" ;;
+    5) echo "the Jira call failed (exit 5)" ;;
+    64) echo "refused before sending, e.g. by the outbound gate (exit 64): $2" ;;
+    *) echo "jira-publish.sh exit $1: $2" ;;
+  esac
+}
+
+fetch_issue() {  # fetch_issue <key> <file>
+  jira_api GET "/rest/api/2/issue/$1?fields=$FIELDS" > "$2" 2>/dev/null || return 5
+  jq -e '.key' "$2" >/dev/null 2>&1 || return 5
+}
+
+do_fetch() {  # do_fetch <key> <dir>
+  local issue="$1" out="$2" parent project
+  valid_key "$issue" || { echo "ERR: not an issue key: $issue" >&2; return 64; }
+  if ma_unattended; then
+    echo "unattended run: the family is not read here; the runner owns Jira" >&2
+    return 6
+  fi
+  jira_auth_resolve || return 4
+  mkdir -p "$out"
+  fetch_issue "$issue" "$out/input.json" || { echo "ERR: could not read $issue" >&2; return 5; }
+  parent="$(jq -r 'if .fields.issuetype.subtask == true then .fields.parent.key // empty else empty end' "$out/input.json")"
+  if [ -n "$parent" ] && ! valid_key "$parent"; then
+    echo "WARN: the parent key does not look like a key: $parent" >&2; parent=""
+  fi
+  if [ -n "$parent" ]; then
+    fetch_issue "$parent" "$out/story.json" || { echo "WARN: could not read the parent $parent" >&2; rm -f "$out/story.json"; }
+  else
+    cp "$out/input.json" "$out/story.json"
+  fi
+  project="$(jq -r '.fields.project.key // empty' "$out/input.json")"
+  [ -n "$project" ] || project="${issue%%-*}"
+  bash "$SELF_DIR/analysis-jira-write.sh" --subtask-types --project "$project" \
+    > "$out/site-types.txt" 2>/dev/null || : > "$out/site-types.txt"
+  echo "fetched $issue${parent:+ (story $parent)} into $out"
+}
+
+# The run's own files: the issue key and the family directory beside agent-state.json.
+state_key() { jq -r '.jiraId // .taskId // empty' "$STATE"; }
+family_dir() { printf '%s/jira-family' "$(cd "$(dirname "$STATE")" && pwd)"; }
+
+do_resolve() {  # fetch, resolve, and record state.jiraFamily; asks and writes nothing in Jira
+  local key dir story=""
+  key="$(state_key)"; dir="$(family_dir)"
+  do_fetch "$key" "$dir" >/dev/null || return $?
+  [ -f "$dir/story.json" ] && story="--story $dir/story.json"
+  # shellcheck disable=SC2086
+  node "$FAMILY_MJS" resolve --input "$dir/input.json" $story \
+    --site-types "$dir/site-types.txt" > "$dir/family.json" || return 3
+}
+
+if [ "$CMD" = "fetch" ]; then
+  [ -n "$ISSUE" ] && [ -n "$OUT" ] || usage
+  do_fetch "$ISSUE" "$OUT"
+  exit $?
+fi
+
+WRITE_STATE="$SELF_DIR/../scripts/write-state.mjs"
+
+if [ "$CMD" = "resolve" ]; then
+  [ -n "$STATE" ] && [ -f "$STATE" ] || usage
+  do_resolve || exit $?
+  DIR="$(family_dir)"
+  jq -n --slurpfile f "$DIR/family.json" --slurpfile s "$STATE" \
+    '{jiraFamily: ($f[0].stateEntry + {writes: ($s[0].jiraFamily.writes // [])})}' \
+    | node "$WRITE_STATE" "$STATE" || exit 3
+  jq -r '"family: story \(.stateEntry.storyKey), dev \(.stateEntry.devTaskKey // "-"), test \(.stateEntry.testTaskKey // "-"), story format \(.stateEntry.storyFormat.status)"' "$DIR/family.json"
+  exit 0
+fi
+
+if [ "$CMD" = "plan" ]; then
+  [ -n "$STATE" ] && [ -f "$STATE" ] && [ -n "$DEV_BODY" ] && [ -f "$DEV_BODY" ] || usage
+  do_resolve || exit $?
+  DIR="$(family_dir)"
+  RUN_ID="$(jq -r '"\(.taskId)-\(.shortId // 0)"' "$STATE")"
+  PR_URL="$(jq -r '.pr.url // .projects[0].pr.url // empty' "$STATE")"
+  MODE="$(jq -r 'if .autopilot == true then "autopilot" else "interactive" end' "$STATE")"
+  set -- --family "$DIR/family.json" --dev-body "$DEV_BODY" --run-id "$RUN_ID" --mode "$MODE"
+  [ -z "$PR_URL" ] || set -- "$@" --pr-url "$PR_URL"
+  [ -z "$BUILD" ] || set -- "$@" --build "$BUILD"
+  [ -z "$SKIP" ] || set -- "$@" --skip "$SKIP"
+  [ -z "$DEV_TASK" ] || set -- "$@" --dev-task "$DEV_TASK"
+  [ -z "$TEST_TASK" ] || set -- "$@" --test-task "$TEST_TASK"
+  node "$FAMILY_MJS" plan "$@" > "$DIR/plan.json" || exit 3
+  jq -r '.confirm, (.skipped[] | "  not written: \(.id) (\(.reason))"), (.questions[] | "  question \(.id): \(.question) [\(.options | join(", "))]")' "$DIR/plan.json"
+  echo "plan: $DIR/plan.json"
+  exit 0
+fi
+
+[ "$CMD" = "apply" ] || usage
+MERGE=0
+if [ -z "$PLAN" ] && [ -n "$STATE" ] && [ -f "$STATE" ]; then
+  PLAN="$(family_dir)/plan.json"
+  [ -n "$RESULT" ] || RESULT="$(family_dir)/writes.json"
+  MERGE=1
+fi
+[ -n "$PLAN" ] && [ -f "$PLAN" ] || usage
+
+# Every exit leaves a result file, so the caller's follow-up never reads nothing.
+early_exit() {  # early_exit <code> <status> <reason>
+  if [ -n "$RESULT" ]; then
+    jq -c --arg s "$2" --arg r "$3" '[.writes[]? | {id, issue, status: $s, reason: $r}]' "$PLAN" \
+      > "$RESULT" 2>/dev/null || echo '[]' > "$RESULT"
+  fi
+  exit "$1"
+}
+if ma_unattended; then
+  echo "unattended run: the family writes are left to the runner" >&2
+  early_exit 6 skipped "unattended run: left to the runner"
+fi
+jq -e . "$PLAN" >/dev/null 2>&1 || { echo "ERR: the plan does not parse: $PLAN" >&2; early_exit 3 failed "the plan does not parse"; }
+if [ "$(jq -r '.ready' "$PLAN")" != "true" ]; then
+  echo "ERR: the plan still has open questions ($(jq -r '[.questions[].id] | join(", ")' "$PLAN")); answer them and re-plan" >&2
+  early_exit 3 skipped "the plan still has open questions"
+fi
+[ "$DRY" -eq 1 ] || jira_auth_resolve || exit 4
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+RESULTS="$WORK/results.jsonl"; : > "$RESULTS"
+ME=""
+RC=0
+
+record() {  # record <id> <issue> <status> <reason>
+  jq -cn --arg i "$1" --arg k "$2" --arg s "$3" --arg r "$4" \
+    '{id: $i, issue: $k, status: $s, reason: $r}' >> "$RESULTS"
+  printf '  %-8s %-12s %s%s\n' "$3" "$1" "$2" "${4:+  ($4)}"
+}
+
+fail_rc() {  # an auth failure (4) outranks any other failure (5) in the exit code
+  if [ "$1" -eq 4 ]; then RC=4; elif [ "$RC" -ne 4 ]; then RC=5; fi
+}
+
+record_decisions() {  # record_decisions <writeId>, or "" for the decisions that made no write
+  [ -n "$STATE" ] || return 0
+  jq -c --arg w "$1" '.decisions[]? | select(if $w == "" then .writeId == null else .writeId == $w end)' "$PLAN" | while IFS= read -r d; do
+    node "$DECISIONS_MJS" add --state "$STATE" \
+      --what "$(printf '%s' "$d" | jq -r .what)" \
+      --why "$(printf '%s' "$d" | jq -r .why)" \
+      --cost-if-wrong "$(printf '%s' "$d" | jq -r .costIfWrong)" \
+      --phase "$(printf '%s' "$d" | jq -r .phase)" >/dev/null 2>&1 \
+      || echo "  WARN: could not record the decision for $1" >&2
+  done
+}
+
+echo "jira-family: $(jq -r '.confirm' "$PLAN")$([ "$DRY" -eq 1 ] && echo "  (dry run)")"
+N="$(jq '.writes | length' "$PLAN")"
+i=0
+while [ "$i" -lt "$N" ]; do
+  W="$(jq -c ".writes[$i]" "$PLAN")"
+  i=$((i + 1))
+  id="$(printf '%s' "$W" | jq -r .id)"
+  kind="$(printf '%s' "$W" | jq -r .kind)"
+  issue="$(printf '%s' "$W" | jq -r .issue)"
+  printf '%s' "$W" | jq -j .body > "$WORK/body.txt"
+  if ! valid_key "$issue"; then
+    record "$id" "$issue" "failed" "not an issue key"; RC=5; continue
+  fi
+  if [ "$DRY" -eq 1 ]; then
+    record "$id" "$issue" "dry-run" "$kind"
+    continue
+  fi
+  if [ "$kind" = "comment" ]; then
+    mark="$(printf '%s' "$W" | jq -r .marker)"
+    if ! jira_api GET "/rest/api/2/issue/$issue/comment?maxResults=1000" > "$WORK/comments.json" 2>/dev/null \
+        || ! jq -e '.comments' "$WORK/comments.json" >/dev/null 2>&1; then
+      record "$id" "$issue" "failed" "could not read the comments"; RC=5; continue
+    fi
+    if [ -z "$ME" ]; then
+      jira_api GET "/rest/api/2/myself" > "$WORK/me.json" 2>/dev/null || :
+      ME="$(jq -c '{name, key, accountId} | with_entries(select(.value != null))' "$WORK/me.json" 2>/dev/null || echo "")"
+    fi
+    if [ -z "$ME" ] || [ "$ME" = "{}" ]; then
+      ME=""; record "$id" "$issue" "failed" "could not read the authenticated user"; RC=5; continue
+    fi
+    # Only our own comments count: another user can paste a marker, and it
+    # must not be able to stop this one from being posted.
+    seen="$(jq --arg m "$mark" --argjson me "$ME" '[.comments[]?
+      | select((.author // {}) as $a | any($me | to_entries[]; $a[.key] == .value))
+      | .body // "" | select(contains($m))] | length' "$WORK/comments.json")"
+    if [ "${seen:-0}" -gt 0 ]; then
+      record "$id" "$issue" "exists" "already posted by this run"; continue
+    fi
+    bash "$PUBLISH" --issue "$issue" --body-file "$WORK/body.txt" --target comment >/dev/null 2>"$WORK/err.txt"
+    prc=$?
+    if [ "$prc" -eq 0 ]; then
+      record "$id" "$issue" "written" ""
+      record_decisions "$id"
+    else
+      record "$id" "$issue" "failed" "$(publish_reason "$prc" "$(head -1 "$WORK/err.txt")")"
+      fail_rc "$prc"
+    fi
+    continue
+  fi
+  # description
+  if ! jira_api GET "/rest/api/2/issue/$issue?fields=description" > "$WORK/current.json" 2>/dev/null \
+      || ! jq -e '.fields' "$WORK/current.json" >/dev/null 2>&1; then
+    record "$id" "$issue" "failed" "could not read the description"; RC=5; continue
+  fi
+  jq -j '.fields.description // ""' "$WORK/current.json" > "$WORK/current.txt"
+  printf '%s' "$W" | jq -j '.original // ""' > "$WORK/original.txt"
+  jq '{global: {issueTree: (if .storyPanels == null then {} else {storyPanels: .storyPanels} end)}}' \
+    "$PLAN" > "$WORK/plan-prefs.json"
+  if node "$FAMILY_MJS" check --description "$WORK/current.txt" --prefs "$WORK/plan-prefs.json" >/dev/null 2>&1; then
+    record "$id" "$issue" "exists" "already in the story format"; continue
+  fi
+  if ! cmp -s "$WORK/current.txt" "$WORK/original.txt"; then
+    record "$id" "$issue" "skipped" "the description changed since the preview"; continue
+  fi
+  raw=""
+  [ "$(printf '%s' "$W" | jq -r '.raw == true')" = "true" ] && raw="--raw"
+  bash "$PUBLISH" --issue "$issue" --body-file "$WORK/body.txt" --target description \
+    --mode replace --confirm-overwrite --expect-file "$WORK/original.txt" $raw >/dev/null 2>"$WORK/err.txt"
+  prc=$?
+  if [ "$prc" -eq 0 ]; then
+    record "$id" "$issue" "written" "previous text backed up"
+    record_decisions "$id"
+  elif [ "$prc" -eq 6 ]; then
+    record "$id" "$issue" "skipped" "the description changed since the preview"
+  else
+    record "$id" "$issue" "failed" "$(publish_reason "$prc" "$(head -1 "$WORK/err.txt")")"
+    fail_rc "$prc"
+  fi
+done
+
+[ "$DRY" -eq 1 ] || record_decisions ""
+[ -z "$RESULT" ] || jq -s '.' "$RESULTS" > "$RESULT"
+# Merged by write id: a re-run that finds a comment already there ("exists")
+# keeps the earlier "written" record instead of replacing it.
+if [ "$MERGE" -eq 1 ] && [ "$DRY" -eq 0 ]; then
+  jq -n --slurpfile s "$STATE" --slurpfile n "$RESULT" '
+    ($s[0].jiraFamily // {}) as $f
+    | ($f.writes // []) as $old
+    | ($n[0] | map({(.id): .}) | add // {}) as $new
+    | ($old | map(.id)) as $oldIds
+    | {jiraFamily: ($f + {writes: (
+        [$old[] | . as $o | ($new[$o.id] // null) as $x
+          | if $x == null or ($o.status == "written" and $x.status == "exists") then $o else $x end]
+        + [$n[0][] | select(.id as $i | $oldIds | index($i) | not)])})}' \
+    | node "$WRITE_STATE" "$STATE" >/dev/null || echo "  WARN: could not record the writes in $STATE" >&2
+fi
+exit "$RC"

package/pipeline/lib/jira-publish.sh

@@ -19,6 +19,8 @@
 #                   [--mode append|replace]          (description only, default: append)
 #                   [--confirm-overwrite]            (required for mode=replace on a non-empty field)
 #                   [--backup-dir DIR]
+#                   [--raw]                          (body is already Jira wiki markup; no emoticon escape)
+#                   [--expect-file FILE]             (description only: write only if it still equals FILE)
 #                   [--dry-run]
 #
 # Resolution:
@@ -29,6 +31,9 @@
 #
 # Every body is run through scripts/jira-wiki-escape.mjs before it is sent, so
 # Jira cannot manufacture an emoticon out of a Swift selector or a table cell.
+# --raw skips that one step for a body built only from text the author already
+# wrote in Jira markup plus macros the caller escaped itself (the story reformat
+# of lib/jira-family-write.sh); the outbound gate and the backup still apply.
 #
 # Exit codes:
 #   0  published (or, with --dry-run, previewed)
@@ -36,6 +41,8 @@
 #      --confirm-overwrite was given. The backup is already on disk.
 #   4  host or token could not be resolved
 #   5  a Jira API call failed
+#   6  refused: --expect-file no longer matches the description (someone
+#      edited it after the caller read it). Nothing was written.
 #  64  usage error
 
 set -euo pipefail
@@ -91,6 +98,8 @@ TARGET="comment"
 MODE="append"
 CONFIRM=0
 DRY_RUN=0
+RAW=0
+EXPECT=""
 BACKUP_DIR="${JIRA_BACKUP_DIR:-$HOME/.claude/logs/multi-agent/jira-backups}"
 
 die() { echo "$1" >&2; exit "${2:-64}"; }
@@ -106,6 +115,8 @@ while [ "$#" -gt 0 ]; do
     --backup-dir) need_value "$@"; BACKUP_DIR="$2"; shift 2 ;;
     --confirm-overwrite) CONFIRM=1; shift ;;
     --dry-run) DRY_RUN=1; shift ;;
+    --raw) RAW=1; shift ;;
+    --expect-file) need_value "$@"; EXPECT="$2"; shift 2 ;;
     -h|--help) sed -n '2,40p' "$0"; exit 0 ;;
     *) die "unknown argument: $1" ;;
   esac
@@ -148,7 +159,16 @@ api() { "$CURL" -sS -m 30 -K <(auth_cfg "$TOKEN") -H "Content-Type: application/
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
 
-node "$ESCAPER" "$BODY_FILE" > "$WORK/new.txt"
+if [ "$RAW" = "1" ]; then
+  cp "$BODY_FILE" "$WORK/new.txt"
+else
+  node "$ESCAPER" "$BODY_FILE" > "$WORK/new.txt"
+fi
+# An escaper that printed nothing for a body that has text would post an empty
+# comment or blank a description; that is refused, never sent.
+if [ -s "$BODY_FILE" ] && [ ! -s "$WORK/new.txt" ]; then
+  die "the escaped body came out empty; nothing was posted" 5
+fi
 
 if [ "$TARGET" = "comment" ]; then
   if [ "$DRY_RUN" = "1" ]; then
@@ -175,6 +195,13 @@ case "$http" in
   *) echo "could not read the current description of $ISSUE (HTTP $http)" >&2; exit 5 ;;
 esac
 jq -r '.fields.description // ""' "$WORK/issue.json" > "$WORK/existing.txt"
+if [ -n "$EXPECT" ]; then
+  jq -j '.fields.description // ""' "$WORK/issue.json" > "$WORK/existing-exact.txt"
+  if ! cmp -s "$WORK/existing-exact.txt" "$EXPECT"; then
+    echo "REFUSED: the description of $ISSUE changed since it was read; nothing was written." >&2
+    exit 6
+  fi
+fi
 
 existing_bytes=$(wc -c < "$WORK/existing.txt" | tr -d ' ')
 existing_lines=$(grep -c . "$WORK/existing.txt" || true)

package/pipeline/lib/jira-remote-links.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+#
+# jira-remote-links.sh  -  read and write a Jira issue's Issue Links (remote links).
+#
+# Usage:
+#   jira-remote-links.sh list  <ISSUE>              # current remote links, JSON array
+#   jira-remote-links.sh apply <ISSUE> <plan.json> [--dry-run]
+#
+# `plan.json` is what `scripts/plan-remote-links.mjs` prints: {"write": [...], "skip": [...]}.
+# `apply` POSTs each `write` entry to /rest/api/2/issue/<ISSUE>/remotelink. Jira treats a
+# POST whose globalId already exists on the issue as an update, so a re-run rewrites the
+# same link instead of adding a second one. This file never deletes a link: the planner
+# decides what is written, and a link nobody planned stays as it is.
+#
+# Output of apply: one line per entry, `written <globalId>` or `failed <globalId> <http status>`,
+# then `skipped <globalId> <reason>` for each skip. Exit 0 when every write succeeded, 1 when
+# any failed (the rest are still attempted), 2 on a usage error, 3 when jq is missing, 4 when
+# host or token did not resolve.
+#
+# Host and token resolve through `_jira-auth.sh`; the token reaches curl only through a -K
+# config on process substitution, never argv or a log.
+
+set -uo pipefail
+
+usage() {
+  echo "usage: jira-remote-links.sh list <ISSUE> | apply <ISSUE> <plan.json> [--dry-run]" >&2
+  exit 2
+}
+
+[ $# -ge 2 ] || usage
+CMD="$1"
+ISSUE="$2"
+[[ "$ISSUE" =~ ^[A-Z][A-Z0-9]*-[0-9]+$ ]] || { echo "jira-remote-links: not an issue key: $ISSUE" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "jira-remote-links: jq not found" >&2; exit 3; }
+
+# shellcheck source=_jira-auth.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/_jira-auth.sh"
+
+case "$CMD" in
+  list)
+    jira_auth_resolve || exit $?
+    body="$(jira_api GET "/rest/api/2/issue/${ISSUE}/remotelink" -w '\n%{http_code}')"
+    code="${body##*$'\n'}"
+    body="${body%$'\n'*}"
+    if [ "$code" != "200" ]; then
+      echo "jira-remote-links: list failed for $ISSUE (HTTP $code)" >&2
+      exit 1
+    fi
+    printf '%s' "$body" | jq -c 'if type == "array" then . else [] end' 2>/dev/null || {
+      echo "jira-remote-links: list for $ISSUE did not return JSON" >&2
+      exit 1
+    }
+    ;;
+  apply)
+    PLAN="${3:-}"
+    [ -n "$PLAN" ] && [ -f "$PLAN" ] || usage
+    DRY=0
+    # A misspelled safety flag must not turn into a real write.
+    case "$#:${4:-}" in
+      3:) ;;
+      4:--dry-run) DRY=1 ;;
+      *) usage ;;
+    esac
+    jq -e '(.write | type) == "array"' "$PLAN" >/dev/null 2>&1 || { echo "jira-remote-links: $PLAN has no write list" >&2; exit 2; }
+    # An unattended run posts nothing outside the machine; this write is no exception.
+    if [ "$DRY" -eq 0 ] && [ "${MULTI_AGENT_UNATTENDED:-0}" = "1" ]; then
+      jq -r '.write[]? | "skipped \(.globalId) unattended"' "$PLAN"
+      exit 0
+    fi
+    if [ "$DRY" -eq 0 ]; then
+      jira_auth_resolve || exit $?
+    fi
+    RC=0
+    count="$(jq '.write | length' "$PLAN")"
+    i=0
+    while [ "$i" -lt "$count" ]; do
+      entry="$(jq -c ".write[$i]" "$PLAN")"
+      gid="$(printf '%s' "$entry" | jq -r '.globalId // empty')"
+      i=$((i + 1))
+      if [ -z "$gid" ] || [ -z "$(printf '%s' "$entry" | jq -r '.object.url // empty')" ]; then
+        echo "failed ${gid:-<no-globalId>} invalid-entry"
+        RC=1
+        continue
+      fi
+      if [ "$DRY" -eq 1 ]; then
+        echo "would-write $gid"
+        continue
+      fi
+      code="$(jira_api POST "/rest/api/2/issue/${ISSUE}/remotelink" --data-binary @<(printf '%s' "$entry") -o /dev/null -w '%{http_code}')"
+      case "$code" in
+        200 | 201) echo "written $gid" ;;
+        *) echo "failed $gid $code"; RC=1 ;;
+      esac
+    done
+    jq -r '.skip[]? | "skipped \(.globalId) \(.reason)"' "$PLAN"
+    exit "$RC"
+    ;;
+  *) usage ;;
+esac

package/pipeline/multi-agent-refs/analysis/intake.md

@@ -212,6 +212,8 @@ Q7: header="Firebase"
     (Other: comma-separated mix of event names like 'profile.view,profile.opened', a /path/to/events.json, or a console.firebase.google.com URL)
 ```
 
+**Issue Links of a Q4 issue are sources:** `features/analysis-issue-links.md`, "Reading an issue's links at intake".
+
 After each batch is submitted, pipe every Other-provided string into
 `~/.claude/lib/context-link-extractor.sh` on **stdin** (`printf '%s' "$answer" | ~/.claude/lib/context-link-extractor.sh`)  -  it takes no argv, and an
 argv call silently returns `[]` rather than erroring. Results are typed and written to `state.analysisSpec.contextLinks[]`. Standards-question entries are additionally tagged `binding: true` so Phase 2 Section 7 treats them as hard constraints (see the Phase 1 type table and the Phase 2 Section 7 row).

package/pipeline/multi-agent-refs/analysis/render.md

@@ -137,9 +137,11 @@ Iterate `state.analysisSpec.outputs.requested`. For each target:
 
 | Target | Action |
 |--------|--------|
-| Local | For each per-platform draft, `cp /tmp/analysis-<feature-slug>-<ts>/<feature>-<platform>.md` into `analysis/<feature>-<platform>.md` in the matching repo's working tree. When multiple repos exist for the same platform, the file is duplicated into each and the dispatch report lists every destination. **When no repo was selected** (Locked 34) there is no working tree to be relative to, so files land in `~/Desktop/multiAgentAnalysis/<feature-name>/`, one per derived channel (`<feature>-mobile.md`, `<feature>-web.md`) or a single `<feature>.md` when none could be derived. The current working directory is never written to: for a repo-less run it is arbitrary, and creating a folder in whatever directory the command happened to be invoked from is the kind of surprise that costs a tool its trust. The user can override the path through the picker's Other input. **No commit.** |
+| Local | For each per-platform draft, `cp /tmp/analysis-<feature-slug>-<ts>/<feature>-<platform>.md` into `analysis/<feature>-<platform>.md` in the matching repo's working tree. When multiple repos exist for the same platform, the file is duplicated into each and the dispatch report lists every destination. **When no repo was selected** (Locked 34) there is no working tree to be relative to, so files land in `~/Desktop/multiAgentAnalysis/<feature-name>/`, one per derived channel (`<feature>-mobile.md`, `<feature>-web.md`) or a single `<feature>.md` when none could be derived. The current working directory is never written to: for a repo-less run it is arbitrary. The user can override the path through the picker's Other input. **No commit.** |
 | Confluence | Re-humanize each draft with `formal-stakeholder` tone. One page per draft under the chosen parent, titled `<Feature> - <Platform>` - including a repo-less run, whose drafts are the derived channels (`<Feature> - Mobile` / `<Feature> - Web`, Locked 34). A single channel-agnostic draft becomes one page titled `<Feature>`, with no suffix implying a split that was not made. Cross-link siblings inside each page via `<ac:link><ri:page ri:content-title="<Feature> - <OtherPlatform>"/></ac:link>`; a lone page has no sibling block. Markdown -> storage XML via `$HOME/.claude/multi-agent-refs/channels/confluence.md`. Re-emit on existing pages uses PUT with version bump. |
-| Jira | Re-humanize the combined body with `informal-technical` tone. Concatenate the drafts under `h2. Platform: <X>` separators in production order - `iOS`, `Android`, `Web`, `Backend` repo-backed, `Mobile` / `Web` for channels derived on a repo-less run (Locked 34). A single channel-agnostic draft gets no separator: a heading announcing a split of one is noise. then run the whole body through the markdown → Jira wiki conversion table in `$HOME/.claude/multi-agent-refs/channels/jira.md`  -  both the comment body and the `description` field render wiki markup, so raw `##`/`**`/backticks arrive as literal text. Write the converted body to a file and publish it with `$HOME/.claude/lib/jira-publish.sh`, never with a hand-rolled `curl`: <br><br>`bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" --target comment` <br>`bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" --target description --mode append` <br><br>The script owns the parts that are easy to get wrong: it runs `jira-wiki-escape.mjs` on the body, resolves host + token without putting either in argv, and on the description path it GETs the current value, writes it to a backup under `~/.claude/logs/multi-agent/jira-backups/` and reports the path, appends below a `----` rule by default, and **refuses with exit 3** when `--mode replace` would discard a non-empty description unless `--confirm-overwrite` is passed. Exit 3 is reported to the user with the backup path, never retried with the flag added automatically  -  only the user's explicit "Description - replace" answer from Phase 3.5 supplies it. `--dry-run` previews the exact final body without writing. |
+| Jira | Re-humanize the combined body with `informal-technical` tone. Concatenate the drafts under `h2. Platform: <X>` separators in production order - `iOS`, `Android`, `Web`, `Backend` repo-backed, `Mobile` / `Web` for channels derived on a repo-less run (Locked 34). A single channel-agnostic draft gets no separator: a heading announcing a split of one is noise. then run the whole body through the markdown → Jira wiki conversion table in `$HOME/.claude/multi-agent-refs/channels/jira.md`  -  both the comment body and the `description` field render wiki markup, so raw `##`/`**`/backticks arrive as literal text. Write the converted body to a file; it is published by step 3 there, with `$HOME/.claude/lib/jira-publish.sh`, never with a hand-rolled `curl`: <br><br>`bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" --target comment` <br>`bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" --target description --mode append` <br><br>The script runs `jira-wiki-escape.mjs`, keeps host and token out of argv, and on the description path backs the current value up under `~/.claude/logs/multi-agent/jira-backups/` (path reported), appends below a `----` rule by default, and **refuses with exit 3** when `--mode replace` would discard a non-empty description unless `--confirm-overwrite` is passed. Exit 3 is reported with the backup path, never retried with the flag added: only the user's explicit "Description - replace" answer from Phase 3.5 supplies it. `--dry-run` previews the exact final body without writing. |
+
+**Jira write and Issue Links:** `$HOME/.claude/multi-agent-refs/features/analysis-issue-links.md`. Nothing reaches Jira before approval.
 
 **Output capture**: fill `state.analysisSpec.outputs.localPaths[]` (one entry per per-platform-per-repo write, or one per derived channel on a repo-less run), `outputs.confluencePageUrls[]` (one entry per emitted document), `outputs.confluencePages[]` (the same pages by IDENTITY - `pageId`, `title`, `space`, `channel` - because a write-back needs the id and a `/display/SPACE/Title` URL cannot be parsed for one), `outputs.jiraIssueKey` (single string).
 

package/pipeline/multi-agent-refs/channels/jira.md

@@ -22,8 +22,9 @@ Every Jira comment posted by this adapter follows the same section order. Sectio
 |---|---|---|---|---|
 | 1 | `summary` | `## Geliştirme Özeti` | `## Development Summary` | always |
 | 2 | `test_scenarios` | `## Test Senaryoları` | `## Test Scenarios` | always (use " - " placeholder line if truly N/A) |
-| 3 | `impact` | `## Etki Analizi` | `## Impact Analysis` | always |
-| 4 | `context_refs` | `## Bağlantılar` | `## References` | when any link exists |
+| 3 | `test_run` | `## Test Koşumu` | `## Test Run` | when "Test Koşumu (Xray)" content is selected |
+| 4 | `impact` | `## Etki Analizi` | `## Impact Analysis` | always |
+| 5 | `context_refs` | `## Bağlantılar` | `## References` | when any link exists |
 
 > Heading levels in the source markdown are `##`. The wiki-markup converter (next section) rewrites them to `h2.` for Jira rendering.
 
@@ -44,10 +45,9 @@ it is the PR body (`channels/pr.md`).
 
 **Visual evidence inside these sections.** When `state.visualEvidence` carries artefacts, they render INSIDE `summary` and `test_scenarios` - never as a section of their own, which the fixed section order forbids. Phase 4 Step 2.9 has already uploaded them and written the returned name to `visualEvidence.*[].jiraFilename`: reference that name, and call `jira-attach.sh <issue> <file>...` only for an artefact whose `jiraFilename` is absent. Uploading unconditionally here attaches every file a second time whenever the comment is re-rendered - which is exactly what a post-hoc `/multi-agent:channels` run does.
 
-- `summary`, after its sentences: one line naming the pair in `outputLanguage` (`Düzeltme öncesi / Düzeltme sonrası`), then the thumbnails on the next line - `!<file>-before.png|thumbnail! !<file>-after.png|thumbnail!`.
-- `test_scenarios`, under the scenario the recording demonstrates: `!<file>-flow.mp4!` plus one line stating the tier used.
+- The lines come from `scripts/render-jira-evidence.mjs` (`features/visual-evidence.md` section 6): in `summary` the before/after line, under each scenario in `test_scenarios` its evidence line (`Kanıt: Ekran [<file>](<url>) · Kayıt [<file>](<url>)`), plus the flow recording line. Links are the default; `prefs.global.visualEvidence.jiraMedia: thumbnails` embeds images as `|thumbnail` instead. A full-size `!<file>!` embed is never written, and recordings are always links.
 
-A `gaps[]` entry prints its reason on the line where the artefact would have been (`Düzeltme öncesi: ticket'ta görsel yok`). Never an empty thumbnail, never a silent omission. Contract: `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
+Each `gaps[]` line the renderer prints (`Önce: yok - <reason>`) goes where the artefact would have been. Never an empty thumbnail, never a silent omission. After `jira-attach.sh` uploads a missing artefact, its printed name and URL are written back to that artefact's `jiraFilename` and `url` before rendering. Contract: `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
 
 **`test_scenarios`**  -  one titled scenario per acceptance criterion, each a
 numbered list of steps ending in the expected result. Not Given/When/Then: it
@@ -104,6 +104,8 @@ written in the same plain register as the rest of the comment:
 Part 4 is answered "none" far more often than it is answered at all, and "none" is
 a real answer worth writing: it is what lets the reader stop looking.
 
+**`test_run`**  -  the block `render-flow-run.mjs --heading-level 2` prints, unedited: the Xray Test Execution per domain, the Test Set / Plan, the run, the result counts and one row per scenario. It sits right after `test_scenarios` because it is the evidence for them. The renderer is the only source: a key that is not in the run history's delivery line is not written, and an undelivered run says so (`channels/test-run.md`). This section is the one exception to the no-identifiers rule above: execution, test and run ids, and the run's commit and branch, are what QA clicks through, not code.
+
 **`context_refs`**  -  flat bullet list of external links the work depends on or produced. PR URL is **not** repeated here; it lives on the first line (see *Cross-link injection*). Common entries (only when present in the task):
 
 ```markdown
@@ -122,8 +124,8 @@ The links are pulled from `agent-state.json.contextLinks[]` (see Phase 0 link ex
 
 ```
 1. Read agent-state.json (taskId, contextLinks, prUrls, language).
-2. Build section bodies in markdown, in table order: summary, test_scenarios, impact, context_refs.
-3. Run the assembled body through the `humanizer` skill (see Hard rules below).
+2. Build section bodies in markdown, in table order: summary, test_scenarios, test_run, impact, context_refs.
+3. Run the assembled body through the `humanizer` skill (see Hard rules below). The `test_run` block and the evidence lines pass through verbatim, like code: they are rendered by scripts, and a reworded key or link is a wrong one.
 4. Apply Cross-link injection (PR URL on line 1).
 5. Run Wiki markup conversion.
 6. Run the emoticon escape program on the converted body (see *Emoticon escaping*).
@@ -232,6 +234,8 @@ Jira's wiki renderer turned it into an emoticon, which is what section
 *Emoticon escaping* below is about. A defence that has to be invoked by hand is
 a defence that is eventually not invoked.
 
+A run with `state.jiraFamily` posts this body on the development sub-task, plus a test comment on the test sub-task: `features/jira-family.md`.
+
 The dispatch summary line includes the comment URL with `?focusedCommentId=...` so the user can paste it into Slack/Teams.
 
 ### Writing the issue description (not a comment)
@@ -253,7 +257,7 @@ When the **Wiki** adapter writes pages on the same run AND `prefs.global.wikiToJ
 
 - Real newlines, no HTML entities  -  heredoc + `jq --rawfile` + `curl --data-binary @file`.
 - UTF-8 in, UTF-8 out  -  the body file is UTF-8 and `--data-binary` ships its bytes verbatim. Never round-trip the body through `unicode_escape`, `latin-1`, or any re-encode step, and never hand-roll a Python/curl helper that re-decodes it: that mangles Turkish chars (ç ş ı ö ü ğ) into mojibake (`Çözüm` → `Ãözüm`). Use the `jq --rawfile` + `--data-binary @file` path above as-is. Same rule for the PR / Confluence / Wiki adapters.
-- Section order is fixed: `summary` → `test_scenarios` → `context_refs`. Never insert sections between them; never reorder.
+- Section order is fixed: `summary` → `test_scenarios` → `test_run` → `impact` → `context_refs`. Never insert other sections between them; never reorder.
 - Humanizer pass runs **after** body assembly and **before** wiki-markup conversion. Tone target: informal but technical. No marketing voice, no "we are excited", no "I have...".
 - **No decorative glyphs anywhere in the comment body**  -  neither emotive (    ) nor status glyphs ([done] [pending] failed skipped active ). The comment is plain technical prose. Status is written in words: `[done]` / `[pending]`, and `done · active · failed · skipped · pending` in the phase strip. This applies to every channel, not only Jira  -  see `channels/README` note in `phase-5-report.md`.
 - Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, type names, branch names, and the wiki-markup syntax stay verbatim. The `promptLanguage="en"` lock means any LLM prompt that produces the body is in English; the body itself is then rendered in the user's language.