@mmerterden/multi-agent-pipeline 11.3.2 → 11.5.0

package/pipeline/lib/plan-todos.sh

@@ -61,7 +61,10 @@ resolve_state() {
 
 write_state() {
   local path="$1" content="$2"
-  local tmp; tmp=$(mktemp)
+  # mktemp NEXT TO the target: a $TMPDIR temp file can live on a different
+  # filesystem than $HOME, where mv degrades to copy+unlink and loses the
+  # atomic-rename guarantee.
+  local tmp; tmp=$(mktemp "${path}.XXXXXX")
   printf '%s\n' "$content" > "$tmp"
   mv "$tmp" "$path"
 }
@@ -93,6 +96,12 @@ do_set() {
     echo "plan-todos: input must be an object with .title (string) and .todos (array)" >&2
     exit 2
   fi
+  # Per-item validation: every todo needs a string .id and .task, otherwise
+  # downstream jq like `.id + "\t" + .task` crashes on (null + string).
+  if ! jq -e '.todos | all(type == "object" and (.id | type == "string") and (.task | type == "string"))' <<<"$plan_blob" >/dev/null 2>&1; then
+    echo "plan-todos: every todo must be an object with string .id and .task fields" >&2
+    exit 2
+  fi
   local state_path; state_path=$(resolve_state "$task_id")
   local now; now=$(iso_now)
   local new
@@ -209,7 +218,7 @@ do_next() {
           )
       )
     | (.[0] // empty)
-    | if . == null or . == "" then "" else .id + "\t" + .task end
+    | if . == null or . == "" then "" else (.id // "") + "\t" + (.task // "") end
   ' "$state_path"
 }
 
@@ -229,7 +238,7 @@ do_list() {
           skipped:    "- [/]",
           failed:     "- [!]"
         } as $marks
-        | ($marks[.status] // "- [ ]") + " **" + .id + "** " + .task
+        | ($marks[.status] // "- [ ]") + " **" + (.id // "") + "** " + (.task // "")
           + (if (.notes // "") != "" then "  _(" + .notes + ")_" else "" end)
           + (if (.failureReason // "") != "" then "  _**failed:** " + .failureReason + "_" else "" end)
           + (if (.skipReason    // "") != "" then "  _**skipped:** "    + .skipReason    + "_" else "" end))

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

@@ -75,9 +75,11 @@ ITERATION=$(jq -r '.review.iterationNumber // 1' "$AGENT_STATE")
 # --- Decision ---------------------------------------------------------------
 
 # Single jq pass  -  group accepted findings by severity into tab-separated counts.
+# `.review.findings // []` so a null/absent findings array (clean review)
+# cannot raise "Cannot iterate over null" under set -e.
 read -r ACCEPTED_BLOCKING ACCEPTED_IMPORTANT < <(
   jq -r '
-    [.review.findings[] | select(.status == "accepted")] as $a
+    [(.review.findings // [])[] | select(.status == "accepted")] as $a
     | [($a | map(select(.severity == "blocking")) | length),
        ($a | map(select(.severity == "important")) | length)]
     | @tsv
@@ -242,7 +244,7 @@ post_github() {
   fi
 
   if [ "$DECISION" = "needs_work" ]; then
-    jq -c '.review.findings[] | select(.status == "accepted" and (.severity == "blocking" or .severity == "important"))' "$AGENT_STATE" \
+    jq -c '(.review.findings // [])[] | select(.status == "accepted" and (.severity == "blocking" or .severity == "important"))' "$AGENT_STATE" \
     | while read -r finding; do
         local sev path line issue_b64 fix_b64 rule_id_b64 issue fix rule_id body fingerprint
         IFS=$'\t' read -r sev path line issue_b64 fix_b64 rule_id_b64 < <(
@@ -333,7 +335,7 @@ post_bitbucket_server() {
   fi
 
   if [ "$DECISION" = "needs_work" ]; then
-    jq -c '.review.findings[] | select(.status == "accepted" and (.severity == "blocking" or .severity == "important"))' "$AGENT_STATE" \
+    jq -c '(.review.findings // [])[] | select(.status == "accepted" and (.severity == "blocking" or .severity == "important"))' "$AGENT_STATE" \
     | while read -r finding; do
         local sev path line issue_b64 fix_b64 rule_id_b64 issue fix rule_id body payload http fingerprint
         IFS=$'\t' read -r sev path line issue_b64 fix_b64 rule_id_b64 < <(

package/pipeline/lib/repo-cache.sh

@@ -59,6 +59,36 @@ if [ $REFRESH -eq 0 ] && cache_fresh; then
   exit 0
 fi
 
+# Refresh staging: providers write to $CACHE_TMP, then commit_cache validates
+# and mv's it into place. Writing straight to $CACHE_FILE truncated the cache
+# BEFORE the fetch ran, so any failure left an empty file that cache_fresh
+# then served for the whole TTL.
+CACHE_TMP="${CACHE_FILE}.tmp.$$"
+cleanup_tmp() { rm -f "$CACHE_TMP" "$CACHE_TMP.list" 2>/dev/null || true; }
+trap cleanup_tmp EXIT
+
+# Validate the staged file (non-empty valid JSON) and move it into place.
+# On failure keep the previous cache and serve it with a warning; hard-fail
+# only when there is no previous cache to fall back to.
+commit_cache() {
+  if [ -s "$CACHE_TMP" ] \
+    && python3 -c 'import json,sys; json.load(open(sys.argv[1]))' "$CACHE_TMP" 2>/dev/null; then
+    mv "$CACHE_TMP" "$CACHE_FILE"
+    return 0
+  fi
+  rm -f "$CACHE_TMP"
+  if [ -f "$CACHE_FILE" ]; then
+    echo "WARN: repo-cache refresh failed for $PROVIDER/$SCOPE; serving previous cache" >&2
+    return 0
+  fi
+  echo "ERR: repo-cache refresh failed for $PROVIDER/$SCOPE and no previous cache exists" >&2
+  exit 3
+}
+
+# Basic-auth via a curl config fed through process substitution so the
+# credential never appears in argv (argv is visible to `ps`).
+bb_auth_cfg() { printf 'user = "%s:%s"\n' "$1" "$2"; }
+
 case "$PROVIDER" in
   github)
     if ! command -v gh >/dev/null 2>&1; then
@@ -100,20 +130,32 @@ for r in data:
       "provider": "github"
     })
 print(json.dumps(out))
-' > "$CACHE_FILE"
+' > "$CACHE_TMP" || true
+    commit_cache
     ;;
 
   bitbucket)
     : "${BB_TOKEN_KEY:?BB_TOKEN_KEY required for bitbucket}"
     : "${BB_HOST:?BB_HOST required (e.g. bitbucket.example.com)}"
-    BB_USER="${BB_USER:-${BB_USER_KEY:+$("$HOME/.claude/lib/credential-store.sh" get "$BB_USER_KEY" 2>/dev/null || true)}}"
-    BB_TOKEN=$("$HOME/.claude/lib/credential-store.sh" get "$BB_TOKEN_KEY" 2>/dev/null || true)
+    # Resolve the credential helper via the shared resolver (works from the
+    # repo checkout and from both install trees)  -  never hardcode the path.
+    # A pre-set CRED_STORE (tests, custom installs) is honored as-is.
+    if [ -z "${CRED_STORE:-}" ]; then
+      # shellcheck disable=SC1090,SC1091
+      . "$(cd "$(dirname "$0")" && pwd)/credential-store-resolver.sh" 2>/dev/null \
+        || . "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
+        || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
+        || { echo "ERR: credential helper not found" >&2; exit 3; }
+    fi
+    BB_USER="${BB_USER:-${BB_USER_KEY:+$("$CRED_STORE" get "$BB_USER_KEY" 2>/dev/null || true)}}"
+    BB_TOKEN=$("$CRED_STORE" get "$BB_TOKEN_KEY" 2>/dev/null || true)
     if [ -z "$BB_TOKEN" ]; then
       echo "ERR: bitbucket token not found in credential store ($BB_TOKEN_KEY)" >&2
       exit 3
     fi
     # Bitbucket Server REST: /rest/api/1.0/projects/{key}/repos?limit=200
-    curl -sf -u "${BB_USER:-bot}:${BB_TOKEN}" \
+    # Auth via curl config file (-K) so the token never appears on argv.
+    curl -sf -K <(bb_auth_cfg "${BB_USER:-bot}" "$BB_TOKEN") \
       "https://${BB_HOST}/rest/api/1.0/projects/${SCOPE}/repos?limit=200" \
       | python3 -c '
 import json,sys
@@ -147,7 +189,8 @@ for r in vals:
       "provider": "bitbucket"
     })
 print(json.dumps(out))
-' > "$CACHE_FILE"
+' > "$CACHE_TMP" || true
+    commit_cache
     ;;
 
   local)
@@ -161,7 +204,7 @@ print(json.dumps(out))
     if [ -d "$SCOPE" ]; then
       ROOTS="$SCOPE"
     fi
-    : > "$CACHE_FILE.tmp"
+    : > "$CACHE_TMP.list"
     for root in $ROOTS; do
       [ -d "$root" ] || continue
       # -prune avoids descending into already-found .git trees (nested submodules
@@ -178,7 +221,7 @@ print(json.dumps(out))
             # truly offline-only or a clone with an upstream we just chose
             # to treat as local.
             remote=$(git -C "$repo_dir" remote get-url origin 2>/dev/null || true)
-            printf '%s\t%s\t%s\n' "$name" "$repo_dir" "$remote" >> "$CACHE_FILE.tmp"
+            printf '%s\t%s\t%s\n' "$name" "$repo_dir" "$remote" >> "$CACHE_TMP.list"
           done
     done
     python3 -c '
@@ -218,8 +261,9 @@ for raw in open(sys.argv[1]):
         "provider": "local"
     })
 print(json.dumps(out))
-' "$CACHE_FILE.tmp" > "$CACHE_FILE"
-    rm -f "$CACHE_FILE.tmp"
+' "$CACHE_TMP.list" > "$CACHE_TMP" || true
+    rm -f "$CACHE_TMP.list"
+    commit_cache
     ;;
 
   *)

package/pipeline/lib/review-watch.sh

@@ -180,6 +180,10 @@ review_one_repo() {
     title=$(jq -r '.title' <<<"$pr")
     url=$(jq -r '.url' <<<"$pr")
 
+    # Advance the cursor candidate for every PR seen (including skips), so a
+    # PR that keeps its reviewed head SHA is not re-fetched on every poll.
+    if [ "$updated_at" \> "$newest_iso" ]; then newest_iso="$updated_at"; fi
+
     # Did we already review THIS head SHA?
     local prev_sha
     prev_sha=$(jq -r --arg n "$pr_num" '.reviewed_prs[$n] // empty' <<<"$state")
@@ -196,12 +200,18 @@ review_one_repo() {
     # (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" --arg t "$updated_at" \
-      '.reviewed_prs[$n] = $s | .last_seen_iso = $t' <<<"$state")
-
-    if [ "$updated_at" \> "$newest_iso" ]; then newest_iso="$updated_at"; fi
+    state=$(jq --arg n "$pr_num" --arg s "$head_sha" \
+      '.reviewed_prs[$n] = $s' <<<"$state")
   done < <(jq -c '.[]' <<<"$prs_json")
 
+  # Persist the NEWEST updatedAt seen this scan  -  the previous per-PR
+  # assignment stamped whichever PR the search returned last, which moves
+  # the cursor backwards whenever results are not oldest-first and causes
+  # permanent re-scans. newest_iso only ever grows (seeded from last_seen).
+  if [ -n "$newest_iso" ] && [ "$newest_iso" != "$last_seen" ]; then
+    state=$(jq --arg t "$newest_iso" '.last_seen_iso = $t' <<<"$state")
+  fi
+
   save_state "$repo" "$state"
 }
 
@@ -218,7 +228,13 @@ case "$CMD" in
       while IFS= read -r r; do [ -n "$r" ] && REPOS+=("$r"); done < <(read_repos_from_prefs)
     fi
     [ "${#REPOS[@]}" -eq 0 ] && { err "no repos configured (prefs.reviewWatch.repos)"; exit 2; }
-    for r in "${REPOS[@]}"; do review_one_repo "$r"; done
+    # Per-repo failures (transient gh/network errors) must not kill the run
+    # under set -e; log, continue, and reflect them in the exit code.
+    RC=0
+    for r in "${REPOS[@]}"; do
+      review_one_repo "$r" || { err "scan failed for $r (continuing)"; RC=3; }
+    done
+    exit "$RC"
     ;;
   --watch)
     require_jq
@@ -227,7 +243,11 @@ case "$CMD" in
     [ "$interval" -lt 30 ] && interval=30   # GitHub rate limit guard
     printf 'review-watch: starting loop (interval=%ds)\n' "$interval"
     while :; do
-      while IFS= read -r r; do [ -n "$r" ] && review_one_repo "$r"; done < <(read_repos_from_prefs)
+      # A transient failure on one repo must not kill the watch loop.
+      while IFS= read -r r; do
+        [ -n "$r" ] || continue
+        review_one_repo "$r" || err "scan failed for $r (continuing)"
+      done < <(read_repos_from_prefs)
       sleep "$interval"
     done
     ;;

package/pipeline/lib/shadow-git.sh

@@ -61,6 +61,23 @@ usage() {
 
 shadow_dir() { printf '%s/%s' "$SHADOW_ROOT" "$1"; }
 
+# Task ids become path components under $SHADOW_ROOT, so an unvalidated id
+# like ".." would make prune's `rm -rf` walk out of the shadow tree and
+# delete ~/.claude/state. Allow only [A-Za-z0-9._-]+ and explicitly reject
+# ".", "..", empty, and anything containing a slash.
+require_task_id() {
+  case "${1:-}" in
+    "" | . | ..)
+      err "invalid task id: '${1:-}' (empty, '.' and '..' are rejected)"
+      exit 2
+      ;;
+    *[!A-Za-z0-9._-]*)
+      err "invalid task id: '$1' (allowed characters: A-Z a-z 0-9 . _ -)"
+      exit 2
+      ;;
+  esac
+}
+
 # Wrap git so .git lives in $SHADOW_DIR but worktree is the project root.
 sg() {
   local sd="$1" wt="$2"; shift 2
@@ -74,6 +91,7 @@ iso_now() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
 do_init() {
   local task_id="${1:-}" project_root="${2:-}"
   [ -z "$task_id" ] || [ -z "$project_root" ] && { err "usage: init <task-id> <project-root>"; exit 1; }
+  require_task_id "$task_id"
   [ ! -d "$project_root" ] && { err "project root not a directory: $project_root"; exit 1; }
   local sd; sd=$(shadow_dir "$task_id")
   if [ -d "$sd/.git" ]; then
@@ -83,12 +101,16 @@ do_init() {
   mkdir -p "$sd"
   # Bare-ish: .git inside $sd, worktree is the project root.
   git init --quiet "$sd" >/dev/null
-  # Mirror the project's .gitignore so we don't snapshot node_modules / Pods.
+  # Ignore rules must live in $GIT_DIR/info/exclude: the work tree is the
+  # project root, so a .gitignore placed next to the shadow .git is never
+  # read by git. Seed the exclude file with the project's own .gitignore
+  # (protects snapshots even if the project file is deleted mid-run) plus
+  # forced excludes for build artifacts the project may not ignore.
+  mkdir -p "$sd/.git/info"
   if [ -f "$project_root/.gitignore" ]; then
-    cp "$project_root/.gitignore" "$sd/.gitignore"
+    cat "$project_root/.gitignore" >> "$sd/.git/info/exclude"
   fi
-  # Also exclude these from snapshots even if .gitignore omits them.
-  cat >> "$sd/.gitignore" <<EOF
+  cat >> "$sd/.git/info/exclude" <<EOF
 node_modules/
 Pods/
 .build/
@@ -111,6 +133,7 @@ do_snapshot() {
   local task_id="${1:-}" project_root="${2:-}" label="${3:-}"
   [ -z "$task_id" ] || [ -z "$project_root" ] || [ -z "$label" ] && {
     err "usage: snapshot <task-id> <project-root> <label>"; exit 1; }
+  require_task_id "$task_id"
   local sd; sd=$(shadow_dir "$task_id")
   [ ! -d "$sd/.git" ] && { err "shadow not initialized for $task_id  -  run 'init' first"; exit 1; }
   sg "$sd" "$project_root" add -A >/dev/null 2>&1 || true
@@ -129,6 +152,7 @@ do_snapshot() {
 do_list() {
   local task_id="${1:-}"
   [ -z "$task_id" ] && { err "usage: list <task-id>"; exit 1; }
+  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
@@ -141,12 +165,28 @@ do_restore() {
   local task_id="${1:-}" project_root="${2:-}" sha="${3:-}" mode="${4:---files}"
   [ -z "$task_id" ] || [ -z "$project_root" ] || [ -z "$sha" ] && {
     err "usage: restore <task-id> <project-root> <sha> [--files|--state|--both]"; exit 1; }
+  require_task_id "$task_id"
   local sd; sd=$(shadow_dir "$task_id")
   [ ! -d "$sd/.git" ] && { err "shadow not initialized for $task_id"; exit 1; }
   case "$mode" in
     --files|--both)
       sg "$sd" "$project_root" checkout --quiet "$sha" -- . \
         || { err "git checkout failed"; exit 3; }
+      # `checkout <sha> -- .` restores tracked content but leaves files that
+      # did not exist in the snapshot. Remove both classes of leftovers so a
+      # restore is a full rollback, staying strictly inside the work tree:
+      #   a) files committed in snapshots AFTER $sha (added between sha..HEAD)
+      #   b) files created since the last snapshot (still untracked; `clean`
+      #      respects the info/exclude rules, so ignored trees are untouched)
+      local extra
+      extra=$(sg "$sd" "$project_root" diff --name-only --diff-filter=A "$sha" HEAD 2>/dev/null || true)
+      if [ -n "$extra" ]; then
+        printf '%s\n' "$extra" | while IFS= read -r f; do
+          [ -n "$f" ] && rm -f "$project_root/$f"
+        done
+      fi
+      ( cd "$project_root" && \
+        git --git-dir="$sd/.git" --work-tree="$project_root" clean -fdq ) || true
       printf 'shadow-git: restored files to %s\n' "$sha" >&2
       ;;
     --state)
@@ -161,6 +201,7 @@ do_restore() {
 do_prune() {
   local task_id="${1:-}"; shift || true
   [ -z "$task_id" ] && { err "usage: prune <task-id> [--older-than-days N]"; exit 1; }
+  require_task_id "$task_id"
   local older=""
   while [ "$#" -gt 0 ]; do
     case "$1" in

package/pipeline/lib/vercel-deploy.sh

@@ -110,7 +110,16 @@ cmd_deploy() {
   fi
 
   if [ -z "${VERCEL_TOKEN:-}" ]; then
-    echo "ERROR: VERCEL_TOKEN not set. Resolve via env or keychain ('~/.claude/lib/credential-store.sh get <vercel-key>')." >&2
+    # Route the credential-helper hint through the resolver instead of a
+    # hardcoded ~/.claude path so Copilot-only installs get a usable command.
+    # The resolver ships alongside this wrapper in lib/; fall back to the
+    # per-CLI install locations when running from a different cwd layout.
+    # shellcheck source=/dev/null
+    . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/credential-store-resolver.sh" 2>/dev/null \
+      || . "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
+      || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
+      || true
+    echo "ERROR: VERCEL_TOKEN not set. Resolve via env or keychain ('${CRED_STORE:-credential-store.sh} get <vercel-key>')." >&2
     echo "Hint: vercel CLI accepts the token via env var; do NOT pass --token= on argv (leaks on retry)." >&2
     exit 1
   fi

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

@@ -6,13 +6,13 @@
 
 ---
 
-## 1. Command Inventory (36 commands)
+## 1. Command Inventory (38 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, delete, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
 help, issue, jira, kill, language, local,
-local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review,
+local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
 scan, search, setup, stack, status, sync, test, update
 ```
 
@@ -23,7 +23,7 @@ Categories:
 - **Full 8-phase modes**: `autopilot`, `local`, `local-autopilot`
 - **Fast modes** (Init -> Dev(Opus) -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
-- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `delete`, `resume`, `review`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
+- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `delete`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 
 > **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list  -  bump the count + table together.
@@ -245,7 +245,7 @@ For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; th
 
 This contract is validated by:
 
-- `smoke-cross-cli-behavior.sh`  -  asserts all 36 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
+- `smoke-cross-cli-behavior.sh`  -  asserts all 38 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
 - `smoke-commands-skills-parity.sh` (50 assertions)  -  enforces colon-form command ↔ dash-form skill directory parity
 - `smoke-compliance-skills.sh` (45 assertions)  -  enforces store-compliance skill catalog + 4 consumer wiring
 - `smoke-personal-data.sh`  -  extended in 0.5.5 to treat deprecated placeholders (`{github-username}`, `{your-website}`, `{website-repo}`) as leaks; adds `mmerterden` to public-handle blocklist for generic docs

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

@@ -0,0 +1,65 @@
+# Readiness Review (shared flow for review-jira + review-issue)
+
+Assess whether a tracker item (Jira issue or GitHub issue) is READY to hand to the multi-agent pipeline, list the concrete gaps, and - after confirmation - post them back as a comment on the item so the reporter can fix it. Read-only on code: no worktree, no branch, no commits, no dev chaining. This is the inverse of `/multi-agent:create-jira` (which authors a well-formed item); here we grade an existing one.
+
+Both `/multi-agent:review-jira` and `/multi-agent:review-issue` execute this flow; only the provider (fetch + comment endpoint + picker) differs.
+
+## Language
+Instruction prose here is English. The verdict shown in chat and the comment body follow `prefs.global.outputLanguage` (the comment is authored for the user's team, same exception as create-jira). AskUserQuestion `label`/`header` stay English; `question`/`description` follow `outputLanguage`.
+
+## Step 1 - resolve the item
+- With an argument: `review-jira KEY-123` / `https://<jira>/browse/KEY-123`; `review-issue #N` / `repo#N` / GitHub issue URL.
+- With no argument: offer the picker - review-jira reuses the `jira` command's issue list (`jira/SKILL.md` JQL, assignee=currentUser, open); review-issue reuses the `issue` command's list (`gh issue list`). Single-select (one item reviewed per run; re-run for more).
+
+## Step 2 - fetch + base maturity
+Run `$HOME/.claude/lib/issue-fetcher.sh` (the same fetcher Phase 0 uses). It returns a descriptor with `title`, `type`, `status`, `description`, and `maturity = { score (0..100), blockers[], warnings[], summary }`. Reuse that maturity verbatim as the baseline; never re-fetch through MCP.
+
+## Step 3 - readiness rubric (extends maturity)
+Maturity is generic; add these pipeline-readiness dimensions by reading the fetched `title` + `description` (no invention - only judge what is written). Each is `pass` / `gap`:
+
+| Dimension | Ready when | Gap signal |
+|---|---|---|
+| Scope is testable | the change is bounded + verifiable (what "done" means is stated) | vague ("improve X"), no measurable outcome |
+| Acceptance criteria / DoD | AC or DoD present (Task/Story/Feature) | none (aligns with maturity `no_acceptance_criteria`) |
+| Reproduction | Bugs have steps + expected/actual | none (aligns with maturity `no_repro_steps`) |
+| Design reference | UI work links a Figma frame or attaches a screenshot | UI implied but no design source |
+| API contract | backend/integration work names endpoints or a Swagger/OpenAPI ref | data/contract implied, none given |
+| Platform / stack signal | the target stack is inferable (iOS / Android / frontend / backend) | ambiguous - Phase 1 could not route |
+| Dependencies | blocking deps/links are called out when they exist | hidden dependency likely |
+
+Only emit a dimension as a gap when its trigger applies (do not demand an API contract on a copy-change task). Merge: `gaps = maturity.blockers + maturity.warnings + rubric gaps`.
+
+## Step 4 - verdict (chat, always)
+Print a compact verdict; reuse the maturity blocker-vs-warning severity contract (same as the Phase 0 maturity check):
+
+```
+Readiness: KEY-123  -  score 60/100  -  NEEDS WORK
+BLOCK  Description is empty
+WARN   No acceptance criteria detected
+GAP    UI work but no design reference
+GAP    Target stack ambiguous
+```
+Verdict rule: any blocker -> NOT READY (blocking); else any warning/gap -> NEEDS WORK; else READY. Mirrors `jira/SKILL.md` maturity handling: blockers would halt a real run, warnings would prompt.
+
+## Step 5 - post the comment (confirmed)
+Posting to a tracker is outward-facing - confirm first (autopilot auto-posts):
+
+```
+question (outputLanguage): "Eksiklikleri {KEY|#N} üzerine yorum olarak ekleyeyim mi?"
+header   (English):        "Post readiness comment"
+options:
+  - label "Post comment", description (outputLanguage): "Eksiklik listesini item'a yorum olarak yaz"
+  - label "Chat only",    description (outputLanguage): "Sadece sohbet özeti, item'a dokunma"
+default: option 1
+```
+
+Comment body: a short "Multi-agent readiness review" heading, the score + verdict, then the gap list grouped Blockers / Warnings / Gaps, each with a one-line fix suggestion. Tone rules (same as `channels/issue-comment.md`): no AI/Claude/Copilot attribution, no "generated by", no em-dash/section-sign, plain ASCII; if referencing another item use `Ref: #N` never `Closes/Fixes`. READY items get a short "ready to pick up" confirmation instead of a gap list.
+
+Provider dispatch:
+- **Jira** (`review-jira`): post via `$HOME/.claude/multi-agent-refs/channels/jira.md` comment path - `POST /rest/api/2/issue/{id}/comment`, Bearer token from `keychainMapping.jira` via `credential-store.sh`, UTF-8 verbatim (`jq --rawfile` + `curl --data-binary @payload.json`), markdown->wiki conversion.
+- **GitHub** (`review-issue`): `gh issue comment "$N" --repo "$org/$repo" --body-file <file>` per `channels/issue-comment.md` (auth via the Phase 0 `gh` account).
+
+On post failure, surface the failing endpoint on stderr; the chat verdict remains the source of truth.
+
+## Not in scope
+No status transitions, no assignment changes, no issue creation, no code review (that is `/multi-agent:review`). This command only reads the item and comments its readiness.

package/pipeline/scripts/audit-log-rotate.sh

@@ -34,24 +34,52 @@ mkdir -p "$AUDIT_DIR"
 
 # Rotate today's file (only if it has content)
 if [ -s "$AUDIT_FILE" ]; then
-  STAMP="$(date -u -r "$AUDIT_FILE" +"%Y-%m-%d" 2>/dev/null || date -u +"%Y-%m-%d")"
+  # Portable file-mtime read. BSD `date -r` takes epoch SECONDS (not a file
+  # path), so the previous `date -r "$AUDIT_FILE"` always errored on macOS and
+  # mislabeled every rotated file with today's date.
+  case "$(uname -s)" in
+    Darwin|*BSD*) MTIME="$(stat -f %m "$AUDIT_FILE" 2>/dev/null || true)" ;;
+    *)            MTIME="$(stat -c %Y "$AUDIT_FILE" 2>/dev/null || true)" ;;
+  esac
+  if [ -n "$MTIME" ]; then
+    # BSD: date -r <epoch>; GNU: date -d @<epoch>
+    STAMP="$(date -u -r "$MTIME" +"%Y-%m-%d" 2>/dev/null \
+      || date -u -d "@$MTIME" +"%Y-%m-%d" 2>/dev/null \
+      || date -u +"%Y-%m-%d")"
+  else
+    STAMP="$(date -u +"%Y-%m-%d")"
+  fi
   ROTATED="$AUDIT_DIR/audit.${STAMP}.jsonl"
 
-  # Don't clobber a rotated file from earlier today (multiple invocations)
-  if [ -f "$ROTATED" ]; then
-    cat "$AUDIT_FILE" >> "$ROTATED"
+  # Atomic against concurrent appenders: mv the live inode FIRST, then create
+  # a fresh empty live file. Writers appending via >> to the moved inode land
+  # in the spool and are preserved; the old cat-then-truncate flow lost any
+  # event appended between the copy and the truncate.
+  SPOOL="$AUDIT_DIR/.audit.rotate.$$"
+  mv "$AUDIT_FILE" "$SPOOL"
+  : > "$AUDIT_FILE"
+  chmod 600 "$AUDIT_FILE" 2>/dev/null || true
+
+  # Don't clobber a rotated file from earlier today (multiple invocations).
+  # Earlier rotations may already be gzipped; appending a second gzip member
+  # is valid (gunzip concatenates members).
+  if [ -f "$ROTATED.gz" ] && command -v gzip >/dev/null 2>&1; then
+    if gzip -c "$SPOOL" >> "$ROTATED.gz" 2>/dev/null; then
+      rm -f "$SPOOL"
+    else
+      mv "$SPOOL" "$ROTATED"
+    fi
+  elif [ -f "$ROTATED" ]; then
+    cat "$SPOOL" >> "$ROTATED"
+    rm -f "$SPOOL"
   else
-    mv "$AUDIT_FILE" "$ROTATED"
+    mv "$SPOOL" "$ROTATED"
   fi
 
   # gzip immediately to save space
-  if command -v gzip >/dev/null 2>&1; then
+  if [ -f "$ROTATED" ] && command -v gzip >/dev/null 2>&1; then
     gzip -f "$ROTATED" 2>/dev/null || true
   fi
-
-  # Reset live file (mode 0600  -  sensitive)
-  : > "$AUDIT_FILE"
-  chmod 600 "$AUDIT_FILE" 2>/dev/null || true
 fi
 
 # Drop archives older than KEEP_DAYS

package/pipeline/scripts/check-md-links.mjs

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
-// Internal markdown link checker for the user-facing docs surface.
+// Internal markdown link checker for the user-facing docs surface and the
+// pipeline instruction tree.
 //
-// Scope: root *.md + docs/**/*.md + examples/**/*.md. Verifies that every
-// relative link target ([text](./path) or [text](path#anchor)) resolves to
-// an existing file or directory. External (http/https/mailto) links and
-// pure #anchors are skipped - this is a drift gate for file moves/renames,
-// not a network crawler.
+// Scope: root *.md + docs/**/*.md + examples/**/*.md + pipeline/**/*.md.
+// Verifies that every relative link target ([text](./path) or
+// [text](path#anchor)) resolves to an existing file or directory. Skipped:
+// external (http/https/mailto) links, pure #anchors, template links whose
+// path contains a {placeholder} variable, and links through shell
+// variables ($HOME, ...) - except $HOME/.claude/multi-agent-refs/, which
+// is checked against its repo source (pipeline/multi-agent-refs/) so a
+// ref rename cannot leave stale runtime links behind. This is a drift
+// gate for file moves/renames, not a network crawler.
+//
+// Excluded trees: pipeline/skills/shared/external/ is vendored community
+// skill content - several packs (the Apple HIG set) index upstream
+// references/ companion files that are deliberately not vendored here.
 
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -25,10 +34,13 @@ function mdFiles(dir, acc = []) {
 
 const targets = [
   ...readdirSync(repoRoot).filter((f) => f.endsWith(".md")).map((f) => join(repoRoot, f)),
-  ...["docs", "examples"].filter((d) => existsSync(join(repoRoot, d))).flatMap((d) => mdFiles(join(repoRoot, d))),
+  ...["docs", "examples", "pipeline"].filter((d) => existsSync(join(repoRoot, d))).flatMap((d) => mdFiles(join(repoRoot, d))),
   // CHANGELOG-archive.md is frozen history - it legitimately references docs
   // that were deleted in later releases.
-].filter((f) => !f.endsWith("CHANGELOG-archive.md"));
+]
+  .filter((f) => !f.endsWith("CHANGELOG-archive.md"))
+  // Vendored community skill packs (see header note).
+  .filter((f) => !f.includes(join("pipeline", "skills", "shared", "external") + "/"));
 
 const LINK_RE = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
 const errors = [];
@@ -42,9 +54,22 @@ for (const file of targets) {
   for (const match of text.matchAll(LINK_RE)) {
     const raw = match[1];
     if (/^(https?:|mailto:|#)/.test(raw)) continue;
+    // Template placeholders ({fileKey}, {slug}, ...) resolve at runtime,
+    // never on disk - skip them.
+    if (raw.includes("{") || raw.includes("}")) continue;
     const target = raw.split("#")[0];
     if (target === "") continue;
-    const resolved = resolve(dirname(file), decodeURIComponent(target));
+    let resolved;
+    const refsPrefix = "$HOME/.claude/multi-agent-refs/";
+    if (target.startsWith(refsPrefix)) {
+      // Runtime install path with a repo source - check the source tree.
+      resolved = join(repoRoot, "pipeline", "multi-agent-refs", target.slice(refsPrefix.length));
+    } else if (target.includes("$") || target.startsWith("~")) {
+      // Other shell-variable / home paths resolve at runtime only.
+      continue;
+    } else {
+      resolved = resolve(dirname(file), decodeURIComponent(target));
+    }
     if (!existsSync(resolved)) {
       errors.push(`${file.slice(repoRoot.length + 1)}: broken link -> ${raw}`);
     }

package/pipeline/scripts/diff-risk-score.mjs

@@ -85,7 +85,6 @@ function loadDiff() {
     if (!existsSync(DIFF_FILE)) throw new Error(`diff file not found: ${DIFF_FILE}`);
     return readFileSync(DIFF_FILE, "utf8");
   }
-  BASE = resolveBase();
   return git(["diff", "--unified=0", `${BASE}...${HEAD}`]);
 }
 
@@ -295,6 +294,10 @@ function buildRow(stat, addedLines, allChangedPaths) {
 }
 
 function main() {
+  // Resolve the base ref ONCE, before any git diff runs. loadNumstat() and
+  // loadDiff() both interpolate BASE; resolving it lazily inside loadDiff()
+  // used to leave BASE=null for the numstat call (git diff null...HEAD).
+  if (!DIFF_FILE) BASE = resolveBase();
   const numstat = loadNumstat();
   if (numstat.length === 0) {
     process.stderr.write("diff-risk-score: empty diff\n");

package/pipeline/scripts/evidence-gate.mjs

@@ -138,7 +138,16 @@ if (body.trim().length === 0) {
 const successRe = userRegExp(args["success-pattern"], DEFAULT_MARKERS[claim].success, "success");
 const failureRe = userRegExp(args["failure-pattern"], DEFAULT_MARKERS[claim].failure, "failure");
 
-const showsFailure = failureRe.test(body);
+// Zero-count summaries ("0 failed", "0 tests failed out of 10", "0 failures")
+// are success statements, not failure markers. The default \bFAILED\b marker
+// would otherwise flip a passing log to fail - and failure is decisive. Only
+// applied when the DEFAULT failure marker is in play; a caller-supplied
+// --failure-pattern is matched against the raw body untouched.
+const ZERO_FAIL_SUMMARY = /\b0\s+(?:\w+\s+){0,2}(?:failed|failures?|failing)\b/gi;
+const usingDefaultFailure = !args["failure-pattern"] || args["failure-pattern"] === true;
+const failureBody = usingDefaultFailure ? body.replace(ZERO_FAIL_SUMMARY, "") : body;
+
+const showsFailure = failureRe.test(failureBody);
 const showsSuccess = successRe.test(body);
 
 // Failure is DECISIVE. A log that shows a definitive failure marker cannot