@mmerterden/multi-agent-pipeline 16.18.0 → 16.19.0

package/pipeline/lib/figma-screenshot.sh

@@ -81,6 +81,8 @@ if ! command -v resolve_figma_token >/dev/null 2>&1; then
 fi
 
 FIGMA_API="https://api.figma.com/v1"
+WORK_DIR=$(mktemp -d "${TMPDIR:-/tmp}/figma-screenshot.XXXXXX")
+trap 'rm -rf "$WORK_DIR"' EXIT INT TERM
 PARALLEL_DL=4
 HTTP_TIMEOUT=60
 MAX_IDS_PER_CALL=50
@@ -126,7 +128,8 @@ Options:
                    hold the other channel's design" before a run may write that a
                    channel has none. Emits JSON, downloads nothing.
   --feature-slug   Feature name to match against, for --discover-sections.
-  --output-dir     Output directory. Default: /tmp/figma-screenshots-<ts>.
+  --output-dir     Output directory. Default: a fresh mktemp dir
+                   ($TMPDIR/figma-screenshots.XXXXXX).
   --scale          Render scale (1-4). Default: 2.
   --format         Image format. Default: png.
   --help           Show this help text and exit.
@@ -256,7 +259,7 @@ fetch_nodes_metadata() {
 fetch_image_urls() {
   local ids="$1"
   local tmp
-  tmp=$(mktemp)
+  tmp=$(mktemp "$WORK_DIR/images.XXXXXX")
   local url="$FIGMA_API/images/$FILE_KEY?ids=$ids&format=$FORMAT&scale=$SCALE"
   local code
   code=$(curl_figma "$tmp" "$url")
@@ -281,7 +284,7 @@ render_and_download() {
 
   # Emit a job list (nodeId<TAB>url<TAB>outPath) for parallel download.
   local jobs
-  jobs=$(mktemp)
+  jobs=$(mktemp "$WORK_DIR/jobs.XXXXXX")
   local key_prefix="${FILE_KEY:0:4}"
   printf '%s' "$urls_json" | jq -r 'to_entries[] | "\(.key)\t\(.value)"' \
     | while IFS=$'\t' read -r nid url; do
@@ -292,7 +295,7 @@ render_and_download() {
 
   # Parallel download. xargs -P keeps the channel count bounded.
   local results
-  results=$(mktemp)
+  results=$(mktemp "$WORK_DIR/results.XXXXXX")
   # shellcheck disable=SC2016
   awk -F'\t' '{printf "%s\037%s\037%s\n", $1,$2,$3}' "$jobs" \
     | xargs -P "$PARALLEL_DL" -I{} bash -c '
@@ -389,17 +392,19 @@ if [ "$#" -eq 0 ]; then
   exit 1
 fi
 
+need_value() { [ "$#" -ge 2 ] || die 1 "$1 requires a value"; }
+
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --help|-h) print_help; exit 0 ;;
-    --file-key) FILE_KEY="${2:-}"; shift 2 ;;
-    --node-id)  NODE_ID="${2:-}"; shift 2 ;;
-    --section)  SECTION_URL="${2:-}"; shift 2 ;;
+    --file-key) need_value "$@"; FILE_KEY="$2"; shift 2 ;;
+    --node-id)  need_value "$@"; NODE_ID="$2"; shift 2 ;;
+    --section)  need_value "$@"; SECTION_URL="$2"; shift 2 ;;
     --discover-sections) DISCOVER=1; shift ;;
-    --feature-slug) FEATURE_SLUG="${2:-}"; shift 2 ;;
-    --output-dir) OUTPUT_DIR="${2:-}"; shift 2 ;;
-    --scale)    SCALE="${2:-2}"; shift 2 ;;
-    --format)   FORMAT="${2:-png}"; shift 2 ;;
+    --feature-slug) need_value "$@"; FEATURE_SLUG="$2"; shift 2 ;;
+    --output-dir) need_value "$@"; OUTPUT_DIR="$2"; shift 2 ;;
+    --scale)    need_value "$@"; SCALE="${2:-2}"; shift 2 ;;
+    --format)   need_value "$@"; FORMAT="${2:-png}"; shift 2 ;;
     *) die 1 "unknown argument: $1" ;;
   esac
 done
@@ -431,7 +436,7 @@ if [ -z "${FIGMA_TOKEN:-}" ]; then
 fi
 
 if [ -z "$OUTPUT_DIR" ]; then
-  OUTPUT_DIR="/tmp/figma-screenshots-$(date +%Y%m%d-%H%M%S)"
+  OUTPUT_DIR=$(mktemp -d "${TMPDIR:-/tmp}/figma-screenshots.XXXXXX")
 fi
 mkdir -p "$OUTPUT_DIR"
 
