@mmerterden/multi-agent-pipeline 17.0.0 → 17.1.0

package/pipeline/lib/autopilot-activation.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# autopilot-activation.sh  -  which repos may this machine pick work up from.
+#
+# The answer is NEVER "all of them" and never "whatever has the label". Measured
+# on one machine: 66 repos grant push, and a good half belong to other people -
+# a colleague's backend, someone's side project. A label is a filter, not a gate:
+# anyone able to open an issue in a repo you happen to have push on could put
+# `agent-queue` on it. The gate is this picker, and the picker is per machine.
+#
+# Two lists come out, and the difference matters:
+#
+#   eligible    push rights AND a checkout on this machine
+#   unavailable push rights, no checkout - LISTED, with that as the reason
+#
+# The second list is printed rather than dropped. Silently hiding 40 repos from a
+# 66-repo answer looks exactly like a permissions problem, and the user then goes
+# looking for a token fault that does not exist.
+#
+# Usage:
+#   bash autopilot-activation.sh list            # TSV: state, nameWithOwner, localPath
+#   bash autopilot-activation.sh list --json
+#   . autopilot-activation.sh; ma_ap_local_path <owner/repo>
+#
+# Exit: 0 on success (including an empty list), 2 on usage, 3 when gh cannot answer.
+
+set -uo pipefail
+
+# Repo roots to search for checkouts. $HOME's immediate children covers the
+# normal layout; MA_AUTOPILOT_REPO_ROOTS overrides it for tests and for anyone
+# who keeps checkouts somewhere else.
+MA_AP_ROOTS="${MA_AUTOPILOT_REPO_ROOTS:-$HOME}"
+
+# owner/repo for a checkout, read from its origin remote. Both URL forms, and a
+# trailing .git is stripped - `git@github.com:o/r.git` and
+# `https://github.com/o/r` are the same repo and a picker that treats them as
+# two shows the user a duplicate they cannot explain.
+ma_ap_remote_slug() {
+  local dir="$1" url
+  url=$(git -C "$dir" remote get-url origin 2>/dev/null) || return 1
+  url="${url%.git}"
+  case "$url" in
+    *github.com[:/]*) printf '%s\n' "${url##*github.com[:/]}" ;;
+    *) return 1 ;;
+  esac
+}
+
+# Every checkout under the roots, as `slug<TAB>path`. One pass, so the lookup
+# below is a grep rather than a walk per repo.
+ma_ap_checkout_index() {
+  local root d slug
+  for root in $MA_AP_ROOTS; do
+    [ -d "$root" ] || continue
+    for d in "$root"/*/; do
+      [ -d "$d/.git" ] || continue
+      slug=$(ma_ap_remote_slug "${d%/}") || continue
+      printf '%s\t%s\n' "$slug" "${d%/}"
+    done
+  done
+}
+
+ma_ap_local_path() { # $1 = owner/repo
+  ma_ap_checkout_index | awk -F'\t' -v s="$1" 'tolower($1)==tolower(s){print $2; exit}'
+}
+
+# Repos the authenticated account may push to.
+#
+# The query string form is deliberate: `gh api user/repos --field affiliation=...`
+# sends the value as a BODY field on a GET, which this endpoint ignores - it
+# answers with the default affiliation and the caller never learns the filter did
+# not apply. Measured: the --field form returned 0 rows here, the query string
+# form returned 66.
+ma_ap_writable_repos() {
+  gh api "user/repos?affiliation=owner,collaborator,organization_member&per_page=100" \
+    --paginate -q '.[] | select(.permissions.push == true) | .full_name' 2>/dev/null
+}
+
+ma_ap_list() {
+  local json="${1:-}" slug path index
+  index=$(ma_ap_checkout_index)
+  local repos
+  repos=$(ma_ap_writable_repos)
+  if [ -z "$repos" ]; then
+    echo "autopilot-activation: gh returned no writable repos - check 'gh auth status'" >&2
+    return 3
+  fi
+
+  local first=1
+  [ "$json" = "--json" ] && printf '['
+  while IFS= read -r slug; do
+    [ -n "$slug" ] || continue
+    path=$(printf '%s\n' "$index" | awk -F'\t' -v s="$slug" 'tolower($1)==tolower(s){print $2; exit}')
+    local state="eligible"
+    [ -z "$path" ] && state="unavailable"
+    if [ "$json" = "--json" ]; then
+      [ "$first" -eq 0 ] && printf ','
+      first=0
+      printf '{"state":"%s","nameWithOwner":"%s","localPath":"%s"}' "$state" "$slug" "$path"
+    else
+      printf '%s\t%s\t%s\n' "$state" "$slug" "$path"
+    fi
+  done <<EOF
+$repos
+EOF
+  [ "$json" = "--json" ] && printf ']\n'
+  return 0
+}
+
+if [ "${BASH_SOURCE[0]:-$0}" = "$0" ]; then
+  case "${1:-}" in
+    list) ma_ap_list "${2:-}" ;;
+    "" | -h | --help) grep -E '^#( |$)' "$0" | sed -E 's/^# ?//' ;;
+    *)
+      echo "autopilot-activation: unknown command ${1}" >&2
+      exit 2
+      ;;
+  esac
+fi

package/pipeline/lib/autopilot-state.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# autopilot-state.sh  -  where continuous mode keeps its state, and who may read it.
+#
+# Everything lives under ~/.claude/autopilot/ and NOT in
+# multi-agent-preferences.json. That file has `additionalProperties: false` and a
+# migration chain, so a block there would push keys into every local user's
+# preferences forever - including everyone who never turns this on. Separation
+# also gives the off state a definition that cannot be got wrong: the directory
+# is absent.
+#
+#   config.json      the repo selection. Survives autopilot-off on purpose, so
+#                    turning the mode back on does not re-ask which repos.
+#   queue.json       the current ordered list plus whatever is in flight
+#   status.json      what the menu bar renders. Written by the runner, read-only
+#                    to everything else
+#   attempted.jsonl  append-only: {source,id,taskId,outcome,prUrl,at}
+#   runner.pid       pid + the in-flight sessionId + kern.boottime
+#   runner.log
+#   bin/menubar      built on demand from scripts/autopilot-menubar.swift
+#
+# 0700 throughout. The queue names real tickets and real repos, and on a shared
+# machine that is somebody's roadmap.
+#
+# Usage:
+#   . autopilot-state.sh
+#   ma_ap_root                 # prints the dir, creating it 0700 only when asked
+#   ma_ap_is_on                # exit 0 when configured, 1 otherwise. NO side effects
+#   ma_ap_write <file> <-      # atomic write from stdin, 0600
+
+set -uo pipefail
+
+MA_AP_ROOT="${MA_AUTOPILOT_ROOT:-$HOME/.claude/autopilot}"
+
+ma_ap_root() { printf '%s\n' "$MA_AP_ROOT"; }
+
+MA_AP_LABEL="${MA_AUTOPILOT_LABEL:-com.multi-agent.autopilot}"
+MA_AP_PLIST="${MA_AUTOPILOT_PLIST:-$HOME/Library/LaunchAgents/$MA_AP_LABEL.plist}"
+
+# Two different questions, and conflating them was a real bug in the first draft
+# of this file: `autopilot-off` deliberately KEEPS config.json so turning the
+# mode back on does not re-ask which repos, so a predicate reading the config
+# would still answer "on" after you turned it off.
+#
+#   configured = a repo selection exists
+#   on         = launchd holds the job
+#
+# On is the launchd job because that is the thing that actually makes work
+# happen; anything else is a claim about a file.
+ma_ap_is_configured() { [ -f "$MA_AP_ROOT/config.json" ]; }
+
+ma_ap_is_on() { [ -f "$MA_AP_PLIST" ] && launchctl list 2>/dev/null | grep -q "$MA_AP_LABEL"; }
+
+# The failure mode a `resume` command would have papered over: configured and
+# meant to be running, but launchd does not hold the job - an OS update dropped
+# the plist, or it was booted out by hand. doctor reports this; there is no
+# command to remember.
+ma_ap_is_orphaned() { ma_ap_is_configured && ! ma_ap_is_on && [ -f "$MA_AP_PLIST" ]; }
+
+# Deliberately no side effects in any of the three. A predicate that creates its
+# own directory turns "is autopilot on?" into "autopilot is now half on", and
+# every status command, hook and doctor check calls these.
+
+ma_ap_ensure_root() {
+  [ -d "$MA_AP_ROOT" ] || mkdir -p "$MA_AP_ROOT" || return 1
+  chmod 700 "$MA_AP_ROOT" 2>/dev/null
+  [ -d "$MA_AP_ROOT/bin" ] || mkdir -p "$MA_AP_ROOT/bin" 2>/dev/null
+  chmod 700 "$MA_AP_ROOT/bin" 2>/dev/null
+  return 0
+}
+
+# Write via a temp file in the SAME directory then rename. The menu bar polls
+# status.json every few seconds, and a reader that catches a half-written file
+# shows an empty menu; rename is atomic on the same filesystem, so it never sees
+# a partial one.
+ma_ap_write() { # $1 = filename under the root; content on stdin
+  ma_ap_ensure_root || return 1
+  local dst="$MA_AP_ROOT/$1" tmp="$MA_AP_ROOT/.$1.$$"
+  cat > "$tmp" || {
+    rm -f "$tmp"
+    return 1
+  }
+  chmod 600 "$tmp" 2>/dev/null
+  mv -f "$tmp" "$dst"
+}
+
+ma_ap_append() { # $1 = filename, content on stdin - for the jsonl
+  ma_ap_ensure_root || return 1
+  local dst="$MA_AP_ROOT/$1"
+  cat >> "$dst" || return 1
+  chmod 600 "$dst" 2>/dev/null
+}
+
+ma_ap_read() { # $1 = filename; empty and exit 1 when absent
+  local src="$MA_AP_ROOT/$1"
+  [ -f "$src" ] || return 1
+  cat "$src"
+}
+
+# jq with a default, so a caller never has to distinguish "key absent" from
+# "file absent" from "file unparseable" - all three mean "use the default".
+ma_ap_cfg() { # $1 = jq path, $2 = default
+  local v
+  v=$(ma_ap_read config.json 2>/dev/null | jq -r "$1 // empty" 2>/dev/null)
+  [ -n "$v" ] && printf '%s\n' "$v" || printf '%s\n' "$2"
+}
+
+# AC or battery. The mode holds a sleep assertion only on AC: a queue that keeps
+# a laptop awake on battery is a bug, and `StartInterval` does not wake a
+# sleeping Mac anyway, so on battery the work resumes when you plug in.
+ma_ap_power() {
+  case "$(pmset -g ps 2>/dev/null | head -1)" in
+    *"AC Power"*) printf 'ac\n' ;;
+    *) printf 'battery\n' ;;
+  esac
+}
+
+# Boot time, so a stale runner.pid cannot be mistaken for a live runner. After a
+# restart pids start low and the recorded 4711 may belong to something unrelated;
+# a pid recorded BEFORE the current boot is stale by definition, with no probing.
+# The pattern is ANCHORED on purpose. `kern.boottime` prints
+# `{ sec = 1788181644, usec = 618574 } Mon Aug 31 ...`, and `.*sec = ` is greedy:
+# it walks past `sec` to `usec` and captures 618574, the microseconds. The
+# original form here did exactly that, so this returned a six-digit number that
+# looked plausible and never matched the same fact read anywhere else - which is
+# how the runner's staleness check compared two different numbers and called a
+# live runner dead.
+ma_ap_boottime() {
+  sysctl -n kern.boottime 2>/dev/null | sed -n 's/^{ *sec = \([0-9]*\).*/\1/p'
+}
+
+# The machine's honest ceiling, so raising `slots` is a measured decision. RAM
+# and cores bound the concurrent Claude sessions; disk bounds the worktrees
+# (0.75 GB each, measured at 11 GB across 15). The hard cap is 4 because beyond
+# that the bottleneck stops being this machine.
+ma_ap_slot_ceiling() {
+  local ram_gb cores free_gb a b c
+  ram_gb=$(( $(sysctl -n hw.memsize 2>/dev/null || echo 0) / 1073741824 ))
+  cores=$(sysctl -n hw.ncpu 2>/dev/null || echo 2)
+  free_gb=$(df -g "$HOME" 2>/dev/null | awk 'NR==2{print $4}')
+  [ -n "$free_gb" ] || free_gb=0
+  a=$(((ram_gb - 4) * 10 / 25))
+  b=$((cores / 2))
+  c=$(((free_gb - 20) * 100 / 75))
+  local m=$a
+  [ "$b" -lt "$m" ] && m=$b
+  [ "$c" -lt "$m" ] && m=$c
+  [ "$m" -gt 4 ] && m=4
+  [ "$m" -lt 1 ] && m=1
+  printf '%s\n' "$m"
+}

