@mmerterden/multi-agent-pipeline 16.27.0 → 16.29.0

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

@@ -4,6 +4,19 @@ description-tr: "İlk kurulum sihirbazı: keychain token keşfi, Git Identity ka
 allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
 ---
 
+## Step 0 - What is actually wrong
+
+```bash
+node "$HOME/.claude/scripts/doctor.mjs"
+```
+
+Run it before the first question and again at the end. The first run turns setup
+from a fixed script into a targeted one: there is no point asking for a token
+that is already mapped and answering. The second run is the only honest way to
+end - "setup complete" is a claim, and the doctor's exit code is the evidence for
+or against it. Report both in `outputLanguage`, and if the second run still shows
+a BLOCK, say so plainly rather than closing on the word "complete".
+
 ## Setup (Credential Store + Git Identity Onboarding)
 
 Cross-platform setup  -  uses `$HOME/.claude/lib/credential-store.sh` to read/write secrets in the platform-native credential store:
@@ -789,7 +802,7 @@ All tokens are optional in the sense that every service can be answered with Ski
 
 ### Step 8  -  Enforcement hooks (optional, Claude Code)
 
-Offer to merge `install/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus two capture hooks that block nothing (`SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus two capture hooks that block nothing (`SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
 - Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
 - On Yes, deep-merge EVERY event in the template's `hooks` object, not `PreToolUse` alone - merging one event silently drops the capture hooks, and a run killed before Phase 7 then loses its findings exactly as it did before they existed. Preserve existing hooks; never duplicate a matcher already calling the same script.

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

@@ -57,10 +57,11 @@ The sync skill must run on all three platforms. Commands go through the platform
 Run every step automatically:
 
 ```
+Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 51 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 51 specs as refs + 8 agent TOML)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 53 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 53 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -72,6 +73,8 @@ Step 6: Report      Summary: synced targets, platform, changed files, deploy sta
 
 If nothing is stale → report "All targets up to date" and stop.
 
+Step 0 gate rules and why: `features/doctor.md`.
+
 ---
 
 ## Sync rules
@@ -122,8 +125,8 @@ If nothing is stale → report "All targets up to date" and stop.
      # backstop: no local-only wrapper may exist in the synced target
      grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: local-only wrapper leaked into pipeline/commands"; exit 1; } || true