@@ -444,14 +449,12 @@ mkdir -p "$OUTPUT_DIR"
 # "Elite Kart" on one section and "Elit Kart" on its sibling.
 
 run_discover_mode() {
-  local body
-  # Same as fetch_with_retry: the token goes through a curl config on a process
-  # substitution, never argv, because argv is readable from ps.
-  body=$(curl -sS --max-time "$HTTP_TIMEOUT" --connect-timeout 5 \
-    -K <(printf 'header = "X-Figma-Token: %s"\n' "$FIGMA_TOKEN") \
-    "https://api.figma.com/v1/files/${FILE_KEY}?depth=3") || die 3 "file tree fetch failed"
-
-  printf '%s' "$body" | FEATURE_SLUG="$FEATURE_SLUG" FILE_KEY="$FILE_KEY" python3 -c '
+  local tree code
+  tree=$(mktemp "$WORK_DIR/tree.XXXXXX")
+  code=$(curl_figma "$tree" "$FIGMA_API/files/${FILE_KEY}?depth=3")
+  handle_http_code "$code" "file tree for $FILE_KEY"
+
+  FEATURE_SLUG="$FEATURE_SLUG" FILE_KEY="$FILE_KEY" python3 -c '
 import json, os, re, sys, unicodedata
 
 def fold(t):
@@ -475,11 +478,11 @@ def channel_of(name):
                 return label
     return None
 
-raw = sys.stdin.read()
+raw = open(sys.argv[1]).read()
 try:
     doc = json.loads(raw).get("document", {})
 except Exception:
-    print(json.dumps({"error": "unparseable file response"})); sys.exit(3)
+    print(json.dumps({"error": "unparseable file response"})); sys.exit(6)
 
 slug_words = [w for w in fold(os.environ["FEATURE_SLUG"]).split() if len(w) > 2]
 out, weak, pages = [], [], 0
@@ -516,7 +519,7 @@ print(json.dumps({
     "candidates": sorted(out, key=lambda c: (c["channelGuess"] or "zz", c["id"])),
     "weakMatches": sorted(weak, key=lambda c: c["id"]),
 }, ensure_ascii=False, indent=2))
-'
+' "$tree"
 }
 
 # --- Section mode -----------------------------------------------------------
@@ -570,7 +573,7 @@ PY
 
   # Collect ids and chunk to MAX_IDS_PER_CALL.
   local ids_file
-  ids_file=$(mktemp)
+  ids_file=$(mktemp "$WORK_DIR/ids.XXXXXX")
   awk -F'\t' '{print $1}' "$lookup" > "$ids_file"
 
   local rows

package/pipeline/lib/figma-token.sh

@@ -31,8 +31,9 @@
 # An unset or non-executable CRED_STORE is tolerated: resolution falls through to
 # the env fallback so a keychain-less CI box still works.
 
-# The canonical key first, the legacy key second. Space-separated so the loop
-# below stays POSIX-ish and works under bash 3.2 (stock macOS).
+# The canonical key first, the legacy key second. Space-separated; the loop
+# below splits explicitly because zsh (the pipeline's Bash tool) does not
+# word-split an unquoted parameter, so `for key in $KEYS` saw one key there.
 FIGMA_TOKEN_LOGICAL_KEYS="${FIGMA_TOKEN_LOGICAL_KEYS:-figma figma_pat}"
 
 # resolve_figma_token
