@mmerterden/multi-agent-pipeline 17.0.0 → 17.3.0

package/pipeline/lib/autopilot-state.sh

@@ -0,0 +1,184 @@
+#!/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
+#   ma_ap_asset <rel>          # resolve a script/lib/template across the 3 host roots
+
+set -uo pipefail
+
+MA_AP_ROOT="${MA_AUTOPILOT_ROOT:-$HOME/.claude/autopilot}"
+
+ma_ap_root() { printf '%s\n' "$MA_AP_ROOT"; }
+
+# Where the scripts, libs and templates this mode needs actually live.
+#
+# This file ships into whichever host tree installed it, and a Copilot-only or
+# Codex-only machine has no ~/.claude/scripts, no ~/.claude/lib and - the one
+# that bites hardest - no ~/.claude/templates, which only install/claude.mjs
+# creates. phase-tracker.sh already carries this resolver and its comment names
+# what happens without it: "a hard-coded path silently disabled every live ping
+# on those hosts". Autopilot reproduced the class; this is the same answer.
+#
+# The STATE root above is deliberately NOT resolved this way. ~/.claude/autopilot/
+# is shared across hosts on purpose, exactly like logs/, knowledge/ and
+# multi-agent-preferences.json, because two CLIs on one machine must see ONE
+# queue. Resolving it per host would hand a Copilot session a second, invisible
+# queue and the same item would be taken twice.
+MA_AP_HOST_ROOT="${MA_AP_HOST_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)}"
+
+ma_ap_asset() { # $1 = path relative to a host root, e.g. scripts/autopilot-runner.mjs
+  local rel="$1" root
+  # The tree this file was sourced from wins: on a machine with all three
+  # installed, the caller's own tree is the one that is current.
+  if [ -n "$MA_AP_HOST_ROOT" ] && [ -e "$MA_AP_HOST_ROOT/$rel" ]; then
+    printf '%s\n' "$MA_AP_HOST_ROOT/$rel"
+    return 0
+  fi
+  for root in "$HOME/.claude" "$HOME/.copilot" "$HOME/.codex"; do
+    if [ -e "$root/$rel" ]; then
+      printf '%s\n' "$root/$rel"
+      return 0
+    fi
+  done
+  return 1
+}
+
+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/_dev-context.md

@@ -4,6 +4,16 @@ description: "Internal  -  dev context (extra repos) picker for multi-agent."
 
 # _dev-context  -  Extra Dev Repo Selection
 
