@memnexus-ai/mx-agent-cli 0.1.165 → 0.1.167

package/dist/agent-config/hooks/ci-validate-hook.sh

@@ -0,0 +1,499 @@
+#!/bin/bash
+# ci-validate-hook.sh — PreToolUse hook (matcher: Bash)
+# Runs package-level validation scripts before git push to catch locally
+# catchable CI failures (lint, build, typecheck, test) before they hit CI.
+#
+# Deployed by syncClaudeConfig() via mx-agent-system/agent-config/hooks/.
+# Runs alongside mx-guard-hook.sh — different layers:
+#   mx-guard-hook.sh  — infra-level (workflows, Helm, Docker, shell lint)
+#   ci-validate-hook.sh — code-level (package lint/build/test)
+#
+# Platform v2.31 (#3951) — under multi-session load the full jest suite flakes on
+# wall-clock-sensitive tests and blocks green pushes. Two mitigations live here:
+#   1. Machine-wide serialization: one flock around the whole validate block so
+#      concurrent agent sessions QUEUE instead of contending for CPU (the root
+#      cause of the flakes). Paired with a per-run jest --maxWorkers=50% cap in
+#      the validate-*.sh scripts so a single run can't saturate the box either.
+#   2. Isolate-and-retry-once de-flake: when a validate run fails ONLY at the
+#      test step with a bounded set of failed test files (≤ MAX_ISOLATE_FILES),
+#      re-run the FULL suite once, SERIALIZED (--runInBand), still under the
+#      flock. Full-suite-green-in-isolation ⇒ machine noise ⇒ gate passes with a
+#      NOTE (and the flake is logged). Still-failing ⇒ real regression (incl.
+#      order-dependent / shared-state coupling bugs a per-file retry would mask)
+#      ⇒ gate blocks. See SF-2 note on run_validate.
+#
+# Exit codes:
+#   0 = allow (not a push, or all validations pass, or a load-flake was absorbed)
+#   2 = block (a real validation failure, or the serialization lock timed out)
+
+# Fail-open: any unexpected error → let the push through. NOTE: the two
+# deliberately fail-CLOSED paths (lock timeout, confirmed real regression) use
+# explicit `exit 2` inside conditionals, so the ERR trap never downgrades them.
+trap 'exit 0' ERR
+set -u  # Catch undefined variable references (typos silently expand to empty otherwise)
+
+# ── State directory (SF-3: no predictable /tmp paths) ─────────────────────────
+# The lock and flake log must not live at fixed, world-writable /tmp paths — a
+# predictable name invites a symlink/clobber attack on a shared host (an attacker
+# pre-creates the path as a symlink to a victim file; our `exec 9>` would then
+# truncate it). Put them in a per-UID directory we own at mode 700. Preferred:
+# the systemd per-user runtime dir (XDG_RUNTIME_DIR / /run/user/$UID) — a 0700
+# tmpfs owned by the user and STABLE across sessions, so the machine-wide lock is
+# still shared. Fallbacks preserve the ownership guarantee.
+mx_validate_dir() {
+  local d uid owner
+  uid="$(id -u 2>/dev/null || echo 0)"
+
+  # 1. Per-user runtime dir (stable ⇒ shared lock; already 0700, user-owned).
+  local base="${XDG_RUNTIME_DIR:-/run/user/$uid}"
+  d="$base/mx-validate"
+  if mkdir -p "$d" 2>/dev/null && chmod 700 "$d" 2>/dev/null; then
+    printf '%s' "$d"; return 0
+  fi
+
+  # 2. Stable per-UID dir under TMPDIR — shared across sessions too, but only
+  #    trusted if it is a real directory we own and NOT a pre-planted symlink.
+  d="${TMPDIR:-/tmp}/mx-validate-$uid"
+  mkdir "$d" 2>/dev/null  # atomic create; ignore "already exists"
+  if [[ -d "$d" && ! -L "$d" ]]; then
+    owner="$(stat -c '%u' "$d" 2>/dev/null || echo -1)"
+    if [[ "$owner" == "$uid" ]]; then
+      chmod 700 "$d" 2>/dev/null || true
+      printf '%s' "$d"; return 0
+    fi
+  fi
+
+  # 3. Last resort: an unpredictable per-process dir. Safe from clobber, but not
+  #    shared across sessions — serialization degrades to per-process. Rare.
+  mktemp -d "${TMPDIR:-/tmp}/mx-validate.XXXXXX"
+}
+
+# ── Tunables (env-overridable; defaults are production values) ────────────────
+# Overridable so the co-located test suite can drive short timeouts / temp files.
+MX_VALIDATE_DIR="$(mx_validate_dir)"
+LOCK_FILE="${MX_VALIDATE_LOCK_FILE:-$MX_VALIDATE_DIR/validate.lock}"
+LOCK_TIMEOUT="${MX_VALIDATE_LOCK_TIMEOUT:-900}"          # seconds to wait in queue
+FLAKE_LOG="${MX_VALIDATE_FLAKE_LOG:-$MX_VALIDATE_DIR/flakes.log}"
+MAX_ISOLATE_FILES="${MX_VALIDATE_MAX_ISOLATE_FILES:-10}" # >this many failed files ⇒ real breakage
+
+FAILED=0
+
+# ── Parse failed test files from a runner's captured output ───────────────────
+# jest and vitest both print "FAIL <path>" for each failing test file. Strip ANSI
+# colour, take the path token, keep only things that look like a test/spec file,
+# and dedupe. A suite-level crash (jest-worker OOM, config/compile error) prints
+# NO per-file FAIL lines, so this returns empty — which the caller treats as
+# "not isolable ⇒ block" (a wholly-failed suite must never enter retry).
+parse_failed_test_files() {
+  local out="$1"
+  # SF-3: strip ANSI colour AND every other control character from the path
+  # token before it is trusted / logged (a filename with embedded control chars
+  # could corrupt the flake log or inject terminal escapes). The per-line `sed`
+  # operates on the token only — the inter-token newlines are the line
+  # separators, so they are preserved.
+  sed -E 's/\x1b\[[0-9;]*m//g' "$out" 2>/dev/null \
+    | grep -E '^[[:space:]]*FAIL[[:space:]]' 2>/dev/null \
+    | sed -E 's/^[[:space:]]*FAIL[[:space:]]+//' \
+    | awk '{print $1}' \
+    | sed -E 's/[[:cntrl:]]//g' \
+    | grep -E '\.(test|spec)\.[cm]?[jt]sx?$' 2>/dev/null \
+    | sort -u \
+    || true
+}
+
+# ── Append a load-flake record to the gitignored local log ────────────────────
+# Accumulates flake data (timestamp, load avg, package, files) for the follow-up
+# wall-clock-guard → operation-count conversion work. Best-effort; never blocks.
+record_flakes() {
+  local label="$1"; shift
+  local files_line
+  # SF-3: newlines/tabs → spaces, then drop any remaining control chars so the
+  # appended log line can't be corrupted by a hostile filename token.
+  files_line="$(printf '%s ' "$@" | tr '\n\t\r' '   ' | tr -d '[:cntrl:]')"
+  local ts load
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo 'unknown')"
+  load="$(cut -d' ' -f1 /proc/loadavg 2>/dev/null || echo '?')"
+  printf '%s\tload1m=%s\t%s\t%s\n' "$ts" "$load" "$label" "$files_line" \
+    >>"$FLAKE_LOG" 2>/dev/null || true
+}
+
+# ── Acquire the machine-wide validation lock (deliberate placement) ───────────
+# ONE lock in the hook around the whole validate block. Rationale (#3951):
+#   * Simplest correct design: it serializes even two same-package validates from
+#     two different sessions (the case the escalation specifically calls out).
+#   * Tradeoff, documented: different-package validates from two sessions ALSO
+#     serialize (they can't overlap). Accepted — cross-session CPU contention is
+#     exactly what we're removing, and the per-run --maxWorkers=50% cap keeps any
+#     single run from saturating the box, so total queue time stays bounded.
+#   * flock releases automatically on process death (fd close), so there is no
+#     stale-lock risk even if a session is killed mid-validate.
+acquire_lock() {
+  # Open the lock file on fd 9. If we can't even open it (unexpected infra
+  # error), fail-OPEN: this is not the gate's job and matches the hook's
+  # overall fail-open posture for unexpected conditions. NOTE: no `2>/dev/null`
+  # on this exec — `exec` with only redirections applies them to the CURRENT
+  # shell permanently, so a trailing `2>/dev/null` would silence the hook's own
+  # stderr for the whole run. The `|| { ... }` guard handles a failed open.
+  exec 9>"$LOCK_FILE" || { echo "ci-validate: WARN cannot open lock file $LOCK_FILE — proceeding without serialization." >&2; return 0; }
+
+  if flock -n 9; then
+    return 0  # uncontended — go straight through
+  fi
+
+  echo "ci-validate: another session is validating — queued (waiting up to ${LOCK_TIMEOUT}s)..." >&2
+  if flock -w "$LOCK_TIMEOUT" 9; then
+    echo "ci-validate: lock acquired — proceeding." >&2
+    return 0
+  fi
+
+  # Timeout → FAIL CLOSED. This is a CI gate: failing open here would let an
+  # UNVALIDATED push through under exactly the sustained-high-load conditions
+  # where a regression is most likely to slip in. So we block and tell the user
+  # to retry (queue will drain) rather than wave the push through.
+  local holder=""
+  if command -v fuser >/dev/null 2>&1; then
+    holder="$(fuser "$LOCK_FILE" 2>/dev/null | tr -s ' ' || true)"
+  fi
+  {
+    echo "ci-validate: TIMED OUT after ${LOCK_TIMEOUT}s waiting for the validation lock ($LOCK_FILE)."
+    [[ -n "$holder" ]] && echo "  Lock currently held by PID(s):$holder"
+    echo "  Push BLOCKED (fail-closed — the validation gate must not be skipped under load)."
+    echo "  The queue will drain; retry the push shortly."
+  } >&2
+  exit 2
+}
+
+# ── Run one validation script, with isolate-and-retry-once de-flake ───────────
+# All hook-authored output goes to stderr — the harness surfaces a blocking
+# hook's stderr, not its stdout (KI-HOOKS-STDERR-SYSTEMIC). Sub-validation output
+# is routed to stderr too so failures are visible on the block.
+run_validate() {
+  local script="$1"
+  local label="$2"
+  local script_path
+  case "$script" in
+    /*) script_path="$script" ;;                 # absolute (test seam)
+    *)  script_path="$REPO_ROOT/$script" ;;       # repo-relative (production)
+  esac
+  if [[ ! -f "$script_path" ]]; then
+    echo "⚠ $label: $script not found — skipping" >&2
+    return
+  fi
+
+  echo "" >&2
+  echo "Running $label validation..." >&2
+
+  local out; out="$(mktemp)"
+  local rc=0
+  # SF-1a: scrub the isolation-mode signals from the FIRST-pass environment.
+  # Otherwise an ambient MX_VALIDATE_SERIAL (or the legacy MX_VALIDATE_ISOLATE_
+  # FILES) would make the validate script exec straight into a serial/partial
+  # run and skip lint/build/the full parallel suite — silently turning the gate
+  # into a no-op. The deliberate retry below sets MX_VALIDATE_SERIAL explicitly,
+  # so nothing legitimate breaks.
+  env -u MX_VALIDATE_SERIAL -u MX_VALIDATE_ISOLATE_FILES bash "$script_path" >"$out" 2>&1 || rc=$?
+  cat "$out" >&2
+
+  if [[ $rc -eq 0 ]]; then
+    echo "✓ $label passed" >&2
+    rm -f "$out"
+    return
+  fi
+
+  # ── Failure: decide whether it is an isolable load flake or a real break ────
+
+  # A NON-test step failed (lint / typecheck / build / openapi / gate). The
+  # validate-*.sh scripts emit a structured `[FAIL] <step> ...` marker per failed
+  # step; any such marker that is not the test step means a real breakage that an
+  # isolated test re-run must NOT mask. Block immediately, no retry.
+  if grep -E '^\[FAIL\]' "$out" 2>/dev/null | grep -qivE 'test' ; then
+    echo "✗ $label FAILED — a non-test step failed (lint/typecheck/build/openapi/gate)." >&2
+    echo "  Not a load flake; blocking. Fix the errors above." >&2
+    FAILED=1; rm -f "$out"; return
+  fi
+
+  local failed_files nfiles
+  failed_files="$(parse_failed_test_files "$out")"
+  if [[ -z "$failed_files" ]]; then
+    nfiles=0
+  else
+    nfiles="$(printf '%s\n' "$failed_files" | wc -l | tr -d ' ')"
+  fi
+
+  # No isolable failed test files parsed ⇒ suite-level failure (compile error,
+  # jest-worker crash/OOM, config error). A wholly-failed suite must never enter
+  # retry — block.
+  if [[ "$nfiles" -eq 0 ]]; then
+    echo "✗ $label FAILED — no isolable failed test files found (suite-level failure/crash)." >&2
+    echo "  Not eligible for de-flake retry; blocking." >&2
+    FAILED=1; rm -f "$out"; return
+  fi
+
+  # Too many failed files ⇒ this is real breakage, not a couple of wall-clock
+  # flakes. Block immediately (bound the retry to ≤ MAX_ISOLATE_FILES).
+  if [[ "$nfiles" -gt "$MAX_ISOLATE_FILES" ]]; then
+    echo "✗ $label FAILED — $nfiles failed test files (> $MAX_ISOLATE_FILES cap)." >&2
+    echo "  Too broad to be load flake; blocking immediately." >&2
+    FAILED=1; rm -f "$out"; return
+  fi
+
+  # Eligible: ONE isolation pass. SF-2 — re-running ONLY the failed files would
+  # LAUNDER an order-dependent / shared-state failure: a test that fails solely
+  # because an earlier test in the suite mutated a shared singleton / DB / port /
+  # mock passes when run alone, and would be waved through as a "flake". So
+  # re-run the FULL suite once, SERIALIZED (jest --runInBand / maxWorkers=1),
+  # still under the machine-wide flock. Under the flock the retry runs on a quiet
+  # box, so genuine wall-clock load flakes (retrieval's case) pass; but because
+  # the WHOLE suite still runs, in order, a deterministic coupling bug still
+  # fails and blocks. Require GREEN to absorb.
+  # shellcheck disable=SC2086
+  echo "⟳ $label: $nfiles test file(s) failed under load — re-running the FULL suite ONCE in isolation (serial)..." >&2
+  # shellcheck disable=SC2086
+  printf '     under-load failure: %s\n' $failed_files >&2
+
+  local iso_out; iso_out="$(mktemp)"
+  local iso_rc=0
+  MX_VALIDATE_SERIAL=1 bash "$script_path" >"$iso_out" 2>&1 || iso_rc=$?
+  cat "$iso_out" >&2
+
+  local still_failing
+  still_failing="$(parse_failed_test_files "$iso_out")"
+
+  if [[ $iso_rc -eq 0 && -z "$still_failing" ]]; then
+    # Absorbed — the full suite is GREEN when run serially/uncontended, so the
+    # under-load failures were machine noise, not a real (or coupling) bug.
+    {
+      echo ""
+      echo "  ┌───────────────────────────────────────────────────────────────"
+      echo "  │ NOTE: $label flaked under load; FULL suite passed in isolation."
+      echo "  │ Treating as machine noise — gate PASSES for $label."
+      echo "  │ Under-load flaked test file(s):"
+      # shellcheck disable=SC2086
+      printf '  │   %s\n' $failed_files
+      echo "  │ Recorded to $FLAKE_LOG for follow-up de-flake work."
+      echo "  └───────────────────────────────────────────────────────────────"
+    } >&2
+    # shellcheck disable=SC2086
+    record_flakes "$label" $failed_files
+    rm -f "$out" "$iso_out"
+    return
+  fi
+
+  # The full serial suite still failed ⇒ a REAL regression (including an
+  # order-dependent / shared-state coupling bug the single-file retry would have
+  # masked). Report what still fails and block.
+  echo "✗ $label FAILED — full serial suite still failed in isolation; blocking." >&2
+  if [[ -n "$still_failing" ]]; then
+    echo "  REAL failures (fail even in a serial full-suite run):" >&2
+    # shellcheck disable=SC2086
+    printf '     %s\n' $still_failing >&2
+    local flakes
+    # under-load-only files that did NOT recur serially = load-flakes (informational)
+    # shellcheck disable=SC2086
+    flakes="$(comm -23 <(printf '%s\n' $failed_files | sort -u) <(printf '%s\n' $still_failing | sort -u) || true)"
+    if [[ -n "$flakes" ]]; then
+      echo "  Load-flakes (passed serially, not the blocker):" >&2
+      # shellcheck disable=SC2086
+      printf '     %s\n' $flakes >&2
+    fi
+  else
+    echo "  Serial re-run failed without parseable per-file FAIL lines (crash/compile" >&2
+    echo "  error under isolation) — see output above. Under-load failure(s) were:" >&2
+    # shellcheck disable=SC2086
+    printf '     %s\n' $failed_files >&2
+  fi
+  FAILED=1
+  rm -f "$out" "$iso_out"
+  return
+}
+
+# ── Test seam (SF-1b: must be impossible to engage silently on a real push) ───
+# Drives the lock + de-flake machinery against explicit fixture scripts without
+# a real repo / git diff, so ci-validate-hook.test.sh can exercise queueing,
+# timeout, and every de-flake branch deterministically. MX_VALIDATE_SELFTEST is a
+# space-separated list of "script::label" specs (script may be absolute).
+#
+# Two guards prevent the seam from shadowing real validation:
+#   1. It is only honoured when MX_VALIDATE_SELFTEST_OK=1 is ALSO set (a stray
+#      MX_VALIDATE_SELFTEST alone is ignored — the gate runs normally).
+#   2. Even with both set, if a real tool command is present on stdin (i.e. the
+#      harness invoked us for an actual push), we REFUSE with a loud banner and
+#      fail closed. Fixtures must never run in place of real validation.
+if [[ -n "${MX_VALIDATE_SELFTEST:-}" ]]; then
+  if [[ "${MX_VALIDATE_SELFTEST_OK:-}" != "1" ]]; then
+    echo "ci-validate: MX_VALIDATE_SELFTEST is set but MX_VALIDATE_SELFTEST_OK=1 is not — ignoring the test seam and running normal validation." >&2
+    # fall through to the real push path below
+  else
+    # `timeout` guards against a hang if run interactively with no stdin; the
+    # test harness redirects </dev/null so this returns instantly.
+    SELFTEST_STDIN="$(timeout 5 cat 2>/dev/null || true)"
+    SELFTEST_CMD="$(printf '%s' "$SELFTEST_STDIN" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+    if [[ -n "$SELFTEST_CMD" ]]; then
+      {
+        echo "╔══════════════════════════════════════════════════════════════════╗"
+        echo "║ SELFTEST MODE — REAL VALIDATION SKIPPED                           ║"
+        echo "╠══════════════════════════════════════════════════════════════════╣"
+        echo "║ MX_VALIDATE_SELFTEST + MX_VALIDATE_SELFTEST_OK were set while a"
+        echo "║ real tool command was present on stdin:"
+        echo "║   ${SELFTEST_CMD:0:120}"
+        echo "║ Refusing to run test fixtures in place of real validation."
+        echo "║ Push BLOCKED (fail-closed). Unset MX_VALIDATE_SELFTEST to push."
+        echo "╚══════════════════════════════════════════════════════════════════╝"
+      } >&2
+      exit 2
+    fi
+    REPO_ROOT="${MX_VALIDATE_SELFTEST_ROOT:-$PWD}"
+    acquire_lock
+    for spec in $MX_VALIDATE_SELFTEST; do
+      st_script="${spec%%::*}"
+      st_label="${spec##*::}"
+      run_validate "$st_script" "$st_label"
+    done
+    if [[ "$FAILED" -ne 0 ]]; then
+      echo "ci-validate(selftest): FAILED" >&2
+      exit 2
+    fi
+    echo "ci-validate(selftest): all checks passed." >&2
+    exit 0
+  fi
+fi
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# Cheap literal pre-filter: bail before the regex on any command that can't
+# contain "push". Keeps the pattern match off the hot path for the vast majority
+# of commands (and off long non-push commands).
+case "$COMMAND" in
+  *push*) ;;
+  *) exit 0 ;;
+esac
+
+# Only intercept git push commands. Match "git push" when it begins a command
+# segment. A start-anchored ^git\ push matcher silently let the repo's own
+# sanctioned compound pattern (cd $CLAUDE_WORKTREE_PATH/<pkg> && git push) and
+# other routine forms bypass validation. Segment starts recognised:
+#   - start of command (^)
+#   - a separator: ; & | { ( or a control char (newline/tab — [:cntrl:] matches
+#     newline but NOT space, so newline-joined commands are segmented without
+#     turning every space into a boundary). SF-3 added `(` for the subshell
+#     form ( git push ).
+#   - a shell keyword: then / do / else (e.g. `if ...; then git push; fi`)
+# Also tolerated before "git": leading redirections (`2>/dev/null `), env-var
+# assignments (VAR=1 git push), and launcher/wrapper words (sudo/env/nice/nohup/
+# time/timeout/ionice/stdbuf/command/xargs/setsid, optional numeric arg) so
+# wrapper-prefixed pushes aren't skipped. GIT GLOBAL OPTIONS between `git` and
+# `push` are consumed (High, #3934): `-C <path>`, `-c <k>=<v>`,
+# `--git-dir[=| ]<p>`, `--work-tree[=| ]<p>`, `--namespace[=| ]<p>`,
+# `--no-pager`, and generic single/double-dash forms with or without values.
+# Pre-#3934 only `-C <path>` was consumed, so common benign forms like
+# `git --no-pager push` and `git -c core.sshCommand=x push` skipped validation
+# entirely. The trailing group accepts `)` so the tight subshell form (git push)
+# closes correctly (SF-3). Kept consistent with git-mutation-guard GITSEG.
+PUSH_RE='(^|[;&|{([:cntrl:]]|[[:space:]](then|do|else)[[:space:]])[[:space:]]*([0-9]*[<>][^[:space:]]*[[:space:]]+|[A-Za-z_][A-Za-z0-9_]*=[^[:space:];&|]*[[:space:]]+|(sudo|env|nice|nohup|time|timeout|ionice|stdbuf|command|xargs|setsid)[[:space:]]+([0-9]+[[:space:]]+)?)*git([[:space:]]+(-C[[:space:]]+[^[:space:];&|]+|-c[[:space:]]+[^[:space:];&|]+|--(git-dir|work-tree|namespace|super-prefix)(=[^[:space:];&|]*|[[:space:]]+[^[:space:];&|]+)|--[A-Za-z][A-Za-z0-9-]*=[^[:space:];&|]*|--[A-Za-z][A-Za-z0-9-]*|-[A-Za-z]))*[[:space:]]+push([[:space:]]|[;&|)]|$)'
+if [[ ! "$COMMAND" =~ $PUSH_RE ]]; then
+  exit 0
+fi
+
+# ── Resolve repo root ────────────────────────────────────────────────────────
+# The hook runs from the worktree's .claude/hooks/ dir; scripts/ is at the
+# repo root. Find it by walking up from cwd.
+REPO_ROOT=""
+DIR="$(pwd)"
+for _ in $(seq 1 8); do
+  if [[ -f "$DIR/package.json" && -f "$DIR/pnpm-workspace.yaml" ]]; then
+    REPO_ROOT="$DIR"
+    break
+  fi
+  DIR="$(dirname "$DIR")"
+done
+
+if [[ -z "$REPO_ROOT" ]]; then
+  exit 0  # Can't find repo root — fail-open
+fi
+
+# ── Detect changed packages ──────────────────────────────────────────────────
+# Use three-dot diff against origin/main to find files changed on this branch.
+# Falls back to HEAD (single-commit diff) if origin/main isn't available.
+CHANGED_FILES=$(git -C "$REPO_ROOT" diff --name-only "origin/main...HEAD" 2>/dev/null \
+  || git -C "$REPO_ROOT" diff --name-only HEAD 2>/dev/null \
+  || true)
+
+if [[ -z "$CHANGED_FILES" ]]; then
+  exit 0  # No changed files detected — nothing to validate
+fi
+
+# ── Load the package→validate-script routing table ───────────────────────────
+# The map lives in ci-validate-routes.conf alongside this hook (portable projects
+# ship their own). Format: <path-prefix-glob>|<validate-script>|<label>, one rule
+# per line, '#' comments and blanks ignored. If the file is absent the hook logs
+# a note and skips validation (fail-open) — never blocks a push on a missing map.
+# MX_CI_VALIDATE_ROUTES overrides the path (test seam / portable override).
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd || echo "")"
+ROUTES_FILE="${MX_CI_VALIDATE_ROUTES:-$HOOK_DIR/ci-validate-routes.conf}"
+if [[ ! -f "$ROUTES_FILE" ]]; then
+  echo "ci-validate: routing table not found ($ROUTES_FILE) — skipping validation (fail-open, no packages routed)." >&2
+  exit 0
+fi
+
+R_PREFIX=(); R_SCRIPT=(); R_LABEL=()
+while IFS='|' read -r prefix script label _rest; do
+  # Trim surrounding whitespace on each field.
+  prefix="${prefix#"${prefix%%[![:space:]]*}"}"; prefix="${prefix%"${prefix##*[![:space:]]}"}"
+  script="${script#"${script%%[![:space:]]*}"}"; script="${script%"${script##*[![:space:]]}"}"
+  label="${label#"${label%%[![:space:]]*}"}";    label="${label%"${label##*[![:space:]]}"}"
+  # Skip comments and incomplete rows.
+  [[ -z "$prefix" || "${prefix:0:1}" == "#" ]] && continue
+  [[ -z "$script" || -z "$label" ]] && continue
+  R_PREFIX+=("$prefix"); R_SCRIPT+=("$script"); R_LABEL+=("$label")
+done < "$ROUTES_FILE"
+
+if [[ ${#R_PREFIX[@]} -eq 0 ]]; then
+  echo "ci-validate: routing table $ROUTES_FILE has no usable rules — skipping validation (fail-open)." >&2
+  exit 0
+fi
+
+# ── Match changed files against the routes ───────────────────────────────────
+MATCHED_IDX=()
+for ((ri=0; ri<${#R_PREFIX[@]}; ri++)); do
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    # shellcheck disable=SC2053  # intentional glob match against the route prefix
+    if [[ "$f" == ${R_PREFIX[$ri]} ]]; then
+      MATCHED_IDX+=("$ri")
+      break
+    fi
+  done <<< "$CHANGED_FILES"
+done
+
+# Nothing relevant changed
+if [[ ${#MATCHED_IDX[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+# ── Run validations (serialized machine-wide) ────────────────────────────────
+echo "ci-validate: checking changed packages before push..." >&2
+
+# Serialize the whole validate block across all sessions. Released on exit.
+acquire_lock
+
+for ri in "${MATCHED_IDX[@]}"; do
+  run_validate "${R_SCRIPT[$ri]}" "${R_LABEL[$ri]}"
+done
+
+# ── Result ───────────────────────────────────────────────────────────────────
+if [[ $FAILED -ne 0 ]]; then
+  {
+    echo ""
+    echo "ci-validate: push blocked — fix the errors above before pushing."
+    echo "  Run manually:"
+    for ((ri=0; ri<${#R_SCRIPT[@]}; ri++)); do
+      echo "    bash ${R_SCRIPT[$ri]}"
+    done
+  } >&2
+  exit 2
+fi
+
+echo "" >&2
+echo "ci-validate: all checks passed." >&2
+exit 0

package/dist/agent-config/hooks/ci-validate-routes.conf

@@ -0,0 +1,16 @@
+# ci-validate routing table — <path-prefix-glob>|<validate-script>|<label>
+#
+# One rule per line. ci-validate-hook.sh matches each changed file (repo-root
+# relative) against every <path-prefix-glob> (shell case-glob). On a match the
+# corresponding <validate-script> (repo-root relative) runs, tagged <label>.
+# Lines beginning with '#' and blank lines are ignored. Whitespace around the
+# '|' separators is trimmed.
+#
+# This file is the checked-in MemNexus default. If it is absent the hook logs a
+# note and skips validation (fail-open) — a portable project ships its own map.
+cli/*|scripts/validate-cli.sh|cli
+mcp-server/*|scripts/validate-mcp-server.sh|mcp-server
+customer-portal/*|scripts/validate-portal.sh|customer-portal
+core-api/*|scripts/validate-core-api.sh|core-api
+releases/sdk-generator/*|scripts/validate-sdk-generator.sh|sdk-generator
+benchmarks/*|scripts/validate-benchmarks.sh|benchmarks

package/dist/agent-config/hooks/delegation-audit.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# delegation-audit.sh — Delegation audit StopHook
+#
+# Emits an advisory when a session had many tool calls but zero sub-agent
+# delegation (no Agent or Task tool calls). This is non-blocking and advisory
+# only — it never prevents the session from ending.
+#
+# Fires on: Stop
+# Input: JSON on stdin with transcript_path, session_id, stop_hook_active
+# Output: advisory message to stdout (when threshold met)
+# Exit: always 0 (never blocks)
+
+# Fail-open: any error -> allow session to end normally
+trap 'exit 0' ERR
+
+# ── 1. Parse hook input ──────────────────────────────────────────────────
+INPUT=$(cat)
+
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)
+
+# ── 2. Anti-loop guard ───────────────────────────────────────────────────
+if [[ "$STOP_HOOK_ACTIVE" == "true" ]]; then
+  exit 0
+fi
+
+# ── 3. Fail-open guards ──────────────────────────────────────────────────
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+  exit 0
+fi
+command -v jq >/dev/null 2>&1 || exit 0
+
+# ── 4. Count total tool calls ────────────────────────────────────────────
+TOOL_CALL_COUNT=$(jq -r '
+  select(.type == "assistant") |
+  .message.content[]? |
+  select(.type == "tool_use") |
+  .name
+' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')
+
+# ── 5. Count delegation calls (Agent or Task) ────────────────────────────
+DELEGATION_COUNT=$(jq -r '
+  select(.type == "assistant") |
+  .message.content[]? |
+  select(.type == "tool_use") |
+  select(.name == "Agent" or .name == "Task") |
+  .name
+' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')
+
+# ── 6. Emit advisory if threshold met ────────────────────────────────────
+if [[ "$TOOL_CALL_COUNT" -ge 30 && "$DELEGATION_COUNT" -eq 0 ]]; then
+  # Route to stderr for consistency with the hook-output convention
+  # (KI-HOOKS-STDERR-SYSTEMIC) — user-facing advisories go to stderr.
+  {
+    echo "⚠️  Delegation audit: This session had ${TOOL_CALL_COUNT} tool calls but 0 sub-agent spawns."
+    echo "Consider delegating implementation, code review, and adversarial testing to sub-agents per your roleguide."
+    echo "Run 'mx memories recall --query \"delegation\"' to review delegation patterns."
+  } >&2
+fi
+
+exit 0