@@ -40,13 +41,16 @@ FIGMA_TOKEN_LOGICAL_KEYS="${FIGMA_TOKEN_LOGICAL_KEYS:-figma figma_pat}"
 resolve_figma_token() {
   local key tok
   if [ -n "${CRED_STORE:-}" ] && [ -x "${CRED_STORE:-}" ]; then
-    for key in $FIGMA_TOKEN_LOGICAL_KEYS; do
+    while IFS= read -r key; do
+      [ -n "$key" ] || continue
       tok=$("$CRED_STORE" get "$key" 2>/dev/null || true)
       if [ -n "$tok" ]; then
         printf '%s' "$tok"
         return 0
       fi
-    done
+    done <<EOF_KEYS
+$(printf '%s\n' "$FIGMA_TOKEN_LOGICAL_KEYS" | tr ' ' '\n')
+EOF_KEYS
   fi
   if [ -n "${FIGMA_PAT:-}" ]; then
     printf '%s' "$FIGMA_PAT"

package/pipeline/lib/issue-fetcher.sh

@@ -43,7 +43,6 @@
 # Required env:
 #   ACCOUNT_JIRA_TOKEN_KEY    keychain service name (optional)
 #   ACCOUNT_JIRA_HOST         e.g. jira.example.com    (optional)
-#   ACCOUNT_GH_TOKEN_KEY      keychain service name (optional)
 #   ACCOUNT_DEFAULT_OWNER     fallback GitHub owner (optional)
 #   ACCOUNT_DEFAULT_REPO      fallback GitHub repo  (optional)
 #   PROMPT_LANG               tr|en  -  controls maturity.summary language (default: tr)

package/pipeline/lib/jira-publish.sh

@@ -54,13 +54,15 @@ BACKUP_DIR="${JIRA_BACKUP_DIR:-$HOME/.claude/logs/multi-agent/jira-backups}"
 
 die() { echo "$1" >&2; exit "${2:-64}"; }
 
+need_value() { [ "$#" -ge 2 ] || die "$1 requires a value"; }
+
 while [ "$#" -gt 0 ]; do
   case "$1" in
-    --issue) ISSUE="${2:-}"; shift 2 ;;
-    --body-file) BODY_FILE="${2:-}"; shift 2 ;;
-    --target) TARGET="${2:-}"; shift 2 ;;
-    --mode) MODE="${2:-}"; shift 2 ;;
-    --backup-dir) BACKUP_DIR="${2:-}"; shift 2 ;;
+    --issue) need_value "$@"; ISSUE="$2"; shift 2 ;;
+    --body-file) need_value "$@"; BODY_FILE="$2"; shift 2 ;;
+    --target) need_value "$@"; TARGET="$2"; shift 2 ;;
+    --mode) need_value "$@"; MODE="$2"; shift 2 ;;
+    --backup-dir) need_value "$@"; BACKUP_DIR="$2"; shift 2 ;;
     --confirm-overwrite) CONFIRM=1; shift ;;
     --dry-run) DRY_RUN=1; shift ;;
     -h|--help) sed -n '2,40p' "$0"; exit 0 ;;

package/pipeline/lib/md2confluence-v3.py