package/pipeline/lib/issue-fetcher.sh

@@ -49,8 +49,23 @@
 
 set -euo pipefail
 
+# Sourcing this file hands a caller the provider helpers - `jira_search`,
+# `fetch_jira`, `fetch_github` and the `jira_curl` underneath them - without
+# resolving anything. Executing it resolves one input, exactly as before.
+#
+# The guard exists because the alternative is worse than it looks: a second
+# consumer of `jira_search` with no way to source would have to copy
+# `jira_curl`, and that function is not a URL - it is the credential resolution,
+# the host lookup and the rule that keeps a token off argv. Three copies of that
+# is three places for a token to leak.
+MA_IF_EXECUTED=0
+[ "${BASH_SOURCE[0]}" = "$0" ] && MA_IF_EXECUTED=1
+
 INPUT="${1:-}"
-[ -z "$INPUT" ] && { echo '{"error":"input required"}'; exit 1; }
+if [ "$MA_IF_EXECUTED" = 1 ] && [ -z "$INPUT" ]; then
+  echo '{"error":"input required"}'
+  exit 1
+fi
 
 JIRA_TOKEN_KEY="${ACCOUNT_JIRA_TOKEN_KEY:-}"
 JIRA_HOST="${ACCOUNT_JIRA_HOST:-}"
