@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/scripts/phase-tracker.sh

@@ -0,0 +1,548 @@
+#!/usr/bin/env bash
+# phase-tracker.sh — stateful card-stack pipeline tracker, cross-CLI.
+#
+# Why this exists: Claude Code has TaskCreate/TaskUpdate which renders
+# native UI cards. Copilot CLI has nothing equivalent. This script gives
+# both CLIs the same "card stack" visual: each `update` call re-renders
+# the FULL task list to stdout so the user sees a snapshot of pipeline
+# progress that updates as work proceeds.
+#
+# State persists to a per-task JSON file so multiple shell invocations
+# share the same task list:
+#   $HOME/.claude/logs/multi-agent/<task_id>/tracker-state.json
+# (override with $TRACKER_FILE env var)
+#
+# Commands:
+#   init   <task_id>                                  Reset tracker for this task
+#   add    <phase_id> "<name>"                        Register a phase (status=pending)
+#   update <phase_id> <status>                        Change status + re-render
+#   sub    <phase_id> <sub_id> "<name>" [status]      Add or update a sub-phase
+#   tokens <phase_id> <in> <out>                      Add to phase's token totals (v5.5.0)
+#   model  <phase_id> <model_name>                    Tag phase with the LLM that produced its tokens (v8.3.0)
+#   meta   <phase_id> <key> <value>                   Set phase context (account, repos, files, now, ...)
+#   render                                            Print current snapshot, no change
+#
+# Status enum: pending | in_progress | completed | failed | skipped
+#
+# OTel span emission (v6.1.0+, opt-in):
+#   Set $MULTI_AGENT_OTEL_SPANS=1 to make every `update`, `sub`, and `tokens`
+#   action append one JSON line to:
+#     $HOME/.claude/logs/multi-agent/<task_id>/otel-spans.jsonl
+#   Each line is an OTLP-compatible JSON span with trace_id/span_id derived
+#   from the task_id, phase_id, and timestamp. Format intentionally simple
+#   so an OTel Collector's `filelog` receiver can tail + forward without a
+#   protobuf build step. Emission is never fatal — if jq is missing or the
+#   log dir isn't writable, we silently skip. Default OFF so users without
+#   an observability stack see zero behavior change.
+#
+# Examples:
+#   phase-tracker.sh init "TASK-123"
+#   for p in 0:Init 1:Analysis 2:Planning 3:Dev 4:Review 5:Test 6:Commit 7:Report; do
+#     phase-tracker.sh add "${p%%:*}" "${p#*:}"
+#   done
+#   phase-tracker.sh update 0 in_progress
+#   phase-tracker.sh update 0 completed
+#   phase-tracker.sh update 1 in_progress
+#   phase-tracker.sh sub    1 1 "Stack detection" completed
+#   phase-tracker.sh sub    1 2 "Codebase scan"   in_progress
+#
+# Exit codes: 0 ok, 64 usage error, 65 state file unreadable.
+
+set -uo pipefail
+
+if [ "$#" -lt 1 ]; then
+  cat >&2 <<USAGE
+usage:
+  phase-tracker.sh init   <task_id>
+  phase-tracker.sh add    <phase_id> "<name>"
+  phase-tracker.sh update <phase_id> <pending|in_progress|completed|failed|skipped>
+  phase-tracker.sh sub    <phase_id> <sub_id> "<name>" [status]
+  phase-tracker.sh tokens <phase_id> <in> <out>
+  phase-tracker.sh meta   <phase_id> <key> <value>
+  phase-tracker.sh render
+USAGE
+  exit 64
+fi
+
+ACTION="$1"; shift
+
+# State file location.
+TRACKER_FILE="${TRACKER_FILE:-}"
+if [ -z "$TRACKER_FILE" ]; then
+  TASK_ID_FROM_ENV="${MULTI_AGENT_TASK_ID:-}"
+  if [ "$ACTION" = "init" ] && [ "$#" -ge 1 ]; then
+    TASK_ID_FROM_ENV="$1"
+  fi
+  if [ -z "$TASK_ID_FROM_ENV" ]; then
+    # Fallback to the file written by the most recent init.
+    # WARNING: this pointer is global and flips when ANY shell on this user account runs
+    # `phase-tracker.sh init <other-task>`. In concurrent multi-agent runs (two terminals,
+    # two parallel pipelines), the pointer becomes the wrong task. Always pass
+    # MULTI_AGENT_TASK_ID per shell invocation for reliable per-session resolution.
+    POINTER="$HOME/.claude/logs/multi-agent/.tracker-current"
+    if [ -f "$POINTER" ]; then
+      TRACKER_FILE="$(cat "$POINTER")"
+      if [ "${MULTI_AGENT_QUIET:-0}" != "1" ]; then
+        POINTER_TASK=$(basename "$(dirname "$TRACKER_FILE")")
+        echo "phase-tracker: WARN — using pointer fallback (task=$POINTER_TASK). Pass MULTI_AGENT_TASK_ID=<id> for concurrent-safe resolution." >&2
+      fi
+    else
+      echo "phase-tracker: no task in scope; run 'init <task_id>' first or set MULTI_AGENT_TASK_ID" >&2
+      exit 64
+    fi
+  else
+    TRACKER_FILE="$HOME/.claude/logs/multi-agent/${TASK_ID_FROM_ENV}/tracker-state.json"
+  fi
+fi
+TRACKER_DIR="$(dirname "$TRACKER_FILE")"
+
+need_jq() {
+  command -v jq >/dev/null 2>&1 || {
+    echo "phase-tracker: jq is required" >&2
+    exit 65
+  }
+}
+
+# OTel-compatible span emission — v6.1.0+, opt-in via $MULTI_AGENT_OTEL_SPANS.
+# Appends one JSON line to otel-spans.jsonl. Never fatal on failure.
+#
+# Args:
+#   $1 = event_name (e.g. "phase.update", "phase.sub", "phase.tokens")
+#   $2 = phase_id (required)
+#   $3 = status or subject (string, optional)
+#   $4 = attributes (JSON object string, optional — merged into span.attributes)
+emit_otel_span() {
+  [ "${MULTI_AGENT_OTEL_SPANS:-0}" = "1" ] || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+  [ -n "${TRACKER_DIR:-}" ] || return 0
+  [ -d "$TRACKER_DIR" ] || return 0
+
+  local event="${1:-unknown}"
+  local phase_id="${2:-?}"
+  local subject="${3:-}"
+  local extra_attrs="${4:-{\}}"
+  local task_id
+  task_id=$(basename "$TRACKER_DIR")
+  local now_ns
+  now_ns=$(date +%s)000000000  # seconds * 1e9 (OTel wants nanos; bash-safe)
+  local spans_file="${TRACKER_DIR}/otel-spans.jsonl"
+
+  # Deterministic 128-bit trace_id from task_id, 64-bit span_id from event+phase+timestamp.
+  local trace_id span_id
+  trace_id=$(printf "%s" "$task_id" | shasum -a 256 | awk '{print substr($1,1,32)}')
+  span_id=$(printf "%s:%s:%s" "$event" "$phase_id" "$now_ns" | shasum -a 256 | awk '{print substr($1,1,16)}')
+
+  jq -nc \
+    --arg trace "$trace_id" --arg span "$span_id" \
+    --arg name "${event}.${phase_id}" \
+    --arg ts "$now_ns" \
+    --arg task "$task_id" --arg phase "$phase_id" --arg subj "$subject" \
+    --argjson extra "$extra_attrs" \
+    '{
+      traceId: $trace,
+      spanId: $span,
+      name: $name,
+      startTimeUnixNano: $ts,
+      endTimeUnixNano: $ts,
+      attributes: ({
+        "multi_agent.task_id": $task,
+        "multi_agent.phase_id": $phase,
+        "multi_agent.subject": $subj,
+        "service.name": "multi-agent-pipeline"
+      } + $extra)
+    }' >> "$spans_file" 2>/dev/null || true
+}
+
+# Color helpers (skip when not a TTY or TERM=dumb).
+if [ -t 1 ] && [ "${TERM:-}" != "dumb" ]; then
+  C_RESET=$'\033[0m'
+  C_DIM=$'\033[2m'
+  C_BOLD=$'\033[1m'
+  C_BLUE=$'\033[34m'
+  C_GREEN=$'\033[32m'
+  C_YELLOW=$'\033[33m'
+  C_RED=$'\033[31m'
+  C_PURPLE=$'\033[35m'
+  C_CYAN=$'\033[36m'
+else
+  C_RESET=""; C_DIM=""; C_BOLD=""
+  C_BLUE=""; C_GREEN=""; C_YELLOW=""; C_RED=""; C_PURPLE=""; C_CYAN=""
+fi
+
+glyph_for() {
+  case "$1" in
+    pending)     printf "${C_DIM}○${C_RESET}" ;;
+    in_progress) printf "${C_CYAN}●${C_RESET}" ;;
+    completed)   printf "${C_GREEN}✓${C_RESET}" ;;
+    failed)      printf "${C_RED}✗${C_RESET}" ;;
+    skipped)     printf "${C_YELLOW}↷${C_RESET}" ;;
+    *)           printf "?" ;;
+  esac
+}
+
+# Current time in epoch seconds (portable — works on both BSD and GNU date).
+now_epoch() {
+  date +%s
+}
+
+# Convert ISO-8601 UTC timestamp (YYYY-MM-DDTHH:MM:SSZ) to epoch seconds.
+# BSD date (macOS) uses -j -f; GNU date uses -d. Try BSD first, fall back.
+iso_to_epoch() {
+  local ts="$1"
+  [ -z "$ts" ] && { echo ""; return; }
+  local e
+  e=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$ts" +%s 2>/dev/null)
+  if [ -z "$e" ]; then
+    e=$(date -u -d "$ts" +%s 2>/dev/null)
+  fi
+  echo "$e"
+}
+
+# Format a token count as "Nk" (1200 → "1.2k", 12543 → "12.5k", 187 → "187").
+format_tokens() {
+  local n="$1"
+  [ -z "$n" ] || [ "$n" -le 0 ] 2>/dev/null && { echo ""; return; }
+  if [ "$n" -lt 1000 ]; then
+    printf "%d" "$n"
+  else
+    local whole=$((n / 1000))
+    local frac=$(( (n % 1000) / 100 ))
+    if [ "$frac" -eq 0 ]; then
+      printf "%dk" "$whole"
+    else
+      printf "%d.%dk" "$whole" "$frac"
+    fi
+  fi
+}
+
+# Format elapsed seconds as "Ns" or "Nm Ms".
+format_elapsed() {
+  local s="$1"
+  [ -z "$s" ] || [ "$s" -lt 0 ] 2>/dev/null && { echo ""; return; }
+  if [ "$s" -lt 60 ]; then
+    printf "%ds" "$s"
+  else
+    local m=$((s / 60))
+    local r=$((s % 60))
+    if [ "$r" -eq 0 ]; then
+      printf "%dm" "$m"
+    else
+      printf "%dm %ds" "$m" "$r"
+    fi
+  fi
+}
+
+# Read state, atomically write it back. Atomic = write to .tmp, rename.
+load_state() {
+  if [ ! -f "$TRACKER_FILE" ]; then
+    echo '{"task_id":"unknown","started_at":"","phases":[]}'
+  else
+    cat "$TRACKER_FILE"
+  fi
+}
+save_state() {
+  mkdir -p "$TRACKER_DIR" 2>/dev/null
+  printf '%s\n' "$1" > "${TRACKER_FILE}.tmp"
+  mv "${TRACKER_FILE}.tmp" "$TRACKER_FILE"
+}
+
+render() {
+  need_jq
+  local state
+  state="$(load_state)"
+  local task_id
+  task_id=$(echo "$state" | jq -r '.task_id') || {
+    echo "phase-tracker: corrupted state file — cannot parse task_id" >&2
+    exit 65
+  }
+  local phase_count
+  phase_count=$(echo "$state" | jq '.phases | length')
+
+  # Elapsed seconds per phase. No bar; just label.
+  #   completed/failed/skipped → completed_at - started_at (stamped)
+  #   in_progress              → now - started_at (live)
+  #   pending                  → "" (no label)
+  local now_s; now_s=$(now_epoch)
+  local -a elapsed_arr=()
+  local i=0
+  while [ "$i" -lt "$phase_count" ]; do
+    local pstatus s_iso e_iso s_ep e_ep el=""
+    pstatus=$(echo "$state" | jq -r ".phases[$i].status")
+    s_iso=$(echo "$state"   | jq -r ".phases[$i].started_at   // \"\"")
+    e_iso=$(echo "$state"   | jq -r ".phases[$i].completed_at // \"\"")
+    s_ep=$(iso_to_epoch "$s_iso")
+    e_ep=$(iso_to_epoch "$e_iso")
+    if [ -n "$s_ep" ]; then
+      case "$pstatus" in
+        completed|failed|skipped)
+          [ -n "$e_ep" ] && el=$((e_ep - s_ep))
+          ;;
+        in_progress)
+          el=$((now_s - s_ep))
+          ;;
+      esac
+    fi
+    if [ -n "$el" ] && [ "$el" -lt 0 ] 2>/dev/null; then el=0; fi
+    elapsed_arr+=("${el}")
+    i=$((i+1))
+  done
+
+  # Top border + title.
+  local title="Pipeline: ${task_id}"
+  local title_pad
+  title_pad=$(printf '%*s' $((56 - ${#title})) '' | tr ' ' '─')
+  printf "\n${C_BOLD}${C_BLUE}╭─ %s ${title_pad}╮${C_RESET}\n" "$title"
+
+  if [ "$phase_count" = "0" ]; then
+    printf "${C_BOLD}${C_BLUE}│${C_RESET}  ${C_DIM}(no phases registered yet)${C_RESET}\n"
+  else
+    # Iterate phases.
+    i=0
+    while [ "$i" -lt "$phase_count" ]; do
+      local pid pname pstatus
+      pid=$(echo "$state"     | jq -r ".phases[$i].id")
+      pname=$(echo "$state"   | jq -r ".phases[$i].name")
+      pstatus=$(echo "$state" | jq -r ".phases[$i].status")
+      local g
+      g=$(glyph_for "$pstatus")
+
+      local el="${elapsed_arr[$i]}"
+      local el_label=""
+      [ -n "$el" ] && el_label=$(format_elapsed "$el")
+
+      local el_color="${C_DIM}"
+      case "$pstatus" in
+        in_progress) el_color="${C_BOLD}${C_CYAN}" ;;
+        completed)   el_color="${C_GREEN}" ;;
+        failed)      el_color="${C_RED}" ;;
+        skipped)     el_color="${C_YELLOW}" ;;
+      esac
+
+      local p_tin p_tout p_ttotal tok_label=""
+      p_tin=$(echo  "$state" | jq -r ".phases[$i].tokens_in  // 0")
+      p_tout=$(echo "$state" | jq -r ".phases[$i].tokens_out // 0")
+      p_ttotal=$((p_tin + p_tout))
+      [ "$p_ttotal" -gt 0 ] && tok_label="$(format_tokens $p_ttotal) tok"
+
+      local right_block=""
+      if [ -n "$el_label" ] && [ -n "$tok_label" ]; then
+        right_block=$(printf "%b%s%b ${C_DIM}·${C_RESET} %b%s%b" "$el_color" "$el_label" "$C_RESET" "$C_DIM" "$tok_label" "$C_RESET")
+      elif [ -n "$el_label" ]; then
+        right_block=$(printf "%b%s%b" "$el_color" "$el_label" "$C_RESET")
+      elif [ -n "$tok_label" ]; then
+        right_block=$(printf "%b%s%b" "$C_DIM" "$tok_label" "$C_RESET")
+      fi
+
+      printf "${C_BOLD}${C_BLUE}│${C_RESET}  %b  Phase %-2s %-14s %b\n" \
+        "$g" "$pid" "${pname}" "$right_block"
+
+      # Meta block: only for active (in_progress) phase. Pretty-print key/value
+      # in insertion order so the pipeline's narrative sequence is preserved.
+      if [ "$pstatus" = "in_progress" ]; then
+        local meta_keys
+        meta_keys=$(echo "$state" | jq -r ".phases[$i].meta // {} | keys_unsorted[]" 2>/dev/null)
+        if [ -n "$meta_keys" ]; then
+          local key val
+          while IFS= read -r key; do
+            [ -z "$key" ] && continue
+            val=$(echo "$state" | jq -r ".phases[$i].meta[\"$key\"]")
+            printf "${C_BOLD}${C_BLUE}│${C_RESET}      ${C_DIM}%-10s${C_RESET}  %s\n" "${key}:" "$val"
+          done <<< "$meta_keys"
+        fi
+      fi
+
+      # Sub-phases (if any).
+      local sub_count
+      sub_count=$(echo "$state" | jq ".phases[$i].subs // [] | length")
+      if [ "$sub_count" != "0" ]; then
+        local j=0
+        while [ "$j" -lt "$sub_count" ]; do
+          local sid sname sstatus
+          sid=$(echo "$state"     | jq -r ".phases[$i].subs[$j].id")
+          sname=$(echo "$state"   | jq -r ".phases[$i].subs[$j].name")
+          sstatus=$(echo "$state" | jq -r ".phases[$i].subs[$j].status")
+          local sg
+          sg=$(glyph_for "$sstatus")
+          local connector="├─"
+          if [ "$j" = "$((sub_count - 1))" ]; then connector="└─"; fi
+          printf "${C_BOLD}${C_BLUE}│${C_RESET}      ${connector} %b  ${C_DIM}%s.%s${C_RESET}  %s\n" \
+            "$sg" "$pid" "$sid" "$sname"
+          j=$((j+1))
+        done
+      fi
+      i=$((i+1))
+    done
+  fi
+
+  # Total-tokens footer (v5.5.0) — sum phases[].tokens_in + tokens_out.
+  local total_tokens
+  total_tokens=$(echo "$state" | jq '[.phases[] | ((.tokens_in // 0) + (.tokens_out // 0))] | add // 0')
+  if [ "$total_tokens" -gt 0 ]; then
+    local total_label
+    total_label=$(format_tokens "$total_tokens")
+    printf "${C_BOLD}${C_BLUE}│${C_RESET}  ${C_DIM}%s${C_RESET}\n" "$(printf '%*s' 56 '' | tr ' ' '─')"
+    printf "${C_BOLD}${C_BLUE}│${C_RESET}  ${C_BOLD}Total${C_RESET}                         ${C_BOLD}${C_CYAN}%s tok${C_RESET}\n" "$total_label"
+  fi
+
+  printf "${C_BOLD}${C_BLUE}╰────────────────────────────────────────────────────────────╯${C_RESET}\n"
+}
+
+case "$ACTION" in
+
+  init)
+    [ "$#" -ge 1 ] || { echo "init needs <task_id>" >&2; exit 64; }
+    TASK_ID="$1"
+    TRACKER_FILE="$HOME/.claude/logs/multi-agent/${TASK_ID}/tracker-state.json"
+    TRACKER_DIR="$(dirname "$TRACKER_FILE")"
+    mkdir -p "$TRACKER_DIR" 2>/dev/null
+    NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    save_state "$(jq -nc --arg id "$TASK_ID" --arg ts "$NOW" \
+      '{task_id:$id,started_at:$ts,phases:[]}')"
+    # Update pointer so subsequent calls without env can find this tracker.
+    # NOTE: the pointer is global; for concurrent runs on the same user account,
+    # callers should set MULTI_AGENT_TASK_ID in their shell or prefix every
+    # subsequent tracker call (the pointer flips on the most recent init).
+    echo "$TRACKER_FILE" > "$HOME/.claude/logs/multi-agent/.tracker-current"
+    render
+    if [ "${MULTI_AGENT_QUIET:-0}" != "1" ]; then
+      echo "phase-tracker: tracker initialized for task=$TASK_ID" >&2
+      echo "phase-tracker: TIP — for concurrent-safe resolution, set:" >&2
+      echo "    export MULTI_AGENT_TASK_ID=$TASK_ID" >&2
+    fi
+    ;;
+
+  add)
+    need_jq
+    [ "$#" -ge 2 ] || { echo "add needs <phase_id> <name>" >&2; exit 64; }
+    PID="$1"; PNAME="$2"
+    state=$(load_state)
+    new=$(echo "$state" | jq --arg id "$PID" --arg name "$PNAME" \
+      '.phases += [{"id":$id,"name":$name,"status":"pending","subs":[]}]')
+    save_state "$new"
+    render
+    ;;
+
+  update)
+    need_jq
+    [ "$#" -ge 2 ] || { echo "update needs <phase_id> <status>" >&2; exit 64; }
+    PID="$1"; STATUS="$2"
+    case "$STATUS" in
+      pending|in_progress|completed|failed|skipped) ;;
+      *) echo "bad status: $STATUS" >&2; exit 64 ;;
+    esac
+    NOW_ISO=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    state=$(load_state)
+    # Set status, stamp started_at on first transition to in_progress,
+    # stamp completed_at on transition to terminal states (completed/failed/skipped).
+    new=$(echo "$state" | jq --arg id "$PID" --arg s "$STATUS" --arg ts "$NOW_ISO" '
+      .phases |= map(
+        if .id == $id then
+          .status = $s
+          | (if $s == "in_progress" and (.started_at // "") == "" then .started_at = $ts else . end)
+          | (if ($s == "completed" or $s == "failed" or $s == "skipped") then .completed_at = $ts else . end)
+        else . end
+      )
+    ')
+    save_state "$new"
+    emit_otel_span "phase.update" "$PID" "$STATUS" "{\"multi_agent.status\": \"$STATUS\"}"
+    render
+    ;;
+
+  sub)
+    need_jq
+    [ "$#" -ge 3 ] || { echo "sub needs <phase_id> <sub_id> <name> [status]" >&2; exit 64; }
+    PID="$1"; SID="$2"; SNAME="$3"; SSTATUS="${4:-pending}"
+    case "$SSTATUS" in
+      pending|in_progress|completed|failed|skipped) ;;
+      *) echo "bad status: $SSTATUS" >&2; exit 64 ;;
+    esac
+    state=$(load_state)
+    # If sub with this id exists under this phase, update; else append.
+    new=$(echo "$state" | jq \
+      --arg pid "$PID" --arg sid "$SID" --arg sname "$SNAME" --arg ss "$SSTATUS" \
+      '
+      .phases |= map(
+        if .id == $pid then
+          if any(.subs[]?; .id == $sid) then
+            .subs |= map(if .id == $sid then .name = $sname | .status = $ss else . end)
+          else
+            .subs += [{"id":$sid,"name":$sname,"status":$ss}]
+          end
+        else . end
+      )')
+    save_state "$new"
+    emit_otel_span "phase.sub" "$PID" "$SNAME" "{\"multi_agent.sub_id\": \"$SID\", \"multi_agent.status\": \"$SSTATUS\"}"
+    render
+    ;;
+
+  tokens)
+    need_jq
+    [ "$#" -ge 3 ] || { echo "tokens needs <phase_id> <in> <out>" >&2; exit 64; }
+    PID="$1"; T_IN="$2"; T_OUT="$3"
+    # Validate integers.
+    case "$T_IN$T_OUT" in
+      *[!0-9]*) echo "tokens: in/out must be non-negative integers" >&2; exit 64 ;;
+    esac
+    state=$(load_state)
+    # Additive: add to existing totals so multiple LLM calls accumulate.
+    new=$(echo "$state" | jq --arg id "$PID" --argjson ti "$T_IN" --argjson to "$T_OUT" '
+      .phases |= map(
+        if .id == $id then
+          .tokens_in  = ((.tokens_in  // 0) + $ti)
+          | .tokens_out = ((.tokens_out // 0) + $to)
+        else . end
+      )
+    ')
+    save_state "$new"
+    emit_otel_span "phase.tokens" "$PID" "" "{\"multi_agent.tokens_in_delta\": $T_IN, \"multi_agent.tokens_out_delta\": $T_OUT}"
+    # Re-render so live token count is visible on the active phase. Callers
+    # that want silent accumulation (e.g. tight loops) can suppress with
+    # TRACKER_QUIET=1 to skip the re-render but still write state.
+    if [ "${TRACKER_QUIET:-0}" != "1" ]; then
+      render
+    fi
+    ;;
+
+  meta)
+    need_jq
+    [ "$#" -ge 3 ] || { echo "meta needs <phase_id> <key> <value>" >&2; exit 64; }
+    PID="$1"; KEY="$2"; VALUE="$3"
+    state=$(load_state)
+    new=$(echo "$state" | jq --arg id "$PID" --arg k "$KEY" --arg v "$VALUE" '
+      .phases |= map(
+        if .id == $id then
+          .meta = ((.meta // {}) + {($k): $v})
+        else . end
+      )')
+    save_state "$new"
+    emit_otel_span "phase.meta" "$PID" "$KEY" "{\"multi_agent.meta_key\": \"$KEY\", \"multi_agent.meta_value\": \"$VALUE\"}"
+    if [ "${TRACKER_QUIET:-0}" != "1" ]; then
+      render
+    fi
+    ;;
+
+  model)
+    need_jq
+    [ "$#" -ge 2 ] || { echo "model needs <phase_id> <model_name>" >&2; exit 64; }
+    PID="$1"; MODEL="$2"
+    state=$(load_state)
+    new=$(echo "$state" | jq --arg id "$PID" --arg m "$MODEL" '
+      .phases |= map(
+        if .id == $id then .model = $m else . end
+      )')
+    save_state "$new"
+    emit_otel_span "phase.model" "$PID" "" "{\"multi_agent.model\": \"$MODEL\"}"
+    if [ "${TRACKER_QUIET:-0}" != "1" ]; then
+      render
+    fi
+    ;;
+
+  render)
+    render
+    ;;
+
+  *)
+    echo "phase-tracker: unknown action '$ACTION' (use init|add|update|sub|tokens|model|meta|render)" >&2
+    exit 64
+    ;;
+esac

package/pipeline/scripts/pre-commit-check.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Pre-commit secret detection for multi-agent pipeline
+# Scans staged git changes for accidentally committed secrets
+# Exit 0 = clean, Exit 1 = secrets found (blocks commit)
+
+set -uo pipefail
+
+STAGED_FILES=$(git diff --cached --name-only 2>/dev/null)
+
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+FOUND=0
+
+for file in $STAGED_FILES; do
+  [ ! -f "$file" ] && continue
+  file "$file" 2>/dev/null | grep -q "binary" && continue
+
+  # Only check added/modified lines
+  content=$(git diff --cached -- "$file" 2>/dev/null | grep "^+" | grep -v "^+++" || true)
+  [ -z "$content" ] && continue
+
+  # .env files
+  if echo "$file" | grep -qE '\.env($|\.)'; then
+    echo "BLOCKED: .env file staged: $file"
+    FOUND=1
+    continue
+  fi
+
+  # Credentials files
+  if echo "$file" | grep -qiE '(credentials|secrets|tokens)\.(json|yaml|yml|plist)$'; then
+    echo "BLOCKED: Credentials file staged: $file"
+    FOUND=1
+    continue
+  fi
+
+  # API keys / tokens (key = "long_string" pattern)
+  if echo "$content" | grep -qiE '(api[_-]?key|api[_-]?secret|access[_-]?token|auth[_-]?token|secret[_-]?key)\s*[:=]\s*["'"'"'][A-Za-z0-9+/=_-]{20,}'; then
+    echo "BLOCKED: Possible API key/token in $file"
+    FOUND=1
+  fi
+
+  # AWS access keys
+  if echo "$content" | grep -qE 'AKIA[0-9A-Z]{16}'; then
+    echo "BLOCKED: AWS access key in $file"
+    FOUND=1
+  fi
+
+  # Private keys
+  if echo "$content" | grep -qE 'BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY'; then
+    echo "BLOCKED: Private key in $file"
+    FOUND=1
+  fi
+
+  # Firebase/GCP service account JSON
+  if echo "$content" | grep -qE '"type"\s*:\s*"service_account"'; then
+    echo "BLOCKED: Service account JSON in $file"
+    FOUND=1
+  fi
+done
+
+if [ $FOUND -eq 1 ]; then
+  echo ""
+  echo "Secret check failed. Remove secrets from staged files before committing."
+  exit 1
+fi
+
+exit 0

package/pipeline/scripts/pre-push-check.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# pre-push-check.sh — primary gate before every push.
+#
+# Purpose:
+#   This repo has no GitHub Actions workflow — every push is validated
+#   locally. Unit tests, smoke suites, eval fixtures, schema validation,
+#   and the personal-data leak check all run here before `git push` is
+#   allowed to proceed.
+#
+# Install as a git pre-push hook:
+#   ln -sf ../../pipeline/scripts/pre-push-check.sh .git/hooks/pre-push
+#   chmod +x .git/hooks/pre-push
+#
+# Or run manually before pushing:
+#   bash pipeline/scripts/pre-push-check.sh
+#
+# Exit codes:
+#   0 — all gates passed, safe to push
+#   1 — a gate failed (test, lint, schema, or personal-data leak)
+#   2 — environment problem (node missing, npm missing, wrong cwd)
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$REPO_ROOT" || { echo "FAIL: can't cd to repo root" >&2; exit 2; }
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "FAIL: node not found" >&2
+  exit 2
+fi
+if ! command -v npm >/dev/null 2>&1; then
+  echo "FAIL: npm not found" >&2
+  exit 2
+fi
+
+echo "→ Running local CI gate (primary — no GitHub Actions workflow exists)"
+echo ""
+
+FAILED=0
+
+run_step() {
+  local name="$1"
+  shift
+  echo "→ $name"
+  if "$@"; then
+    echo "  ✓ $name passed"
+  else
+    echo "  ✗ $name FAILED" >&2
+    FAILED=$((FAILED+1))
+  fi
+  echo ""
+}
+
+run_step "unit tests"          node --test test/*.test.mjs
+run_step "smoke suites"        bash -c 'for f in pipeline/scripts/smoke-*.sh; do bash "$f" || exit 1; done'
+run_step "eval fixtures"       node pipeline/scripts/eval-triage.mjs
+run_step "schema validation"   node pipeline/scripts/validate-schemas.mjs
+run_step "lint"                npx --no-install eslint . --max-warnings 0
+
+# v3.7+ output-quality + token-budget gates (best-effort; skip if scripts absent).
+if [ -f "$HOME/.claude/scripts/output-quality-check.sh" ]; then
+  run_step "output quality"      bash "$HOME/.claude/scripts/output-quality-check.sh"
+fi
+if [ -f "$HOME/.claude/scripts/token-budget-report.mjs" ]; then
+  # Daily roll-up; non-zero exit means a budget breach was detected.
+  run_step "token budget"        node "$HOME/.claude/scripts/token-budget-report.mjs" --period daily
+fi
+
+if [ "$FAILED" -gt 0 ]; then
+  echo "" >&2
+  echo "✗ $FAILED gate(s) failed. Fix before pushing." >&2
+  echo "  To bypass (emergencies only): git push --no-verify" >&2
+  exit 1
+fi
+
+echo "✓ All gates passed — safe to push"
+exit 0