@@ -69,6 +69,11 @@ PUNCT_MAP_DEFAULT_TR = {
 PUNCT_MAP_EN = dict(PUNCT_MAP_DEFAULT_TR)
 PUNCT_MAP_EN["\u00A7"] = "section"
 
+# Typographic dashes (U+2010 to U+2015), quotes (U+2018 to U+201F), the
+# ellipsis and the section sign, including the variants the maps above do
+# not rewrite, so a residual can actually be reported.
+FORBIDDEN_PUNCT_RE = re.compile("[\u2010-\u2015\u2018-\u201F\u2026\u00A7]")
+
 
 def detect_language(markdown: str, front_matter_lang: str | None) -> str:
     if front_matter_lang:
@@ -76,12 +81,11 @@ def detect_language(markdown: str, front_matter_lang: str | None) -> str:
         if lang.startswith("en"):
             return "en"
         return "tr"
-    # Heuristic: presence of TR-only characters in headings
-    for line in markdown.splitlines():
-        if line.startswith("#"):
-            if re.search(r"[ğışçöü]", line):
-                return "tr"
-    return "tr"
+    # Heuristic: a Turkish document carries Turkish-only letters somewhere in
+    # its body; a text without a single one is English.
+    if re.search(r"[ğışçöüĞİŞÇÖÜ]", markdown):
+        return "tr"
+    return "en"
 
 
 def apply_punctuation_gate(text: str, language: str) -> tuple[str, list[str]]:
@@ -91,7 +95,9 @@ def apply_punctuation_gate(text: str, language: str) -> tuple[str, list[str]]:
         out = out.replace(src, dst)
 
     warnings: list[str] = []
-    leftover = [ch for ch in mapping.keys() if ch in out]
+    # The residual check must look wider than the mapping: every mapped
+    # character was just replaced, so testing those again can never fire.
+    leftover = sorted(set(FORBIDDEN_PUNCT_RE.findall(out)))
     if leftover:
         warnings.append(
             "punctuation gate: residual forbidden characters: "

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

@@ -33,7 +33,7 @@ set -euo pipefail
 CMD="${1:-}"
 STATE="${2:-}"
 [ -z "$CMD" ] || [ -z "$STATE" ] && {
-  echo "usage: $0 <prepare|commit|push|pr|teardown> <state.json>" >&2
+  echo "usage: $0 <prepare|bridge|commit|push|pr|teardown> <state.json>" >&2
   exit 1
 }
 [ ! -f "$STATE" ] && { echo "ERR: state file not found: $STATE" >&2; exit 2; }
@@ -54,6 +54,8 @@ TASK_ID=$(python3 -c "import json; d=json.load(open('$STATE')); print(d['taskId'
 COMMIT_TYPE=$(python3 -c "import json; d=json.load(open('$STATE')); print(d.get('commitType','feat'))")
 ISSUE_KEY=$(python3 -c "import json; d=json.load(open('$STATE')); print(d['issueRef'].get('key') or '')")
 ISSUE_TITLE=$(python3 -c "import json; d=json.load(open('$STATE')); print(d['issueRef'].get('title') or '')")
+IDENTITY_NAME=$(python3 -c "import json; d=json.load(open('$STATE')); print((d.get('identity') or {}).get('name') or '')")
+IDENTITY_EMAIL=$(python3 -c "import json; d=json.load(open('$STATE')); print((d.get('identity') or {}).get('email') or '')")
 
 cmd_prepare() {
   mkdir -p "$WORKTREE_ROOT"
@@ -90,24 +92,32 @@ cmd_commit() {
   # loop  -  a piped `while` runs in a subshell and the summary exit would
   # always be 0 regardless of per-repo failures.
   local failed=0
+  # state.identity is the commit author/committer, as documented in the schema
+  # above. Git's own config is the fallback when the picker recorded none.
+  local identity_args=()
+  if [ -n "$IDENTITY_NAME" ] && [ -n "$IDENTITY_EMAIL" ]; then
+    identity_args=(-c "user.name=$IDENTITY_NAME" -c "user.email=$IDENTITY_EMAIL")
+  fi
   while IFS=$'\t' read -r name url provider; do
     local target="$WORKTREE_ROOT/$name"
     [ ! -d "$target" ] && continue
     cd "$target"
-    # Use status --porcelain so untracked files count as "changes" too  -
-    # dev sessions usually add brand-new files alongside edits, and `git diff`
-    # alone misses them.
-    if [ -z "$(git status --porcelain 2>/dev/null)" ]; then
-      echo "[$name] no changes, skipping commit"
+    # Only what the dev session staged is committed. A blanket `git add -A`
+    # here swept build output and nested-worktree gitlinks into the commit.
+    if git diff --cached --quiet 2>/dev/null; then
+      if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
+        echo "[$name] nothing staged (unstaged or untracked changes present)  -  stage what belongs in the commit, skipping"
+      else
+        echo "[$name] no changes, skipping commit"
+      fi
       cd - >/dev/null
       continue
     fi
-    git add -A
     local subject="$COMMIT_TYPE($name): $ISSUE_TITLE"
     [ -n "$ISSUE_KEY" ] && subject="$subject [$ISSUE_KEY]"
     # Trim subject to 72 chars
     subject=$(printf '%s' "$subject" | cut -c1-72)
-    if git commit --quiet -m "$subject"; then
+    if git ${identity_args[@]+"${identity_args[@]}"} commit --quiet -m "$subject"; then
       echo "[$name] committed: $subject"
     else
       echo "ERR: [$name] commit failed" >&2

package/pipeline/lib/plan-todos.sh

@@ -155,10 +155,19 @@ do_start() {
   write_state "$state_path" "$new"
 }
 
+require_todo() {
+  # $1 state path, $2 todo_id  -  exits 1 when the id is not in the plan.
+  if ! jq -e --arg id "$2" '(.plan.todos // []) | map(select(.id == $id)) | length > 0' "$1" >/dev/null 2>&1; then
+    echo "plan-todos: todo '$2' not found" >&2
+    exit 1
+  fi
+}
+
 do_complete() {
   local task_id="${1:-}"; local todo_id="${2:-}"; local notes="${3:-}"
   [ -z "$task_id" ] || [ -z "$todo_id" ] && { echo "usage: complete <task-id> <todo-id> [notes]" >&2; exit 64; }
   local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
   local now; now=$(iso_now)
   local new
   new=$(jq --arg id "$todo_id" --arg t "$now" --arg n "$notes" '
@@ -176,6 +185,7 @@ do_fail() {
   local task_id="${1:-}"; local todo_id="${2:-}"; local reason="${3:-}"
   [ -z "$task_id" ] || [ -z "$todo_id" ] || [ -z "$reason" ] && { echo "usage: fail <task-id> <todo-id> <reason>" >&2; exit 64; }
   local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
   local now; now=$(iso_now)
   local new
   new=$(jq --arg id "$todo_id" --arg t "$now" --arg r "$reason" '
@@ -190,6 +200,7 @@ do_skip() {
   local task_id="${1:-}"; local todo_id="${2:-}"; local reason="${3:-}"
   [ -z "$task_id" ] || [ -z "$todo_id" ] || [ -z "$reason" ] && { echo "usage: skip <task-id> <todo-id> <reason>" >&2; exit 64; }
   local state_path; state_path=$(resolve_state "$task_id")
+  require_todo "$state_path" "$todo_id"
   local now; now=$(iso_now)
   local new
   new=$(jq --arg id "$todo_id" --arg t "$now" --arg r "$reason" '

package/pipeline/lib/post-pr-review.sh

@@ -408,9 +408,16 @@ post_bitbucket_server() {
     needs_work) status_payload='{"status":"NEEDS_WORK"}' ;;
   esac
 
-  curl -sS -m 30 -K <(bb_auth_cfg "$auth_user" "$auth_token") -X PUT \
+  local http
+  http=$(curl -sS -m 30 -K <(bb_auth_cfg "$auth_user" "$auth_token") -X PUT \
     -H "Content-Type: application/json" "$base/participants/$user_slug" \
-    -d "$status_payload" >/dev/null
+    -d "$status_payload" -o /dev/null -w '%{http_code}' || echo 000)
+  case "$http" in
+    200|201) ;;
+    *)
+      echo "post-pr-review: bitbucket verdict PUT failed (HTTP $http) for PR #$PR_NUM  -  $DECISION was NOT recorded" >&2
+      return 4 ;;
+  esac
 }
 
 # --- Main switch ------------------------------------------------------------

package/pipeline/lib/repo-cache.sh

@@ -18,12 +18,13 @@
 #   ./repo-cache.sh bitbucket <workspace> [--refresh]
 #
 # Required env per-provider:
-#   github    -> GH_TOKEN_KEY (keychain service)
+#   github    -> (none)  -  uses the gh CLI's own auth; GH_USER selects the account
 #   bitbucket -> BB_TOKEN_KEY, BB_USER_KEY, BB_HOST (e.g. bitbucket.example.com)
 #   local     -> (none)  -  scopes are treated as filesystem roots; "scope=$HOME"
 #                walks $HOME with maxdepth, scope=<path> walks just that path.
-#                LOCAL_SCAN_ROOTS env can override the default root list.
-#                LOCAL_SCAN_MAXDEPTH env (default 4) bounds traversal cost.
+#                LOCAL_SCAN_ROOTS env (colon-separated, like PATH) overrides the
+#                default root list. LOCAL_SCAN_MAXDEPTH env (default 4) bounds
+#                traversal cost.
 
 set -euo pipefail
 
@@ -211,16 +212,23 @@ print(json.dumps(out))
   local)
     # Scan filesystem roots for git repos. Default roots cover the common
     # places personal/work checkouts live; override via LOCAL_SCAN_ROOTS.
-    DEFAULT_ROOTS="$HOME $HOME/Documents $HOME/Developer $HOME/projects $HOME/code $HOME/work"
-    ROOTS="${LOCAL_SCAN_ROOTS:-$DEFAULT_ROOTS}"
-    MAXDEPTH="${LOCAL_SCAN_MAXDEPTH:-4}"
-    # When SCOPE is an absolute path use it directly; otherwise treat SCOPE
-    # as a label and walk the configured roots.
+    # Roots are held in an array, never a whitespace-split string: a HOME with
+    # a space in it split into two nonexistent roots and the scan found nothing.
+    ROOTS=()
     if [ -d "$SCOPE" ]; then
-      ROOTS="$SCOPE"
+      ROOTS=("$SCOPE")
+    elif [ -n "${LOCAL_SCAN_ROOTS:-}" ]; then
+      while IFS= read -r root; do
+        [ -n "$root" ] && ROOTS+=("$root")
+      done <<EOF_ROOTS
+$(printf '%s\n' "$LOCAL_SCAN_ROOTS" | tr ':' '\n')
+EOF_ROOTS
+    else
+      ROOTS=("$HOME" "$HOME/Documents" "$HOME/Developer" "$HOME/projects" "$HOME/code" "$HOME/work")
     fi
+    MAXDEPTH="${LOCAL_SCAN_MAXDEPTH:-4}"
     : > "$CACHE_TMP.list"
-    for root in $ROOTS; do
+    for root in ${ROOTS[@]+"${ROOTS[@]}"}; do
       [ -d "$root" ] || continue
       # -prune avoids descending into already-found .git trees (nested submodules
       # show up via submodule-detector, not the top-level picker).

package/pipeline/lib/review-watch.sh

@@ -10,11 +10,16 @@
 #   - Reads watched repos from prefs.global.reviewWatch.repos[] (or --repos).
 #   - For each repo, lists open PRs since the last seen cursor (state in
 #     ~/.claude/state/review-watch/<owner-repo>.json).
-#   - For each PR not yet reviewed (or updated since last review), invokes
-#     `bash $HOME/.claude/lib/post-pr-review.sh <task-id>` after writing the
-#     PR input to agent-state.json. The reviewer dispatch itself is the
-#     responsibility of /multi-agent:review's LLM loop; review-watch is just
-#     the trigger.
+#   - For each PR not yet reviewed (or updated since last review), writes the
+#     PR input to a per-PR agent-state.json (see Storage) and prints the
+#     dispatch line. The review itself is /multi-agent:review's LLM loop,
+#     which fills `.review.findings` for that task id; review-watch never
+#     spends tokens.
+#   - On a later scan, a PR whose agent-state carries findings for the
+#     current head SHA is posted through post-pr-review.sh, and only a
+#     successful post stamps reviewed_prs[<n>] = <sha>. A PR is never marked
+#     reviewed without a review having been posted.
+#     REVIEW_WATCH_DRY_RUN=1 reports what would be posted and stamps nothing.
 #   - Honors labelFilter (only review PRs carrying the label, default: all).
 #   - Skips PRs the user authored (we don't review our own PRs through this
 #     surface  -  that's what the in-pipeline Phase 4 / standalone /review is
@@ -36,13 +41,26 @@
 #   ~/.claude/state/review-watch/<owner__repo>.json
 #     { last_seen_iso: "2026-05-11T12:34:56Z",
 #       reviewed_prs: { "1234": "head-sha-abc" } }
+#   ~/.claude/logs/multi-agent/review-watch/<owner__repo>-pr<n>/agent-state.json
+#     { taskId, review: { input: {...}, headCommitSha, findings? } }
+#     (task id <owner__repo>-pr<n>; post-pr-review.sh reads it by that id)
 
 set -euo pipefail
 
 PREFS="$HOME/.claude/multi-agent-preferences.json"
 STATE_DIR="$HOME/.claude/state/review-watch"
+REVIEW_LOGS="$HOME/.claude/logs/multi-agent/review-watch"
 mkdir -p "$STATE_DIR"
 
+POSTER=""
+for _cand in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/post-pr-review.sh" \
+             "$HOME/.claude/lib/post-pr-review.sh" \
+             "$HOME/.copilot/lib/post-pr-review.sh" \
+             "$HOME/.codex/lib/post-pr-review.sh"; do
+  [ -f "$_cand" ] && { POSTER="$_cand"; break; }
+done
+unset _cand
+
 CMD="${1:-}"
 shift || true
 
@@ -192,16 +210,44 @@ review_one_repo() {
       continue
     fi
 
+    local task_id state_file
+    task_id="${repo//\//__}-pr${pr_num}"
+    state_file="$REVIEW_LOGS/$task_id/agent-state.json"
+
+    # Findings already written for THIS head by /multi-agent:review: post them.
+    # The stamp below is the only place reviewed_prs is written, and it is
+    # written only after post-pr-review.sh returned 0.
+    if [ -f "$state_file" ] \
+       && [ "$(jq -r '.review.headCommitSha // ""' "$state_file" 2>/dev/null)" = "$head_sha" ] \
+       && jq -e '.review.findings | type == "array"' "$state_file" >/dev/null 2>&1; then
+      if [ "${REVIEW_WATCH_DRY_RUN:-0}" = "1" ]; then
+        printf '  dry-run: would post the review for PR #%s (task %s) via post-pr-review.sh\n' "$pr_num" "$task_id"
+      elif [ -z "$POSTER" ]; then
+        err "post-pr-review.sh not found  -  PR #$pr_num stays pending"
+      elif bash "$POSTER" "$task_id"; then
+        printf '  posted review for PR #%s at %s\n' "$pr_num" "$head_sha"
+        state=$(jq --arg n "$pr_num" --arg s "$head_sha" \
+          '.reviewed_prs[$n] = $s' <<<"$state")
+      else
+        err "post-pr-review.sh failed for $repo PR #$pr_num  -  stays pending, not stamped"
+      fi
+      continue
+    fi
+
+    # No review for this head yet: write the input /multi-agent:review reads
+    # and hand off. review-watch does not run the LLM itself, because token
+    # cost decisions stay with the user; the PR stays un-stamped until a
+    # review is actually posted.
     printf '  dispatch review: %s PR #%s  -  %s\n' "$repo" "$pr_num" "$title"
-    printf '    url=%s head=%s\n' "$url" "$head_sha"
-
-    # Record that we reviewed this head SHA. The actual dispatch happens
-    # via /multi-agent:review on the surface that invoked review-watch
-    # (Claude Code session or future webhook handler). review-watch only
-    # produces the dispatch list  -  it does not run the LLM itself, because
-    # token cost decisions stay with the user.
-    state=$(jq --arg n "$pr_num" --arg s "$head_sha" \
-      '.reviewed_prs[$n] = $s' <<<"$state")
+    printf '    url=%s head=%s task=%s\n' "$url" "$head_sha" "$task_id"
+    mkdir -p "$(dirname "$state_file")"
+    jq -n --arg repo "$repo" --arg n "$pr_num" --arg sha "$head_sha" \
+          --arg url "$url" --arg title "$title" --arg t "$task_id" '
+      { schemaVersion: "2.1.0", taskId: $t,
+        review: { input: { kind: "pr", provider: "github", host: "github.com",
+                           orgRepo: $repo, prNumber: ($n | tonumber),
+                           url: $url, title: $title },
+                  headCommitSha: $sha, iterationNumber: 1 } }' > "$state_file"
   done < <(jq -c '.[]' <<<"$prs_json")
 
   # Persist the NEWEST updatedAt seen this scan  -  the previous per-PR

package/pipeline/lib/shadow-git.sh

@@ -163,10 +163,12 @@ do_list() {
   require_task_id "$task_id"
   local sd; sd=$(shadow_dir "$task_id")
   [ ! -d "$sd/.git" ] && { err "shadow not initialized for $task_id"; exit 1; }
-  # Use the embedded `iso:` line from the commit message body so the listing
+  # Use the embedded `iso:` trailer from the commit message body so the listing
   # carries the snapshot timestamp without relying on committer date (which is
-  # influenced by git env vars).
-  sg "$sd" "$(pwd)" log --pretty=format:'%h  %s' --no-decorate
+  # influenced by git env vars); committer date is the fallback for a snapshot
+  # written without one.
+  sg "$sd" "$(pwd)" log --pretty=format:'%h%x1f%(trailers:key=iso,valueonly,separator=%x20)%x1f%cI%x1f%s' --no-decorate \
+    | awk -F'\037' '{ d = $2; sub(/ .*/, "", d); if (d == "") d = $3; printf "%s  %s  %s\n", $1, d, $4 }'
 }
 
 do_restore() {
@@ -213,7 +215,9 @@ do_prune() {
   local older=""
   while [ "$#" -gt 0 ]; do
     case "$1" in
-      --older-than-days) older="$2"; shift 2 ;;
+      --older-than-days)
+        [ "$#" -ge 2 ] || { err "--older-than-days needs a value"; exit 2; }
+        older="$2"; shift 2 ;;
       *) err "unknown flag: $1"; exit 2 ;;
     esac
   done

package/pipeline/lib/vercel-deploy.sh

@@ -153,10 +153,10 @@ cmd_deploy() {
   if [ "$prod" = true ]; then
     cmd_args+=(--prod)
   fi
-  cmd_args+=("${extra_args[@]}")
+  cmd_args+=(${extra_args[@]+"${extra_args[@]}"})
 
   # Refuse to run if the user is trying to pass --token=... via extra args.
-  for a in "${extra_args[@]}"; do
+  for a in ${extra_args[@]+"${extra_args[@]}"}; do
     case "$a" in
       --token=*|--token)
         echo "ERROR: refused to deploy with --token argv. Pass the token via VERCEL_TOKEN env var instead." >&2

package/pipeline/multi-agent-refs/_dev-context.md

@@ -53,8 +53,11 @@ Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typica
    entry, plus any selected `extras[]` that is not being given a worktree. The
    phases that consume them run hours later and have no access to the picker's
    return value, so a result that is not written here is a result nothing can
-   read - Phase 4's platform-parity cross-check reads `state.siblings[]` and
-   nothing else.
+   read. Phase 4's platform-parity cross-check reads `state.siblings[]` as the
+   fourth of its four counterpart sources, after `--with`,
+   `prefs.projects[<slug>].counterpartRoots[]` and the primary checkout's sibling
+   directories (`platform-parity.md`), so a submodule or a hand-picked repo that
+   is not written here is a candidate the check can never see.
 
    Resolve each entry's `stack` from its local checkout, with the marker table
    in `phases/phase-1-analysis.md` Step 2 (`.xcodeproj` / `Package.swift` →

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

@@ -1,14 +1,14 @@
-# Locked decisions (35)
+# Locked decisions (36)
 
-> The 35 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
+> The 36 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
 
 ### Index by category (v9.1.0+)
 
-Browse-friendly grouping of the 35 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
+Browse-friendly grouping of the 36 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
 
 | Category | Decisions | Concern |
 |---|---|---|
-| **A. Governance** | 1, 5, 6, 7, 10, 26, 27, 32 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache, analysis profile |
+| **A. Governance** | 1, 5, 6, 7, 10, 26, 27, 32, 36 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache, analysis profile, document reviewed before publish |
 | **B. Citation and Evidence** | 3, 4, 8, 11, 24, 30, 34 | Every fact in the doc traces back to a source: citation discipline, forward-looking spec, standards binding, repo-evidence reuse-first, Pass B footnote mandatory, analysis self-contained (pipeline-wide), references built from the evidence record |
 | **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 25, 33, 35 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, Lite mode, corporate backbone always renders, stack-optional render |
 | **D. Design Source and Pipeline Architecture** | 12, 22, 23 | Where design comes from and how the pipeline renders: Figma 3-tier access (BLOCKING), platform-agnostic template + Pass B render, convention extraction (Phase 1c) |

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

@@ -12,7 +12,7 @@
 
    **When `platforms[]` is empty** (Locked 35), the channels come from the evidence instead of from repo stack tags, so this loop runs once per derived channel (`mobile`, `web`, or one channel-agnostic pass). What drops is the development layer (corporate Part C, global Sections 13, 14, 15) and the Pass B projection are skipped, Section 20 carries a row recording that they await a repo selection, and the front-matter `platform` key reads `none`. Everything that does not need a target repository still renders in full.
 
-3. **Humanizer pass (MANDATORY: actually invoke the `ai-common-toolkit:humanizer` skill on the rendered markdown - the punctuation grep alone does NOT satisfy this step)** (`technical-explanatory` tone for the scratch buffer; per-channel re-humanize happens in Phase 4 when actually emitting):
+3. **Humanizer pass (required: actually invoke the `ai-common-toolkit:humanizer` skill on the rendered markdown - the punctuation grep alone does NOT satisfy this step)** (`technical-explanatory` tone for the scratch buffer; per-channel re-humanize happens in Phase 4 when actually emitting):
    ```
    ai-common-toolkit:humanizer skill input:
      language: <tr|en>

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

@@ -207,7 +207,7 @@ Future changes that break an item in the "stay identical" list must update **bot
 
 Each file has a different frontmatter schema. The sync flow transforms between them:
 
-### 3.1 Claude Code  -  `commands/multi-agent/{cmd}.md`
+### 3.1 Claude Code  -  `commands/multi-agent/{cmd}/SKILL.md`
 
 ```yaml
 ---

package/pipeline/multi-agent-refs/outside-the-pipeline.md

@@ -75,13 +75,13 @@ toolkit. Continue without one rather than guessing which might fit.
 
 ## multi-agent-toolkit MCP
 
-| Family | Reach for it when |
+| Tool | Reach for it when |
 |---|---|
-| `ui-inspect` | you need to know what is actually on screen, not what the code implies |
-| `crash-logs` | a crash happened on a device or simulator |
-| `design-check` | a built screen has to be compared against its design |
-| `ios-app-store-audit` | a package is heading for review |
-| `ios-testflight` | validating a build before upload |
+| `ios_get_ui_tree` / `android_get_ui_tree` | you need to know what is actually on screen, not what the code implies |
+| `ios_list_crashes` / `android_list_crashes` | a crash happened on a device or simulator |
+| `design_*` (`design_visual_compare`, `design_ui_geometry`, `design_report`, ...) | a built screen has to be compared against its design |
+| `ios_app_store_audit` | a package is heading for review |
+| `ios_testflight_validate` | validating a build before upload |
 
 Registered at user scope by the installer, and preserved by uninstall - the tools are
 useful with no pipeline at all. If it is not registered the tools simply are not

package/pipeline/multi-agent-refs/phases/log-format.md

@@ -55,7 +55,7 @@ Phase 7: Report █░░░░░░░░░░░░░░░ 2s
 (emit from the last iteration's `triage.consensus` block, schema v3.1.0. One line stating `verdict` + `reviewerCount`; when `verdict` is `split` or `unverified`, list each `disagreements[]` entry so a human can confirm what the reviewers did not independently agree on. Omit the section when triage produced no consensus block.)
 
 ```
-Verdict: unverified (2 reviewers)
+Verdict: unverified (3 reviewers)
 - Auth/KeychainStore.swift:40  -  token persisted without access-control flag
   (both approved a keychain change  -  agreement unverified, confirm manually)
 ```