@mmerterden/multi-agent-pipeline 16.28.0 → 16.29.0

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

@@ -314,8 +314,8 @@ labels_tr = {
     "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",
@@ -325,8 +325,8 @@ labels_en = {
     "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 = []

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

@@ -137,7 +137,7 @@ Iterate `state.analysisSpec.outputs.requested`. For each target:
 | 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 35). 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 35). 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. |
 
-**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.jiraIssueKey` (single string).
+**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).
 
 ### Phase 5 - Report & stop
 

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -6,11 +6,11 @@
 
 ---
 
-## 1. Command Inventory (51 commands)
+## 1. Command Inventory (53 commands)
 
 ```
-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/multi-agent-refs/features/analysis-jira.md

@@ -0,0 +1,128 @@
+# analysis-jira - an analysis document, read as work
+
+`/multi-agent:analysis-jira` turns a rendered analysis document into a Jira tree.
+Two files do it, and the split is the design:
+
+| File | Does | Network |
+|---|---|---|
+| `scripts/analysis-story-tree.mjs` | decides WHAT to create, checks coverage, assigns identity | none |
+| `lib/analysis-jira-write.sh` | creates it | yes |
+
+Planning is deterministic and testable offline; creating issues is neither. Kept
+apart, the file that can write to a tracker is small enough to read in one
+sitting.
+
+`jira-publish.sh` could not be extended to do this: it writes a comment or a
+description on an issue that already exists. The only creation path in the repo
+was a curl hand-written inside a markdown instruction, which is what this
+replaces.
+
+## The marker gate runs first, before any network call
+
+Zero `EKLENECEK`, zero `TBD`, no open Section 20 row. A document with an open
+placeholder is not a plan, and turning it into a tree publishes the gap as work
+somebody is now assigned. Refusal is exit 4 and it names
+`/multi-agent:analysis-resolve` as the step.
+
+This is the same closure contract `status: final` enforces in
+`validate-analysis-doc.mjs`, applied at the point the document leaves the
+analysis world.
+
+## Coverage is two-way, and the second direction is the useful one
+
+| Direction | Catches |
+|---|---|
+| every defined id appears in some story | a dropped requirement |
+| every cited id is defined in the document | an **invented story** - a node with no requirement behind it |
+
+No forward check can see the second one, and it is the failure mode of building
+a tree from a model's reading rather than from the document's own ids.
+
+The atom is `BR-<slug>-NN` in the global profile and `FG-NN` in the corporate
+one; the group is the `BR-<slug>` prefix, or `UC-NN`. Locked 31 guarantees both
+exist, which is why the tree can be derived rather than invented.
+
+`coverageOf()` is exported and tested directly. The planner cannot emit an
+invented id - it derives every `sourceIds` from the defined set - so a test that
+fabricates one and re-checks it with its own logic proves nothing about the
+shipped code. The backward direction guards the boundary where a plan arrives
+from somewhere else: hand-edited, resumed from an older format, or produced by
+something that read the prose instead of the ids.
+
+## An unverifiable run is allowed; looking verified is not
+
+A lite document may carry no ids at all. Coverage then cannot run, and the
+verdict is `unverifiable`, never `ok`. It appears:
+
+- on its own line in the preview, where a reader looks for `ok`
+- as a separate fourth approval option, not folded into `Approve`
+- in the writer's own output, and beside every key in the ledger
+
+Such a document still plans work, from its user-story sub-sections. That is not
+a convenience: without it the no-atom document produced no stories, exited
+"nothing to plan", and the `unverifiable` branch was unreachable - a case the
+code claimed to handle and never could.
+
+## Identity is a label, not a title
+
+Each node carries `<labelPrefix>-<10 hex>`, hashed from the document id
+(`evidence_digest`) plus the node's own source ids. A second run finds its tree
+back with one JQL search on those labels.
+
+Titles were the obvious key and are the wrong one: they get edited, and matching
+on them breaks exactly when someone has improved the wording. The label lives
+server-side, so it survives a new machine, a deleted `~/.claude`, and a **second
+analyst** - who is precisely the person positioned to open a duplicate tree.
+
+## The write is ledgered
+
+`~/.claude/logs/multi-agent/_analysis-jira/<docId>.jsonl`. An `intent` line
+before each POST, the key after the response. A crash between them leaves an
+intent with no key; the next run sees that and searches by label before sending
+anything. Without the ledger the failure mode is not "the run stopped" but "the
+run stopped and the retry made a second tree", which is the expensive one.
+
+Every line also carries the coverage verdict, so "was this tree checked?" stays
+answerable from the tree's own trail.
+
+## 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.
+
+## Every site-specific name is a VALUE, never a schema key
+
+`prefs.global.issueTree` holds the vocabulary. A key is a published literal and
+this schema ships to everyone, so a site's component, team and issue-type names
+are values the site fills in:
+
+- `channelComponents` / `channelTeams` are free-form maps: the key is the
+  channel, the value is the site's own name for it
+- `subtaskRoles` ships **empty**. An empty list is an instruction to look at how
+  this board actually splits work; a ready-made list would be the guess most
+  worth avoiding
+- `subtaskIssueType: null` means discover it - `createmeta` returns whichever
+  type carries `subtask: true`, under whatever name the site gave it. Same rule
+  as `features/jira-context.md`: the type travels as it comes from Jira and is
+  never a matching criterion in code
+
+The preview prints every field beside the pref key it came from, so a wrong
+setting is visible before the writes rather than in Jira afterwards.
+
+## Auth
+
+`lib/_jira-auth.sh` holds one host-and-token resolution and one curl idiom: the
+token reaches curl through a `-K` config on process substitution and never
+touches argv, a log, or `ps`. That idiom is the part most easily retyped badly,
+which is why the third writer got a shared copy instead of a third hand-written
+one.
+
+**Only this writer consumes it today.** `jira-publish.sh` and `issue-fetcher.sh`
+still carry their own resolution, and retrofitting them is real work rather than
+a rename - `issue-fetcher.sh` resolves per-account token keys that this helper
+does not model yet. So the file is the shared copy going forward, not a
+consolidation that has already happened, and saying otherwise would describe a
+cleanup nobody did. The leak property itself is asserted on all three callers
+independently in `smoke-analysis-jira.sh`, which is the part that must hold
+whether or not they ever share code.