-     # backstop: no corporate marketplace/skill reference in the synced tree
-     grep -rniE "ai-ios(-engineering)?-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \
+     # backstop: corporate refs only (generic ai-ios-toolkit is fine)
+     grep -rniE "ai-(ios-engineering|mobile)-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \
        ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true
      ```
@@ -166,7 +169,7 @@ If nothing is stale → report "All targets up to date" and stop.
 Unlike the Copilot step, this one does **not** hand-copy files. The Codex tree is a
 *transform* of the Claude tree, not a mirror of it, and the transform is real work:
 
-- the 51 sub-command specs become reference files, because Codex silently truncates
+- the 53 sub-command specs become reference files, because Codex silently truncates
   its skills block (see `cross-cli-contract.md` 2.6 for the measurement)
 - every `$HOME/.claude/...` reference to a CLI-owned tree is retargeted, with
   `agents/<persona>.md` becoming `.toml` and the dispatcher becoming the router skill
@@ -480,18 +483,18 @@ When invoked with the `release` argument:
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
 This runs on the Claude <-> Copilot axis. Codex is NOT synced here: it receives the
-same 51 specs as reference files rather than as peer skills, via Step 2b -  see
+same 53 specs as reference files rather than as peer skills, via Step 2b -  see
 `cross-cli-contract.md` 2.6 for why the parity axis differs per host.
 
 | Claude Code | Copilot CLI |
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**51 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**53 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels,
-complaint-analysis, create-jira, design-check, diff-explain, feedback,
+analysis, analysis-jira, analysis-resolve, autopilot, build-optimize, channels,
+complaint-analysis, create-jira, design-check, doctor, diff-explain, feedback,
 forget, garbage-collect, graph, help, ios-coding-standard, issue, jira,
 kill, language, local, local-autopilot, log, manual-test, prune-logs,
 prune-prompts, purge, refactor, resume, resume-local, review,

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

@@ -4,6 +4,18 @@ description-tr: "Pipeline'ı npm'deki son yayına günceller: registry kontrolü
 allowed-tools: Bash, Read, Write, AskUserQuestion
 ---
 
+## After the install, check it
+
+```bash
+node "$HOME/.claude/scripts/doctor.mjs"
+```
+
+An update is the moment the layout changes, so it is the moment a layout check is
+worth most: a script that moved, a host tree that did not get the copy, a version
+stamp that disagrees with the package. Report the result in `outputLanguage`.
+Exit 2 means the update left the install in a state a run will fail from - say
+that, do not report "updated" and stop.
+
 # multi-agent update
 
 Update the pipeline in one command. The npm registry is the single update channel: the latest published release is downloaded and installed. Existing preferences are preserved; only skill / script / schema files are refreshed.

package/pipeline/lib/_jira-auth.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+#
+# _jira-auth.sh  -  one resolution of host + token, and one way to call Jira.
+#
+# WHY THIS EXISTS
+#
+# The same twelve lines were written twice (`jira-publish.sh`, `issue-fetcher.sh`)
+# and a third writer was about to make it three. Duplicated auth does not stay
+# duplicated: it drifts, and the copy that drifts is the one nobody is looking at.
+#
+# Today only `analysis-jira-write.sh` sources this. The two older callers still
+# carry their own resolution - `issue-fetcher.sh` resolves per-account token keys
+# this helper does not model yet - so this is where new callers go, not a
+# consolidation that has already happened.
+# Worse, the part most worth getting right is the part most easily retyped badly -
+# the token goes to curl through a `-K` config on process substitution so it never
+# reaches argv, a log, or `ps`. A second-hand copy of that idiom is a leak waiting
+# for the first person who simplifies it.
+#
+# Sourced, never executed. The leading underscore marks it: it is a library for
+# the scripts beside it, not a command.
+#
+#   . "$(dirname "$0")/_jira-auth.sh"
+#   jira_auth_resolve || exit 4      # sets JIRA_API_HOST and JIRA_API_TOKEN
+#   jira_api GET /rest/api/2/myself
+#
+# Resolution, in order, for each of the two values:
+#   host   $JIRA_HOST, $ACCOUNT_JIRA_HOST, prefs .global.hosts.jira
+#   token  $JIRA_TOKEN, else credential-store.sh get <key>, where the key is
+#          $JIRA_TOKEN_KEY, $ACCOUNT_JIRA_TOKEN_KEY, or
+#          prefs .global.keychainMapping.jira
+#
+# Exit contract: `jira_auth_resolve` returns 0 when both resolved, 4 when either
+# did not, having already said which on stderr. 4 is the same code both callers
+# already used for "could not resolve", so nothing downstream changes meaning.
+
+# shellcheck shell=bash
+
+JIRA_AUTH_PREFS="${JIRA_AUTH_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+
+_jira_auth_pref() {  # _jira_auth_pref <jq path> -> value or empty
+  [ -f "$JIRA_AUTH_PREFS" ] || { printf ''; return 0; }
+  jq -r "$1 // empty" "$JIRA_AUTH_PREFS" 2>/dev/null || printf ''
+}
+
+_jira_auth_store() {  # locate credential-store.sh from lib/ or the install
+  local here
+  here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for cand in "$here/credential-store.sh" "$HOME/.claude/lib/credential-store.sh"; do
+    [ -f "$cand" ] && { printf '%s' "$cand"; return 0; }
+  done
+  return 1
+}
+
+jira_auth_resolve() {
+  JIRA_API_HOST="${JIRA_HOST:-${ACCOUNT_JIRA_HOST:-}}"
+  [ -n "$JIRA_API_HOST" ] || JIRA_API_HOST="$(_jira_auth_pref '.global.hosts.jira')"
+  if [ -z "$JIRA_API_HOST" ]; then
+    echo "ERR: no Jira host: set JIRA_HOST or prefs .global.hosts.jira" >&2
+    return 4
+  fi
+  # A host is a host, whatever the caller pasted.
+  JIRA_API_HOST="${JIRA_API_HOST#https://}"
+  JIRA_API_HOST="${JIRA_API_HOST#http://}"
+  JIRA_API_HOST="${JIRA_API_HOST%/}"
+
+  JIRA_API_TOKEN="${JIRA_TOKEN:-}"
+  if [ -z "$JIRA_API_TOKEN" ]; then
+    local key store
+    key="${JIRA_TOKEN_KEY:-${ACCOUNT_JIRA_TOKEN_KEY:-}}"
+    [ -n "$key" ] || key="$(_jira_auth_pref '.global.keychainMapping.jira')"
+    if [ -z "$key" ]; then
+      echo "ERR: no Jira token: set JIRA_TOKEN or map prefs .global.keychainMapping.jira" >&2
+      return 4
+    fi
+    store="$(_jira_auth_store)" || {
+      echo "ERR: credential-store.sh not found next to lib/ or in ~/.claude/lib" >&2
+      return 4
+    }
+    JIRA_API_TOKEN="$(bash "$store" get "$key" 2>/dev/null || printf '')"
+    if [ -z "$JIRA_API_TOKEN" ]; then
+      echo "ERR: Jira token not in the credential store under: $key" >&2
+      return 4
+    fi
+  fi
+  return 0
+}
+
+# The token reaches curl only through a -K config on process substitution: never
+# argv, never a log, never `ps`. Every caller goes through here so that stays
+# true in one place instead of three.
+_jira_auth_cfg() { printf 'header = "Authorization: Bearer %s"\n' "$1"; }
+
+jira_api() {  # jira_api <METHOD> <path> [curl args...]
+  local method="$1" path="$2"; shift 2
+  curl -sS -m 30 -K <(_jira_auth_cfg "$JIRA_API_TOKEN") \
+    -H "Content-Type: application/json" \
+    -X "$method" "https://$JIRA_API_HOST$path" "$@"
+}

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

@@ -0,0 +1,203 @@
+#!/usr/bin/env bash
+#
+# analysis-jira-write.sh  -  create the tree that analysis-story-tree.mjs planned.
+#
+# WHY THIS IS A SEPARATE FILE
+#
+# Planning is deterministic, testable offline, and safe to run a hundred times.
+# Creating issues is none of those. Keeping them apart means the file that can
+# write to a tracker is small enough to read in one sitting, and the file that
+# 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.
+#
+# THE WRITE IS LEDGERED, AND THE LEDGER IS THE POINT
+#
+# Before each POST an `intent` line is appended to the run ledger; after the
+# response, the key. Crash in between and the ledger holds an intent with no key.
+# The next run sees that and does a label search BEFORE sending anything, so a
+# half-written tree cannot twin itself. Without the ledger, the failure mode is
+# not "the run stopped" - it is "the run stopped and the retry made a second
+# tree", which is the expensive one.
+#
+# IDENTITY IS SERVER-SIDE
+#
+# Each node carries a label from the plan. Finding the tree back is a JQL search
+# on that label, not a lookup in a local file: a local index does not survive a
+# new machine, a deleted ~/.claude, or a SECOND ANALYST - and the second analyst
+# is exactly the person who would otherwise open a duplicate tree.
+#
+# 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.
+#
+# Usage:
+#   analysis-jira-write.sh --plan plan.json --project KEY [--dry-run] [--ledger FILE]
+#
+# Exit: 0 written (or previewed), 3 the plan does not parse, 4 auth, 5 a Jira
+#       call failed, 64 usage.
+
+set -uo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SELF_DIR/_jira-auth.sh"
+
+PLAN=""; PROJECT=""; DRY=0; LEDGER=""
+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 ;;
+  esac
+done
+[ -n "$PLAN" ] && [ -f "$PLAN" ] || { echo "ERR: --plan FILE is required and must exist" >&2; exit 64; }
+[ -n "$PROJECT" ] || { echo "ERR: --project KEY is required" >&2; exit 64; }
+
+command -v jq >/dev/null 2>&1 || { echo "ERR: jq is required" >&2; exit 3; }
+jq -e . "$PLAN" >/dev/null 2>&1 || { echo "ERR: the plan does not parse as JSON: $PLAN" >&2; exit 3; }
+
+DOC_ID="$(jq -r '.document.id // "unidentified"' "$PLAN")"
+VERDICT="$(jq -r '.coverage.verdict // "unverifiable"' "$PLAN")"
+if [ -z "$LEDGER" ]; then
+  LEDGER="$HOME/.claude/logs/multi-agent/_analysis-jira/${DOC_ID}.jsonl"
+fi
+mkdir -p "$(dirname "$LEDGER")" 2>/dev/null || true
+
+# A run that could not be verified is allowed to write; it is not allowed to look
+# verified afterwards. The ledger records the verdict beside every key, so the
+# question "was this tree checked?" is answerable later from the tree's own trail.
+ledger() {  # ledger <event> <label> [key]
+  [ "$DRY" -eq 1 ] && return 0
+  printf '{"ts":"%s","event":"%s","label":"%s","key":%s,"coverage":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$1" "$2" \
+    "$([ -n "${3:-}" ] && printf '"%s"' "$3" || printf 'null')" \
+    "$VERDICT" >> "$LEDGER"
+}
+
+if [ "$DRY" -eq 0 ]; then
+  jira_auth_resolve || exit 4
+fi
+
+# An unfinished write from a previous run: an intent whose key never arrived.
+# Its existence is what forces the search below to run before anything is sent.
+ORPHANS=0
+if [ -f "$LEDGER" ]; then
+  ORPHANS=$(jq -rs '[.[] | select(.event=="intent")] as $i
+                  | [.[] | select(.event=="created") | .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
+    echo "NOTE: $ORPHANS write(s) from an earlier run have no recorded key." >&2
+    echo "      Searching Jira by label before sending anything." >&2
+  fi
+fi
+
+# What already exists, by label. One search, whatever the tree's size.
+declare -a EXISTING=()
+existing_for() {  # existing_for <label> -> prints the key, or empty
+  local label="$1" i
+  for i in "${EXISTING[@]:-}"; do
+    case "$i" in "$label="*) printf '%s' "${i#*=}"; return 0 ;; esac
+  done
+  printf ''
+}
+
+LABELS="$(jq -r '[.nodes[] | .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)"
+  SEARCH="$(jira_api GET "/rest/api/2/search?jql=${ENC}&fields=labels&maxResults=200" || echo "")"
+  if [ -n "$SEARCH" ]; then
+    while IFS= read -r pair; do
+      [ -n "$pair" ] && EXISTING+=("$pair")
+    done < <(printf '%s' "$SEARCH" | jq -r '.issues[]? | .key as $k | .fields.labels[]? | "\(.)=\($k)"' 2>/dev/null || true)
+  fi
+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.
+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
+  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"
+    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" '
+    {fields: ({project: {key: $p}, summary: $s, issuetype: {name: $t},
+               labels: [$l], description: $d}
+              + (if $par == "" then {} else {parent: {key: $par}} end))}')"
+  if [ "$DRY" -eq 1 ]; then
+    echo "  create  $itype  $summary   [$label]"
+    return 0
+  fi
+  ledger intent "$label"
+  local resp
+  resp="$(printf '%s' "$body" | jira_api POST "/rest/api/2/issue" --data @- || echo "")"
+  key="$(printf '%s' "$resp" | jq -r '.key // empty' 2>/dev/null || echo "")"
+  if [ -z "$key" ]; then
+    echo "ERR: create failed for '$summary'" >&2
+    printf '%s\n' "$resp" | head -3 >&2
+    return 5
+  fi
+  ledger created "$label" "$key"
+  echo "  created $key  $summary"
+  CREATED_KEY="$key"
+}
+
+echo "analysis-jira-write: ${PROJECT}, coverage ${VERDICT}$([ "$DRY" -eq 1 ] && echo "  (dry run)")"
+[ "$VERDICT" = "unverifiable" ] && \
+  echo "  NOTE: coverage could not be checked for this document; the tree is unverified."
+
+RC=0
+NODES="$(jq -c '.nodes[]' "$PLAN")"
+while IFS= read -r node; do
+  [ -n "$node" ] || continue
+  s_label="$(printf '%s' "$node" | jq -r '.label')"
+  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.
+    RC=5
+    echo "  skipped   this story's sub-tasks: the story itself was not created" >&2
+    continue
+  fi
+  skey="$CREATED_KEY"
+  while IFS= read -r sub; do
+    [ -n "$sub" ] || continue
+    t_label="$(printf '%s' "$sub" | jq -r '.label')"
+    t_role="$(printf '%s' "$sub" | jq -r '.role')"
+    t_type="$(jq -r '.prefsUsed.subtaskIssueType // empty' "$PLAN")"
+    if [ -z "$t_type" ] && [ "$DRY" -eq 0 ]; then
+      # Discover rather than assume: whichever type this site marks subtask:true,
+      # under whatever name the site gave it.
+      t_type="$(jira_api GET "/rest/api/2/issue/createmeta?projectKeys=${PROJECT}&expand=projects.issuetypes" \
+        | 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
+  done < <(printf '%s' "$node" | jq -c '.subtasks[]?')
+done <<< "$NODES"
+
+exit "$RC"

package/pipeline/lib/issue-fetcher.sh

@@ -123,8 +123,11 @@ branch_for() {
 # token never appears in argv (argv is visible to `ps` / process audit).
 jira_auth_cfg() { printf 'header = "Authorization: Bearer %s"\n' "$1"; }
 
-fetch_jira() {
-  local key="$1"
+# Resolve the credential helper once and issue one authenticated GET. Split
+# out of fetch_jira so the sibling search reuses the same resolution instead
+# of duplicating thirty lines of it.
+jira_curl() {
+  local path="$1"
   if [ -z "$JIRA_HOST" ] || [ -z "$JIRA_TOKEN_KEY" ]; then
     echo "ERR: ACCOUNT_JIRA_HOST and ACCOUNT_JIRA_TOKEN_KEY must be set" >&2
     return 1
@@ -160,11 +163,28 @@ fetch_jira() {
     echo "ERR: Jira token not found in credential store ($JIRA_TOKEN_KEY)" >&2
     return 1
   fi
-  curl -sf -K <(jira_auth_cfg "$token") \
-    "https://$JIRA_HOST/rest/api/2/issue/$key?fields=summary,status,issuetype,description,priority,resolution,fixVersions,parent" \
+  curl -sf -K <(jira_auth_cfg "$token") "https://$JIRA_HOST$path"
+}
+
+# The field list is a parameter because the related-issue lookup wants a
+# narrow one; the default is the set every caller needed before it existed.
+fetch_jira() {
+  local key="$1"
+  local fields="${2:-summary,status,issuetype,description,priority,resolution,fixVersions,parent}"
+  jira_curl "/rest/api/2/issue/$key?fields=$fields" \
     || { echo "ERR: Jira fetch failed for $key" >&2; return 1; }
 }
 
+# One request returns every sibling WITH its description. The issue's own
+# `subtasks` field lists ITS children, not its siblings, and the parent's
+# lists siblings without descriptions  -  either shape costs one GET each.
+# Failure is soft: the caller falls back to an empty list and the run goes on.
+jira_search() {
+  local jql="$1" fields="$2" maxr="$3"
+  jira_curl "/rest/api/2/search?jql=$jql&fields=$fields&maxResults=$maxr" \
+    || { echo "WARN: Jira search failed  -  related issues unavailable" >&2; return 1; }
+}
+
 fetch_github() {
   local owner="$1" repo="$2" num="$3"
   if ! command -v gh >/dev/null 2>&1; then
@@ -207,6 +227,16 @@ priority_weights = {
 }
 priority_weight = priority_weights.get(priority.lower(), 0)
 
+# relatedIssues arrives as one JSON argv rather than through the \x1f channel,
+# so the delimited parse below stays exactly eight fields wide. Anything
+# unparseable degrades to an empty list; a fetcher must not die on context.
+try:
+    related = json.loads(fields.get("relatedIssues") or "[]")
+except Exception:
+    related = []
+if not isinstance(related, list):
+    related = []
+
 descriptor = {
     "kind":        fields.get("kind"),
     "key":         fields.get("key") or None,
@@ -225,6 +255,7 @@ descriptor = {
     "owner":       fields.get("owner") or None,
     "repo":        fields.get("repo") or None,
     "branchHint":  fields.get("branchHint") or None,
+    "relatedIssues": related,
 }
 extra = {}
 if fields.get("needsRepoPicker"):
@@ -238,6 +269,8 @@ itype = (descriptor.get("type") or "").lower()
 
 parent_desc = (descriptor.get("parentDescription") or "").strip()
 parent_key = descriptor.get("parentKey") or ""
+sibling_key = next((r.get("key") or "" for r in related
+                    if isinstance(r, dict) and (r.get("description") or "").strip()), "")
 
 blockers, warnings = [], []
 closed = {"done","closed","cancelled","canceled","resolved"}
@@ -253,6 +286,11 @@ if not desc.strip():
     # No parent / an equally-empty parent keeps the hard blocker as before.
     if parent_desc:
         warnings.append("description_empty_parent_available")
+    elif sibling_key:
+        # Same shape one level out: the analysis sibling is where the content
+        # actually is on some boards. Only fires when the parent has none, so
+        # it never costs a point on an issue that reads fine.
+        warnings.append("description_empty_sibling_available")
     else:
         blockers.append("description_empty")
 elif len(desc.strip()) < 80:
@@ -273,20 +311,22 @@ labels_tr = {
     "already_resolved":      "Issue zaten resolved/merged ({})".format(resolution or " - "),
     "description_empty":     "Açıklama boş",
     "description_empty_parent_available":"Açıklama boş ama parent'ta ({}) içerik var  -  oradan devam edilsin mi?".format(parent_key or " - "),
+    "description_empty_sibling_available":"Açıklama boş, parent da boş, ama kardeş maddede ({}) içerik var  -  oradan devam edilsin mi?".format(sibling_key or " - "),
     "short_description":     "Açıklama çok kısa (<80 karakter)",
     "short_title":           "Başlık çok kısa (<10 karakter)",
-    "no_repro_steps":        "Bug için repro adımları yok",
-    "no_acceptance_criteria":"Kabul kriteri / AC görünmüyor",
+    "no_repro_steps":        "Hatanın nasıl tekrarlanacağı yazmamış: ne yapıldı, ne bekleniyordu, ne oldu",
+    "no_acceptance_criteria":"Kabul kriteri yok: işin bittiğini neye bakarak anlayacağımız yazmamış",
 }
 labels_en = {
     "status_closed":         "Issue is closed/cancelled",
     "already_resolved":      "Issue already resolved/merged ({})".format(resolution or " - "),
     "description_empty":     "Description is empty",
     "description_empty_parent_available":"Description is empty but the parent ({}) has content  -  continue from there?".format(parent_key or " - "),
+    "description_empty_sibling_available":"Description is empty and so is the parent, but a sibling issue ({}) has content  -  continue from there?".format(sibling_key or " - "),
     "short_description":     "Description too short (<80 chars)",
     "short_title":           "Title too short (<10 chars)",
-    "no_repro_steps":        "Bug missing reproduction steps",
-    "no_acceptance_criteria":"No acceptance criteria detected",
+    "no_repro_steps":        "No reproduction steps: what was done, what was expected, what happened",
+    "no_acceptance_criteria":"No acceptance criteria: nothing says what \"done\" looks like",
 }
 labels = labels_tr if lang == "tr" else labels_en
 lines = []
@@ -383,13 +423,102 @@ sys.stdout.write((f.get("description") or "").replace("\x1f", " "))
         fi
       fi
     fi
+    # A development sub-task's siblings under the same parent carry the rest of
+    # the picture: the analysis sub-task is often the one with content while the
+    # dev task has none. One search returns all of them WITH their descriptions,
+    # so this costs exactly one extra request, and none at all on an issue with
+    # no parent. Gated on parentkey alone, not on an empty own description  -
+    # the analysis sibling is worth reading even when the dev task is filled in.
+    # Read prefs only once parentkey is known non-empty: an issue with no parent
+    # is the common case and should not pay for an interpreter start. Env wins,
+    # which is what lets the offline gate drive every branch without a prefs file.
+    prefs_jiraContext_enabled="${JIRA_CONTEXT_ENABLED:-}"
+    prefs_jiraContext_maxItems="${JIRA_CONTEXT_MAX_ITEMS:-}"
+    prefs_jiraContext_maxCharsPerItem="${JIRA_CONTEXT_MAX_CHARS:-}"
+    if [ -n "${parentkey:-}" ] && { [ -z "$prefs_jiraContext_enabled" ] || \
+         [ -z "$prefs_jiraContext_maxItems" ] || [ -z "$prefs_jiraContext_maxCharsPerItem" ]; }; then
+      _jc=$(python3 - <<'PY' 2>/dev/null || true
+import json, os
+p = os.path.expanduser("~/.claude/multi-agent-preferences.json")
+c = {}
+try:
+    c = ((json.load(open(p, encoding="utf-8")).get("global") or {}).get("jiraContext") or {})
+except Exception:
+    c = {}
+print("%s %s %s" % (
+    "false" if c.get("enabled") is False else "true",
+    int(c.get("maxItems", 6)),
+    int(c.get("maxCharsPerItem", 1200)),
+))
+PY
+)
+      # Parameter expansion, not `set --`: the positional parameters belong to
+      # the script and the jira-url branch re-execs with them.
+      _jc="${_jc:-true 6 1200}"
+      _jc_rest="${_jc#* }"
+      [ -n "$prefs_jiraContext_enabled" ] || prefs_jiraContext_enabled="${_jc%% *}"
+      [ -n "$prefs_jiraContext_maxItems" ] || prefs_jiraContext_maxItems="${_jc_rest%% *}"
+      [ -n "$prefs_jiraContext_maxCharsPerItem" ] || prefs_jiraContext_maxCharsPerItem="${_jc_rest##* }"
+      unset _jc _jc_rest
+    fi
+    : "${prefs_jiraContext_enabled:=true}"
+    : "${prefs_jiraContext_maxItems:=6}"
+    : "${prefs_jiraContext_maxCharsPerItem:=1200}"
+    relatedjson="[]"
+    if [ -n "${parentkey:-}" ] && [ "$prefs_jiraContext_enabled" = "true" ] && [ "$prefs_jiraContext_maxItems" -gt 0 ]; then
+      # parentkey is API-supplied but goes straight into a URL query, so it is
+      # re-validated against the same anchored pattern detect_kind uses. That
+      # makes the encoding trivial and closes the JQL-injection path.
+      if printf '%s' "$parentkey" | grep -qE '^[A-Z][A-Z0-9]*-[0-9]+$'; then
+        sraw=$(jira_search "parent%3D%22$parentkey%22" \
+                 "summary,issuetype,status,description" 20) || sraw=""
+        if [ -n "$sraw" ]; then
+          relatedjson=$(printf '%s' "$sraw" | SELF_KEY="$KEY" \
+            RELATED_MAX="$prefs_jiraContext_maxItems" RELATED_CHARS="$prefs_jiraContext_maxCharsPerItem" python3 -c '
+import json, os, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.stdout.write("[]"); raise SystemExit(0)
+self_key = os.environ.get("SELF_KEY", "")
+cap = int(os.environ.get("RELATED_MAX") or 0)
+chars = int(os.environ.get("RELATED_CHARS") or 0)
+out = []
+for i in d.get("issues") or []:
+    key = i.get("key") or ""
+    if not key or key == self_key:
+        continue
+    f = i.get("fields") or {}
+    desc = (f.get("description") or "").replace("\x1f", " ")
+    truncated = False
+    if chars and len(desc) > chars:
+        desc = desc[:chars] + "..."
+        truncated = True
+    out.append({
+        "key": key,
+        "relation": "sibling",
+        "type": ((f.get("issuetype") or {}).get("name") or ""),
+        "status": ((f.get("status") or {}).get("name") or ""),
+        "summary": (f.get("summary") or ""),
+        "description": desc,
+        "truncated": truncated,
+    })
+# Siblings that carry content come first, so the cap keeps the useful ones.
+out.sort(key=lambda r: 0 if r["description"].strip() else 1)
+sys.stdout.write(json.dumps(out[:cap], ensure_ascii=False))
+') || relatedjson="[]"
+        fi
+      fi
+    fi
+    [ -n "$relatedjson" ] || relatedjson="[]"
     branch=$(branch_for "$KEY" "$itype" "$title")
     emit_descriptor \
       "kind=jira" "key=$KEY" "title=$title" "type=$itype" "status=$status" \
       "description=$description" "host=$JIRA_HOST" \
       "url=https://$JIRA_HOST/browse/$KEY" "branchHint=$branch" \
       "priority=$priority" "resolution=$resolution" "fixVersions=$fixversions" \
-      "parentKey=$parentkey" "parentDescription=$parentdesc"
+      "parentKey=$parentkey" "parentDescription=$parentdesc" \
+      "relatedIssues=$relatedjson"
     ;;
 
   jira-url)

package/pipeline/lib/multi-repo-pipeline.sh

@@ -18,6 +18,7 @@
 #     "branch":"feature/PROJ-1",
 #     "baseBranch":"develop",
 #     "issueRef":{"kind":"jira","key":"PROJ-1","title":"...", ...},
+#                       (may carry relatedIssues[] from issue-fetcher.sh)
 #     "primary":   {"name":"my-ios-app","cloneUrl":"...","provider":"github"},
 #     "extras":   [{"name":"common","cloneUrl":"...","provider":"github"}, ...],
 #     "worktreeRoot":".worktrees/PROJ-1-20260427",
@@ -300,6 +301,13 @@ agent_state = {
     "projects":      [repo_entry(r, i == 0) for i, r in enumerate(all_repos)],
 }
 
+# Written only when non-empty, so a GitHub or free-text bridge produces the
+# same bytes it always did. Phase 1 and Phase 2 read it; without it here the
+# context would be intake-only and every resume would start without it.
+related = issue.get("relatedIssues") or []
+if isinstance(related, list) and related:
+    agent_state["relatedIssues"] = related
+
 logs_dir = os.path.expanduser(os.path.join("~/.claude/logs/multi-agent", primary["name"], state["taskId"]))
 os.makedirs(logs_dir, exist_ok=True)
 out_path = os.path.join(logs_dir, "agent-state.json")