@@ -361,6 +376,7 @@ PY
 }
 
 # --- Dispatch -----------------------------------------------------------------
+if [ "$MA_IF_EXECUTED" = 1 ]; then
 case "$KIND" in
   jira-id)
     KEY="$INPUT"
@@ -592,3 +608,4 @@ sys.stdout.write("\x1f".join(parts))
       "description=" "branchHint=$branch"
     ;;
 esac
+fi

package/pipeline/lib/plan-todos.sh

@@ -94,6 +94,24 @@ do_set() {
   if [ -z "$plan_blob" ] || [ "$plan_blob" = "-" ]; then
     plan_blob=$(cat)
   fi
+  # A planning-output document is accepted directly and converted here.
+  #
+  # The conversion used to live as a jq blob inside phase-2-planning.md, which
+  # made the mapping from `tasks[]` to `todos[]` a thing two files defined - and
+  # the phase doc was the copy nothing tested. Accepting both shapes costs four
+  # lines and removes the second definition.
+  if jq -e '.tasks and (.todos | not)' <<<"$plan_blob" >/dev/null 2>&1; then
+    plan_blob=$(jq '{
+      title: (.summary // .title // "plan"),
+      todos: [ .tasks[] | {
+        id: .id,
+        task: (.title // .subject // ""),
+        status: "pending",
+        deps: (.dependsOn // .blockedBy // [])
+      } ]
+    }' <<<"$plan_blob")
+  fi
+
   # Validate against schema (best-effort  -  jq syntax check, then required-field probe).
   if ! jq -e '.title and (.todos | type == "array")' <<<"$plan_blob" >/dev/null 2>&1; then
     echo "plan-todos: input must be an object with .title (string) and .todos (array)" >&2

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

@@ -10,35 +10,89 @@ Every Jira comment posted by this adapter follows the same section order. Sectio
 
 | # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
 |---|---|---|---|---|
-| 1 | `summary` | `## Yapılan Çalışma Özeti` | `## Work Summary` | always |
+| 1 | `summary` | `## Geliştirme Özeti` | `## Development Summary` | always |
 | 2 | `test_scenarios` | `## Test Senaryoları` | `## Test Scenarios` | always (use " - " placeholder line if truly N/A) |
-| 3 | `context_refs` | `## Bağlantılar` | `## References` | when any link exists |
+| 3 | `impact` | `## Etki Analizi` | `## Impact Analysis` | always |
+| 4 | `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.
 
+**Jira is not the PR, and this is the contract that keeps getting that wrong.**
+The PR is read by a reviewer holding the diff. The Jira comment is read by the
+person who filed the ticket and by the tester who has to verify it, and neither
+of them has the diff open. So a Jira body carries no identifiers, no file paths,
+no stack frames, no diff hunks and no framework names. Counts in prose are fine
+and are often the most useful sentence in the comment ("two files, eight lines
+removed, no additions"); a class name is not. A sentence that needs a symbol to
+make its point is describing the change at the wrong level for this reader -
+restate the behaviour, not the mechanism. The technical account has a home, and
+it is the PR body (`channels/pr.md`).
+
 ### Section content rules
 
 **`summary`**  -  2-5 sentences in `outputLanguage`. What changed, why, and the user-visible impact. No "we", no marketing tone. Past tense (the work is done at the time the comment goes up).
 
-**Visual evidence inside these two sections.** When `state.visualEvidence` carries artefacts, they render INSIDE `summary` and `test_scenarios` - never as a fourth section, which the fixed section order forbids. Upload first (`jira-attach.sh <issue> <file>...`), then reference by the returned filename:
+**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 6 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.
 
 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`.
 
-**`test_scenarios`**  -  Given/When/Then numbered list. One scenario per acceptance criterion. The heading and scenario text are rendered in `outputLanguage` at write-time; the template itself (this file) shows the English skeleton:
+**`test_scenarios`**  -  one titled scenario per acceptance criterion, each a
+numbered list of steps ending in the expected result. Given/When/Then was the
+shape here for several releases and it reads as translated English to the person
+who actually runs these; a tester wants a list they can follow with the app open.
+The heading and the text render in `outputLanguage`; this file shows the English
+skeleton:
 
 ```markdown
 ## Test Scenarios
 
-1. **Given** a signed-in user
-   **When** they navigate to the Profile screen
-   **Then** their saved preferences appear in the configured order
-2. **Given** ...
+**1. <what this scenario exercises>**
+1. <step the tester performs, in the app's own words>
+2. <step>
+3. **Expected:** <what they should see>
+
+**2. <regression scenario>**
+1. <step>
+2. **Expected:** <what should still behave as before>
 ```
 
-Code identifiers (function names, file paths) stay verbatim  -  they are not translated. When there are no executable scenarios (pure doc change, dependency bump), write a single line: `- No manual test required  -  <short reason>`.
+Order is load-bearing. The scenarios that reproduce the reported behaviour come
+first, then the regression scenarios for whatever the change could have disturbed -
+anything sharing the component that was touched. A comment that lists only the fix
+leaves the tester to guess the blast radius, and that guess is the one thing they
+cannot make from the ticket.
+
+Screens, fields and menu items are named the way the app shows them, in
+`outputLanguage`. Function names and file paths do not appear at all, per the rule
+above. When there are no executable scenarios (pure doc change, dependency bump),
+write a single line: `- No manual test required  -  <short reason>`.
+
+**`impact`**  -  four fixed numbered parts, each answered, never left as a
+placeholder. This is what a test lead reads before deciding how wide to test and
+what a release manager reads before deciding whether it ships this week, so it is
+written in the same plain register as the rest of the comment:
+
+```markdown
+## Impact Analysis
+
+**1 - The problem**
+<what was wrong and since when, in the reader's words>
+
+**2 - What was changed**
+<what the change does, and why the behaviour around it is unchanged>
+
+**3 - Affected areas**
+<the screens and flows that must be tested, including anything sharing the changed component>
+
+**4 - Effect on other systems**
+<none, or which service, contract or channel is affected>
+```
+
+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.
 
 **`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):
 
@@ -58,7 +112,7 @@ 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  -  summary first, test_scenarios next, context_refs last.
+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).
 4. Apply Cross-link injection (PR URL on line 1).
 5. Run Wiki markup conversion.
@@ -116,7 +170,7 @@ Do not hand-apply this table. It was hand-applied for several releases and a smi
 
 Lines outside these patterns pass through verbatim. Multi-paragraph blocks are joined with one blank line.
 
-Every row above is load-bearing, including the ones that look cosmetic. The table must cover each construct the section templates in this file actually emit  -  `##` for the three required headings, `**Given**` / `**When**` / `**Then**` in the test-scenario skeleton, and `1.`-numbered scenarios. A missing row does not degrade gracefully: the "pass through verbatim" fallback POSTs `## Test Senaryoları` and `**Given**` as literal text, so the comment renders with visible `##` and stray asterisks. Single `*bold*` in Markdown means *italic* in Jira wiki  -  never map `**bold**` to `*bold*` by dropping one asterisk mechanically without checking the source was bold, not italic.
+Every row above is load-bearing, including the ones that look cosmetic. The table must cover each construct the section templates in this file actually emit  -  `##` for the four required headings, `**1. title**` on a scenario and `**Expected:**` inside it, the `**1 - ...**` part labels in the impact section, and `1.`-numbered steps. A missing row does not degrade gracefully: the "pass through verbatim" fallback POSTs `## Test Senaryoları` and `**Expected:**` as literal text, so the comment renders with visible `##` and stray asterisks. Single `*bold*` in Markdown means *italic* in Jira wiki  -  never map `**bold**` to `*bold*` by dropping one asterisk mechanically without checking the source was bold, not italic.
 
 There is no markdown→Jira-wiki converter program in the pipeline (`lib/` ships `md2confluence-v3.py` for Confluence only, and `scripts/jira-wiki-escape.mjs` covers the emoticon step alone). This conversion table is applied by the model, by hand, which is exactly why it has to be complete.
 
@@ -149,19 +203,25 @@ Authorization: Bearer $JIRA_TOKEN
 Content-Type: application/json
 ```
 
-Body assembled with `jq --rawfile` + `curl --data-binary @file`, from the escaped file that *Emoticon escaping* produced:
+**Post through `jira-publish.sh`. Never hand-roll the `curl`.**
 
 ```bash
-node "$HOME/.claude/scripts/jira-wiki-escape.mjs" --check /tmp/channels-$TASK_ID-jira-escaped.txt \
-  || { echo "unescaped Jira emoticon in the body - do not POST" >&2; exit 1; }
-jq -n --rawfile body /tmp/channels-$TASK_ID-jira-escaped.txt '{body: $body}' \
-  > /tmp/channels-$TASK_ID-jira-payload.json
-curl -s -X POST -H "Authorization: Bearer $JIRA_TOKEN" \
-     -H "Content-Type: application/json" \
-     --data-binary @/tmp/channels-$TASK_ID-jira-payload.json \
-     "$JIRA_BASE/rest/api/2/issue/$JIRA_ID/comment"
+bash "$HOME/.claude/lib/jira-publish.sh" --issue "$JIRA_ID" \
+  --body-file /tmp/channels-$TASK_ID-jira.txt --target comment
 ```
 
+That script escapes every body unconditionally (`lib/jira-publish.sh:109`) and
+passes the token through a `-K` config rather than argv, so neither the escape
+nor the token handling depends on an agent remembering a step.
+
+This block used to be a hand-written `jq` + `curl` pair with the escape as a
+separate `--check` line above it, and a shipped comment rendered the Swift
+selector `hash(into:)` as `hash(into` plus a smiley - twice. The escaper was
+present, correct, and simply not run on that path: `:)` reached Jira intact and
+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.
+
 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)

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

@@ -10,20 +10,31 @@ The PR description targets code reviewers  -  it stays technical. Every adapter
 
 | # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
 |---|---|---|---|---|
-| 1 | `summary` | `## Özet` | `## Summary` | always |
-| 2 | `changes` | `## Değişiklikler` | `## Changes` | always |
+| 1 | `summary` | `## Geliştirme Özeti` | `## Development Summary` | always |
+| 2 | `technical` | `## Teknik Açıklama` | `## Technical Explanation` | always |
 | 3 | `architecture` | `## Mimari Kararlar` | `## Architecture Decisions` | when a non-trivial design choice was made |
-| 4 | `verification` | `## Doğrulama` | `## Verification` | always |
-| 5 | `visuals` | `## Görsel Kanıt` | `## Visual Evidence` | when `state.visualEvidence.required` |
-| 6 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
-| 7 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
-| 8 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+| 4 | `impact` | `## Etki Analizi` | `## Impact Analysis` | always |
+| 5 | `test_scenarios` | `## Test Senaryoları` | `## Test Scenarios` | always |
+| 6 | `visuals` | `## Görsel Kanıt` | `## Visual Evidence` | when `state.visualEvidence.required` |
+| 7 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
+| 8 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
+| 9 | `build` | `## Build` | `## Build` | always |
+| 10 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+
+`summary`, `impact` and `test_scenarios` carry the same three section keys the
+Jira adapter uses, and that pairing is deliberate: the same three questions get
+answered on both surfaces, at the register each reader needs. The PR versions name
+symbols, files, line counts and build shas. The Jira versions name screens and
+behaviour and nothing else (`channels/jira.md`). `technical` has no Jira twin at
+all - it is the section whose absence over there is the point.
 
 ### Section content rules
 
-**`summary`**  -  1-3 sentences in `outputLanguage`. The "why" of the change. Past tense, no marketing voice. Code identifiers stay verbatim.
+**`summary`**  -  2-4 sentences in `outputLanguage`. What broke or what was added, where the user meets it, and the size of the effect when it is measurable (a crash count, a share of a known total, a version range). Past tense, no marketing voice. Code identifiers stay verbatim. This is the one section a reviewer reads before deciding whether to read the rest, so it names the user-visible behaviour before the mechanism.
 
-**`changes`**  -  bullet list, one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". The source is `$WORKTREE/.pipeline/scope-check.json` `files[].reason` (Phase 3 Step 3.7): a file the dev could not justify there is a file this list cannot describe either, so the bullet quotes the gate output instead of inventing a reason. Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
+**`technical`**  -  the account for someone holding the diff: a short paragraph on the mechanism (what the code was actually doing wrong, or what the new code does), then the per-file bullets, then one line of diff stat (`2 files, 8 deletions, 0 insertions`). Where a change is safe for a reason that is not obvious from the diff - an equality relation preserved, an invariant kept, a call site left alone deliberately - that reason belongs here in a sentence, because it is the question the reviewer would otherwise ask in a comment. Tables are welcome when several symbols share a property worth listing side by side.
+
+The bullet list is one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". The source is `$WORKTREE/.pipeline/scope-check.json` `files[].reason` (Phase 3 Step 3.7): a file the dev could not justify there is a file this list cannot describe either, so the bullet quotes the gate output instead of inventing a reason. Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
 
 ```markdown
 ## Changes
@@ -37,20 +48,55 @@ Across stacks the same shape produces, for example: `LoginView.swift  -  ...` (i
 
 **`architecture`**  -  only when the change involves a non-trivial decision (new abstraction, pattern change, data flow shift, dependency direction). Format: short paragraph stating the decision and the alternative considered. Skip the section entirely for mechanical refactors / dependency bumps / formatting passes.
 
-**`verification`**  -  what the reviewer should run to confirm the change works. Commands first, manual steps next. Pick the commands for the project's stack  -  the pipeline supports iOS (Swift/Xcode), Android (Gradle), web (npm/pnpm/yarn), and backend (varies: pytest/jest/go test/etc). Do not hardcode one stack in the body; emit only the commands relevant to the repos touched by this PR.
+**`impact`**  -  four fixed numbered parts, each answered, never a placeholder. Same four questions as the Jira `impact` section, answered here with the identifiers and numbers that section is not allowed to carry:
+
+```markdown
+## Impact Analysis
+
+**1 - The problem**
+<what was wrong, since which version, with the crash/report identifiers and counts>
+
+**2 - What was changed**
+<the change, and why behaviour around it is unchanged>
+
+**3 - Affected functions**
+<the screens, flows and symbols that must be tested, including shared components the change reaches>
+
+**4 - Effect on other systems**
+<none, or which service, contract or channel>
+```
+
+When the change deliberately fixes part of a wider problem, a closing **Risk and remaining scope** paragraph names what is still open and why it was left - a reviewer who can see the rest of the pattern in the repo will ask otherwise, and the honest answer is cheaper written down than defended in a thread.
 
-Skeleton (the adapter fills the body with the actual stack-appropriate lines at write-time; the template lists the shape only):
+**`test_scenarios`**  -  the same titled-scenario shape the Jira adapter uses, so the tester reads one list on both surfaces, with symbols allowed here:
 
 ```markdown
-## Verification
+## Test Scenarios
 
-- Build: <stack-appropriate build command>
-- Tests: <stack-appropriate test command, scoped to the touched targets/packages>
-- Lint / type-check: <if the project has one>
-- Manual: <one or more user-facing steps the reviewer can follow without setup>
+**1. <what this scenario exercises>**
+1. <step>
+2. **Expected:** <observable outcome>
+
+**2. <regression scenario>**
+1. <step>
+2. **Expected:** <what should still behave as before>
+```
+
+Reproduction scenarios first, then regressions for whatever the change could have disturbed. When a UI test target covers a scenario, say so on the scenario line and let `## Build` carry the run result - a scenario a machine already ran is not the same request as one a human has to perform, and conflating them wastes the reviewer's time.
+
+**`build`**  -  what was built, on what, and what came out. Not a promise that it builds; the recorded result of the run that happened:
+
+```markdown
+## Build
+
+- <build command or scheme> on <base branch>@<sha>: BUILD SUCCEEDED, 0 errors
+- Tests: <test command>: <N> passed, <M> failed
+- UI tests: <target>: <status> | not run  -  <reason from state.uiTest.notRunReason>
 ```
 
-Multi-repo PRs (one PR per repo) emit verification commands for that repo's stack only  -  never mix iOS + Android commands into a single PR body.
+The base sha matters because "it builds" is a claim about a merge base, and the reviewer's local tree is usually not that one. `state.uiTest` supplies the third line verbatim, including its `notRunReason` - "no UI test target in this repo" is a result, not a gap, and writing it stops the same question being asked on every PR.
+
+Pick commands for the project's stack  -  the pipeline supports iOS (Swift/Xcode), Android (Gradle), web (npm/pnpm/yarn) and backend (pytest/jest/go test/etc). Multi-repo PRs (one PR per repo) emit the commands for that repo's stack only  -  never mix iOS + Android commands into a single PR body.
 
 **`risk`**  -  only when `state.diffRisk.signals` (Phase 4 Step 1.75) contains a high-stakes signal. Four fixed lines, each answered, never left as a placeholder; the source is Phase 1 `touchedAreas` plus the signals themselves, and when a signal is present the absence of this section is a Phase 6 Step 3 blocker:
 
@@ -136,7 +182,7 @@ Never use `Closes #N`, `Fixes #N`, `Resolves PROJ-X`. Issues require 4-approval
 
 ```
 1. Read agent-state.json (taskId, contextLinks, identity, language).
-2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply. Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `risk` (cond.) → `dependencies` (cond.) → `related`.
+2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply. Section order is fixed: `summary` → `technical` → `architecture` (cond.) → `impact` → `test_scenarios` → `visuals` (cond.) → `risk` (cond.) → `dependencies` (cond.) → `build` → `related`.
 3. Run the assembled body through the `humanizer` skill.
 4. Apply Multi-repo cross-links (## Related PRs prepend when projects.length > 1).
 5. Dispatch per the Behaviour-by-remote table.
@@ -220,7 +266,7 @@ The Bitbucket REST API returns `409 Conflict` if `version` is stale. Adapter beh
 ## Hard rules (must not regress)
 
 - Real newlines, no HTML entities  -  heredoc + `jq --rawfile` + `curl --data-binary @file`. Never embed `\n` literally; Bitbucket stores the literal `\n` characters.
-- Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `dependencies` (cond.) → `related`. Conditional sections may be omitted but never reordered or inserted between fixed ones.
+- Section order is fixed: `summary` → `technical` → `architecture` (cond.) → `impact` → `test_scenarios` → `visuals` (cond.) → `risk` (cond.) → `dependencies` (cond.) → `build` → `related`. Conditional sections may be omitted but never reordered or inserted between fixed ones.
 - Humanizer pass runs **after** body assembly and **before** dispatch  -  every body line carries technical, non-AI tone. References at least one symbol/file/line drawn from the diff or pipeline log.
 - Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, branch names, PR titles, commands, type names, and `Closes/Fixes`-style keywords stay verbatim English. The template file (this doc) is English because `promptLanguage="en"` is locked; the body is rendered in the user's language at write-time.
 - No body markers (`<!-- channels:start -->`)  -  channels does a full replace each run.

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

@@ -6,13 +6,14 @@
 
 ---
 
-## 1. Command Inventory (53 commands)
+## 1. Command Inventory (56 commands)
 
 ```
-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,
+analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
+autopilot-on, autopilot-status, build-optimize, channels, complaint-analysis,
+create-jira, design-check, diff-explain, doctor, 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,
 review-analysis, review-issue, review-jira, routines, save, scan, search,
 setup, stack, status, steer, store-ready, sync, test, test-accessibility,