+<!-- toc -->
+- [Steps](#steps)
+- [Web repos  -  `webRepos`](#web-repos---webrepos)
+- [Pref override  -  `editableRelatedRepos`](#pref-override---editablerelatedrepos)
+- [Output](#output)
+- [Rule](#rule)
+- [Autopilot Behavior](#autopilot-behavior)
+- [Pipeline contract for read-only siblings](#pipeline-contract-for-read-only-siblings)
+<!-- /toc -->
+
 Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typically submodules (e.g. SDKs vendored inside an app repo) or sibling libraries. Each candidate is enriched with a `canPush` flag so the picker can pre-select repos that the active account is allowed to edit, and surface read-only ones as advisory context the pipeline will not modify.
 
 > **Language**: see `picker-contract.md` + `rules.md` Language Application matrix.

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

@@ -1,5 +1,13 @@
 # Redesign mode - the contract
 
+<!-- toc -->
+- [What the mode is for](#what-the-mode-is-for)
+- [Why it is an option and not a mode](#why-it-is-an-option-and-not-a-mode)
+- [The three artefacts](#the-three-artefacts)
+- [The eight checks](#the-eight-checks)
+- [The cache, and the silent failure to avoid](#the-cache-and-the-silent-failure-to-avoid)
+<!-- /toc -->
+
 Loaded only when `state.analysisSpec.options.redesign` is true, the same way
 `analysis/review.md` is loaded only by a reviewer subagent. A run that is not a
 redesign never pays for this file.

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

@@ -1,5 +1,14 @@
 # Analysis document review (`/multi-agent:review-analysis`)
 
+<!-- toc -->
+- [Phase 0 - Resolve the document](#phase-0---resolve-the-document)
+- [Phase 1 - Deterministic gates first](#phase-1---deterministic-gates-first)
+- [Phase 1.5 - What did the run skip?](#phase-15---what-did-the-run-skip)
+- [Phase 2 - Rubric](#phase-2---rubric)
+- [Phase 3 - Triage and verdict](#phase-3---triage-and-verdict)
+- [Phase 4 - Output](#phase-4---output)
+<!-- /toc -->
+
 > Reviews a written analysis the way `/multi-agent:review` reviews a diff. Loaded on demand. Read-only: no branch, no worktree, no commit, and the source document is never edited in place.
 
 `/multi-agent:review` answers "is this code right". This answers "could an implementer build the thing from this document, and does the document keep the promises its own contract makes". The two are different questions with the same failure mode: a reviewer who has opinions instead of rules produces findings nobody can act on. So this flow cites `Locked <n>` the way a code review cites a rule ID.

package/pipeline/multi-agent-refs/android-guide.md

@@ -1,5 +1,19 @@
 ## Android/Kotlin Component Generation Guide
 
+<!-- toc -->
+- [Component Architecture: State / Screen / Content](#component-architecture-state-screen-content)
+- [Simple vs Complex Decision](#simple-vs-complex-decision)
+- [State Pattern](#state-pattern)
+- [Token Discipline](#token-discipline)
+- [Stability for Performance](#stability-for-performance)
+- [Accessibility](#accessibility)
+- [Preview Best Practices](#preview-best-practices)
+- [Testing](#testing)
+- [Build Verification](#build-verification)
+- [Component Quality Checklist](#component-quality-checklist)
+- [Compliance Rules (maps to multi-agent-toolkit MCP audit tools)](#compliance-rules-maps-to-multi-agent-toolkit-mcp-audit-tools)
+<!-- /toc -->
+
 > **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single Composable line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
 
 When the task involves creating an Android UI component (Jetpack Compose), follow this architecture.

package/pipeline/multi-agent-refs/audit-guide.md

@@ -1,5 +1,17 @@
 ## Audit & Quality Tools Guide
 
+<!-- toc -->
+- [Trigger Model](#trigger-model)
+- [iOS Accessibility Audit](#ios-accessibility-audit)
+- [Android Accessibility Audit](#android-accessibility-audit)
+- [iOS Biometric Test](#ios-biometric-test)
+- [Android Launch Time](#android-launch-time)
+- [iOS Archive Audit (App Store Compliance)](#ios-archive-audit-app-store-compliance)
+- [Android APK Audit (Play Store Compliance)](#android-apk-audit-play-store-compliance)
+- [Integration with Pipeline Phases](#integration-with-pipeline-phases)
+- [Graceful Degradation](#graceful-degradation)
+<!-- /toc -->
+
 Standalone audit commands  -  runs directly via Bash, **no MCP server dependency**. These are the same checks that multi-agent-toolkit-mcp provides as MCP tools, but embedded here as pipeline skills.
 
 ### Trigger Model

package/pipeline/multi-agent-refs/backend-guide.md

@@ -1,5 +1,15 @@
 ## Backend API Development Guide
 
+<!-- toc -->
+- [API Architecture](#api-architecture)
+- [Python/FastAPI Pattern](#pythonfastapi-pattern)
+- [Node.js/Express Pattern](#nodejsexpress-pattern)
+- [Error Handling](#error-handling)
+- [Security Checklist](#security-checklist)
+- [Testing](#testing)
+- [Quality Checklist](#quality-checklist)
+<!-- /toc -->
+
 When the task involves backend development (Python/FastAPI, Node.js/Express, Go), follow these patterns.
 
 ### API Architecture

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

@@ -1,5 +1,16 @@
 # Channel adapter  -  Confluence page
 
+<!-- toc -->
+- [Required body structure](#required-body-structure)
+- [Token check](#token-check)
+- [Parent page resolution](#parent-page-resolution)
+- [Page title](#page-title)
+- [Body conversion (markdown → storage format)](#body-conversion-markdown-storage-format)
+- [POST contract](#post-contract)
+- [Recents persistence](#recents-persistence)
+- [Hard rules (must not regress)](#hard-rules-must-not-regress)
+<!-- /toc -->
+
 > Detailed contract for the `confluence` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here.
 
 The Confluence adapter creates or updates a Confluence page under a chosen parent. Like the Jira adapter, it runs **once** per invocation  -  the page lives at the primary repo's component slug in multi-repo mode.

package/pipeline/multi-agent-refs/channels/issue-comment.md

@@ -1,5 +1,17 @@
 # Channel adapter  -  GitHub Issue comment
 
+<!-- toc -->
+- [When this fires](#when-this-fires)
+- [The hard rule](#the-hard-rule)
+- [Required body structure](#required-body-structure)
+- [Hard prohibitions](#hard-prohibitions)
+- [Compaction policy](#compaction-policy)
+- [API contract](#api-contract)
+- [Pairing with the Progress flag updater](#pairing-with-the-progress-flag-updater)
+- [Drift detection](#drift-detection)
+- [Hard rules (must not regress)](#hard-rules-must-not-regress)
+<!-- /toc -->
+
 > Canonical template for the `issue` channel of `/multi-agent:channels`. Every successful run that touched a tracked GitHub issue MUST post one comment using this template  -  no exceptions, no "state-only" shortcuts.
 
 ## When this fires

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

@@ -1,5 +1,15 @@
 # Channel adapter  -  Jira comment
 
+<!-- toc -->
+- [Required body structure](#required-body-structure)
+- [Wiki markup conversion](#wiki-markup-conversion)
+- [Cross-link injection](#cross-link-injection)
+- [Token resolution](#token-resolution)
+- [POST contract](#post-contract)
+- [Wiki → Jira auto-link triad](#wiki-jira-auto-link-triad)
+- [Hard rules (must not regress)](#hard-rules-must-not-regress)
+<!-- /toc -->
+
 > Detailed contract for the `jira` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here.
 
 The Jira adapter posts a comment on the linked issue. The Jira ticket is shared by all repos in a multi-repo task, so the adapter runs **once** per channels invocation regardless of how many PR targets are dispatched in parallel.
@@ -10,35 +20,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>
+```
+
+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>
 ```
 
-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>`.
+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 +122,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 +180,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 +213,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-review-actions.md

@@ -1,5 +1,18 @@
 # Channel adapter  -  Pull Request review actions
 
+<!-- toc -->
+- [When this fires](#when-this-fires)
+- [The decision rule](#the-decision-rule)
+- [Inline comment template (per finding)](#inline-comment-template-per-finding)
+- [Decision endpoints](#decision-endpoints)
+- [Order of operations](#order-of-operations)
+- [Hard prohibitions](#hard-prohibitions)
+- [Idempotency](#idempotency)
+- [Provider auto-detection](#provider-auto-detection)
+- [Pairing with the chat summary](#pairing-with-the-chat-summary)
+- [Drift detection](#drift-detection)
+<!-- /toc -->
+
 > Canonical contract for the PR-actions branch of `/multi-agent:review`. The PR-side artifacts are **per-finding inline comments + an explicit approve / needs-work decision**  -  never a single monolithic description comment.
 
 ## When this fires