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

package/dist/agent-config/hooks/workflow-dispatch-guard.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+# workflow-dispatch-guard.sh — PreToolUse hook (matcher: Bash)
+# Blocks spurious `gh workflow run` calls when the reason CI didn't trigger
+# is simply path filters — the changed files don't match the workflow's paths.
+#
+# Agents frequently misdiagnose path-filtered skips as skip-duplicate-actions
+# deduplication and respond by manually dispatching the workflow. This is
+# almost always wrong and produces spurious CI runs on unchanged packages.
+#
+# Logic:
+#   1. Intercept `gh workflow run <name>` commands
+#   2. Read the workflow YAML to extract on.push.paths / on.pull_request.paths
+#   3. Get changed files vs origin/main
+#   4. If no changed files match the workflow paths → block with explanation
+#   5. If paths match, no path filters defined, or anything is uncertain → allow
+#
+# Deployed by syncClaudeConfig() via mx-agent-system/agent-config/hooks/.
+#
+# Exit codes:
+#   0 = allow
+#   2 = block (path filters explain why CI didn't trigger — dispatch not needed)
+
+# Fail-open: any unexpected error → allow the command through
+trap 'exit 0' ERR
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# Only intercept gh workflow run
+if [[ ! "$COMMAND" =~ ^gh\ workflow\ run ]]; then
+  exit 0
+fi
+
+# ── Extract workflow name from command ───────────────────────────────────────
+# Handles: gh workflow run foo.yml
+#          gh workflow run foo.yml --ref branch
+#          gh workflow run "foo.yml" ...
+WORKFLOW_NAME=$(echo "$COMMAND" | sed -E 's/^gh[[:space:]]+workflow[[:space:]]+run[[:space:]]+([^[:space:]]+).*/\1/' | tr -d '"'"'")
+
+if [[ -z "$WORKFLOW_NAME" ]]; then
+  exit 0  # Can't parse workflow name — fail-open
+fi
+
+# ── Find repo root ────────────────────────────────────────────────────────────
+REPO_ROOT=""
+DIR="$(pwd)"
+for _ in $(seq 1 10); do
+  if [[ -d "$DIR/.github/workflows" ]]; 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
+
+# ── Locate the workflow file ──────────────────────────────────────────────────
+WORKFLOW_FILE="$REPO_ROOT/.github/workflows/$WORKFLOW_NAME"
+if [[ ! -f "$WORKFLOW_FILE" ]]; then
+  # Selector may be a display name or numeric ID — try resolving via gh CLI
+  if command -v gh &>/dev/null; then
+    RESOLVED_PATH=$(gh workflow view "$WORKFLOW_NAME" --json path -q .path 2>/dev/null || true)
+    if [[ -n "$RESOLVED_PATH" && -f "$REPO_ROOT/$RESOLVED_PATH" ]]; then
+      WORKFLOW_FILE="$REPO_ROOT/$RESOLVED_PATH"
+    else
+      exit 0  # Unresolvable selector — fail-open
+    fi
+  else
+    exit 0  # gh not available — fail-open
+  fi
+fi
+
+# ── Extract path filters from the workflow ───────────────────────────────────
+# Pull all entries under on.push.paths and on.pull_request.paths.
+# yq is not guaranteed to be installed; use python3 (available everywhere) or
+# fall back to a grep-based heuristic. Fail-open if neither works.
+
+extract_paths() {
+  local file="$1"
+  local _result
+  # Try python3 + PyYAML first (most reliable)
+  if command -v python3 &>/dev/null; then
+    _result=$(python3 - "$file" <<'PYEOF' 2>/dev/null
+import sys, yaml
+try:
+    with open(sys.argv[1]) as f:
+        data = yaml.safe_load(f)
+    on = data.get('on', data.get(True, {}))  # 'on' can parse as True in PyYAML
+    if not isinstance(on, dict):
+        sys.exit(0)
+    paths = []
+    for trigger in ('push', 'pull_request'):
+        t = on.get(trigger, {})
+        if isinstance(t, dict):
+            paths.extend(t.get('paths', []))
+    print('\n'.join(paths))
+except Exception:
+    sys.exit(0)
+PYEOF
+    )
+    if [[ -n "$_result" ]]; then
+      echo "$_result"
+      return
+    fi
+    # PyYAML not installed or produced no output — fall through to yq/awk
+  fi
+  # Fallback: yq if available
+  if command -v yq &>/dev/null; then
+    yq e '.on.push.paths[], .on.pull_request.paths[]' "$file" 2>/dev/null | grep -v '^null$' || true
+    return
+  fi
+  # Last resort: grep for '- ' lines after a 'paths:' line (fragile, but better than nothing)
+  awk '/paths:/{found=1; next} found && /^[[:space:]]*-[[:space:]]/{gsub(/^[[:space:]]*-[[:space:]]*/,""); print; next} found && /^[[:space:]]*[^-]/{found=0}' "$file" 2>/dev/null || true
+}
+
+PATH_FILTERS=$(extract_paths "$WORKFLOW_FILE")
+
+# No path filters defined → workflow triggers on all pushes → dispatch is plausible
+if [[ -z "$PATH_FILTERS" ]]; then
+  exit 0
+fi
+
+# ── Get changed files on this branch ─────────────────────────────────────────
+CHANGED_FILES=$(git -C "$REPO_ROOT" diff --name-only "origin/main...HEAD" 2>/dev/null || true)
+
+if [[ -z "$CHANGED_FILES" ]]; then
+  exit 0  # Can't determine changed files — fail-open
+fi
+
+# ── Check if any changed file matches any path filter ────────────────────────
+# Workflow path filters support glob patterns (e.g. `mcp-server/**`).
+# Use bash glob matching via case statement.
+
+matches_any_filter() {
+  local file="$1"
+  while IFS= read -r pattern; do
+    [[ -z "$pattern" ]] && continue
+    # Intentional glob matching — unquoted RHS is required for ** patterns
+    # shellcheck disable=SC2053
+    [[ $file == $pattern ]] && return 0
+  done <<< "$PATH_FILTERS"
+  return 1
+}
+
+HAS_MATCH=0
+while IFS= read -r f; do
+  [[ -z "$f" ]] && continue
+  if matches_any_filter "$f"; then
+    HAS_MATCH=1
+    break
+  fi
+done <<< "$CHANGED_FILES"
+
+# Changed files match the workflow's path filters → dispatch may be legitimate
+if [[ $HAS_MATCH -eq 1 ]]; then
+  exit 0
+fi
+
+# ── Block: path filters explain why CI didn't trigger ────────────────────────
+# Route to stderr — the harness surfaces a blocking hook's stderr only
+# (KI-HOOKS-STDERR-SYSTEMIC).
+{
+  echo ""
+  echo "workflow-dispatch-guard: blocked \`$COMMAND\`"
+  echo ""
+  echo "CI didn't trigger because your changed files don't match the path filters"
+  echo "in $(basename "$WORKFLOW_FILE"). This is expected behaviour — not a CI bug."
+  echo ""
+  echo "Workflow monitors:"
+  while IFS= read -r p; do
+    [[ -n "$p" ]] && echo "  $p"
+  done <<< "$PATH_FILTERS"
+  echo ""
+  echo "Your changed files (vs origin/main):"
+  while IFS= read -r f; do
+    [[ -n "$f" ]] && echo "  $f"
+  done <<< "$CHANGED_FILES"
+  echo ""
+  echo "No manual dispatch needed. If CI genuinely failed or needs re-running,"
+  echo "push a new commit that touches the paths above."
+} >&2
+exit 2

package/dist/agent-config/hooks/worktree-guard.sh

@@ -0,0 +1,258 @@
+#!/bin/bash
+# Worktree isolation guard - runs before every Bash command
+# Exit 0 = allow, Exit 2 = block (non-zero exit blocks the command)
+#
+# This hook enforces worktree isolation by:
+# 1. Blocking cd commands that leave the worktree directory
+# 2. Blocking dangerous git operations (belt-and-suspenders with settings.json)
+#
+# OUTPUT ROUTING (KI-HOOKS-STDERR-SYSTEMIC): all block messages go to stderr —
+# the harness surfaces a blocking hook's stderr, not its stdout.
+#
+# FALSE-POSITIVE HARDENING (block-report 2026-07-06): the git/cd patterns are
+# matched against a "scannable" copy of the command with heredoc BODIES removed
+# and are anchored to command-segment starts (^, or after ; & | && ||). This
+# stops documentation text that merely MENTIONS a blocked verb — e.g. a memory
+# or status report written via `cat <<EOF ... git merge --ff-only ... EOF`, or
+# `echo "use git merge"` — from being blocked. Heredoc/quoted PROSE is data, not
+# a command; unlike git-mutation-guard (destructive-git risk warrants accepting
+# prose false-positives), worktree-guard blocking documentation about branches
+# is not justified, so it is fixed here. NOTE: a REAL `git merge --ff-only` is
+# still blocked — that is intended isolation policy (sync via
+# `git rebase origin/main`, and settings.json also hard-denies `git merge *` at
+# the permission layer, which fires before this hook).
+#
+# Requires environment variables set by `worktree start`:
+# - CLAUDE_WORKTREE_PATH: Absolute path to worktree (e.g., /workspace/.worktrees/foo)
+# - CLAUDE_WORKTREE_NAME: Worktree name (e.g., foo)
+
+set -euo pipefail
+
+# Read the tool input from stdin (JSON format)
+INPUT=$(cat)
+
+# Extract the command - handle both direct command and tool_input formats
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // .command // empty' 2>/dev/null)
+
+if [[ -z "$COMMAND" ]]; then
+  # Can't parse command, allow it (fail open)
+  exit 0
+fi
+
+# Get worktree path from environment
+WORKTREE_PATH="${CLAUDE_WORKTREE_PATH:-}"
+
+# If no worktree restriction set, allow everything
+if [[ -z "$WORKTREE_PATH" ]]; then
+  exit 0
+fi
+
+# Normalize worktree path (remove trailing slash)
+WORKTREE_PATH="${WORKTREE_PATH%/}"
+
+# Get current working directory
+CURRENT_DIR=$(pwd)
+
+# --- heredoc-body stripping (consumer-aware) --------------------------------
+# Drop a heredoc body ONLY when its consuming command is inert (documentation/
+# report text via cat/tee/redirect-to-file/non-shell language). When the operator
+# line names a SHELL interpreter (bash/sh/zsh/dash/ksh/eval/source/`.`) or pipes
+# the body into one (`| ...sh`), the body IS executed, so it is KEPT and still
+# scanned — a blocked verb there is a real command, not prose. The operator line
+# itself is always preserved. Covers `<<EOF`, `<<-EOF`, `<<"EOF"`, `<<'EOF'`.
+strip_heredocs() {
+  awk '
+    !inbody {
+      line = $0
+      if (match(line, /<<[-]?[[:space:]]*["'"'"']?[A-Za-z_][A-Za-z0-9_]*["'"'"']?/)) {
+        d = substr(line, RSTART, RLENGTH)
+        gsub(/<<[-]?[[:space:]]*["'"'"']?/, "", d)
+        gsub(/["'"'"'].*/, "", d)
+        delim = d
+        inbody = 1
+        keepbody = 0
+        if (line ~ /(^|[^[:alnum:]_])(bash|sh|zsh|dash|ksh|eval|source)([^[:alnum:]_]|$)/) keepbody = 1
+        if (line ~ /(^|[[:space:]])\.[[:space:]]/) keepbody = 1
+        if (line ~ /\|[^|]*(bash|sh|zsh|dash|ksh|eval)([^[:alnum:]_]|$)/) keepbody = 1
+      }
+      print line
+      next
+    }
+    {
+      t = $0
+      gsub(/^[[:space:]]+/, "", t)
+      if (t == delim) { inbody = 0; keepbody = 0; next }
+      if (keepbody) print $0
+    }
+  '
+}
+
+SCAN=$(printf '%s' "$COMMAND" | strip_heredocs)
+
+# ============================================================
+# Rule 1: Block cd to paths outside worktree
+# ============================================================
+# FALSE-POSITIVE HARDENING (#3909): a `cd` only counts as real navigation when
+# it STARTS a command segment (CDSEG: start-of-line, or after a separator
+# `; & | ( {`, or a `then`/`do`/`else` shell keyword) — the same segment-anchor
+# approach as git-mutation-guard.sh's GITSEG (line ~148). Applied to the
+# already-heredoc-stripped SCAN. In ADDITION, an absolute target that is not a
+# directory ON THE LOCAL FILESYSTEM is ignored: a cd to a locally-nonexistent
+# path is harmless (it would just fail), and this is what removes the
+# remote-payload false-positive class — the `cd` runs on a REMOTE host, not
+# here. Examples that must NOT block:
+#   az vm run-command ... --scripts 'bash -c "... ; cd /home/azureuser/app ; ..."'
+#   ssh host "cd /var/www/remote-app && git pull"
+#   printf 'cd /remote/only/path\n'
+# Relative paths already fail open this way (empty RESOLVED below); this makes
+# absolute-path handling consistent. A REAL `cd /etc && ...` at a segment start
+# that resolves to an existing local dir outside the worktree still blocks.
+CDSEG='(^|[;&|({]|\s(then|do|else)\s)\s*'
+
+if echo "$SCAN" | grep -qE "${CDSEG}cd\s+"; then
+  # Extract cd target(s) that appear at a command-segment start only. The
+  # grep match may carry a leading separator/keyword prefix; strip everything
+  # up to and including the anchored `cd ` token, then strip surrounding quotes.
+  CD_TARGETS=$(echo "$SCAN" | grep -oE "${CDSEG}cd\s+[^;&|<>]+" \
+    | sed -E 's/^.*\bcd[[:space:]]+//' \
+    | tr -d '"'"'"'`' || true)
+
+  for TARGET in $CD_TARGETS; do
+    # Skip empty targets
+    [[ -z "$TARGET" ]] && continue
+
+    # Resolve the path
+    if [[ "$TARGET" == /* ]]; then
+      # Absolute path
+      RESOLVED="$TARGET"
+    elif [[ "$TARGET" == "~"* ]]; then
+      # Home directory path
+      RESOLVED="${TARGET/#\~/$HOME}"
+    else
+      # Relative path - resolve from current directory
+      RESOLVED=$(cd "$CURRENT_DIR" 2>/dev/null && cd "$TARGET" 2>/dev/null && pwd) || RESOLVED=""
+    fi
+
+    # Normalize resolved path
+    RESOLVED="${RESOLVED%/}"
+
+    # Ignore targets that are not a directory on the LOCAL filesystem. A cd to a
+    # locally-nonexistent path is harmless (it just fails), and this drops the
+    # remote-payload false-positive class (#3909). Relative paths already fail
+    # open via the resolution above (empty RESOLVED).
+    [[ -n "$RESOLVED" && -d "$RESOLVED" ]] || continue
+
+    # Allow /tmp and /var/tmp
+    if [[ "$RESOLVED" == /tmp* ]] || [[ "$RESOLVED" == /var/tmp* ]]; then
+      continue
+    fi
+
+    # Allow paths within worktree
+    if [[ "$RESOLVED" == "$WORKTREE_PATH"* ]]; then
+      continue
+    fi
+
+    # Allow the scratchpad directory
+    if [[ "$RESOLVED" == *"/scratchpad"* ]]; then
+      continue
+    fi
+
+    # Allow the user's home directory (for inspecting global tools, configs, etc.)
+    if [[ -n "$HOME" ]] && [[ "$RESOLVED" == "$HOME"* ]]; then
+      continue
+    fi
+
+    # Block: path is outside worktree
+    if [[ -n "$RESOLVED" ]]; then
+      # Route to stderr — the harness surfaces a blocking hook's stderr only.
+      {
+        echo ""
+        echo "BLOCKED: Cannot navigate outside worktree"
+        echo "  Target: $TARGET"
+        echo "  Resolved: $RESOLVED"
+        echo "  Allowed: $WORKTREE_PATH (and /tmp)"
+        echo ""
+        echo "You are working in worktree: ${CLAUDE_WORKTREE_NAME:-unknown}"
+        echo "Stay within your assigned worktree directory."
+        echo ""
+      } >&2
+      exit 2
+    fi
+  done
+fi
+
+# ============================================================
+# Rule 2: Block git operations that could tangle state
+# (Belt-and-suspenders with settings.json deny rules)
+# ============================================================
+
+# Segment anchor: a command starts at ^, or right after a separator. Besides
+# ; & | (which cover ; && || and pipe/background), include ( ` and $ so a git op
+# inside a subshell `(git ...)`, backticks `` `git ...` ``, or command
+# substitution `$(git ...)` is still caught (SHOULD FIX 1). Prose like
+# "planned a git merge" has a plain space before "git" and stays allowed.
+SEG='(^|[;&|(`$])\s*'
+
+# Block checkout to main
+if echo "$SCAN" | grep -qE "${SEG}git\s+(checkout|switch)\s+main(\s|$)"; then
+  {
+    echo ""
+    echo "BLOCKED: Cannot switch to main branch"
+    echo "  Command: $COMMAND"
+    echo "  Worktree: ${CLAUDE_WORKTREE_NAME:-unknown}"
+    echo ""
+    echo "To work on main, use a different worktree or the root workspace."
+    echo ""
+  } >&2
+  exit 2
+fi
+
+# Block checkout -b (new branch creation)
+if echo "$SCAN" | grep -qE "${SEG}git\s+(checkout\s+-b|switch\s+(-c|--create))"; then
+  {
+    echo ""
+    echo "BLOCKED: Cannot create new branches"
+    echo "  Command: $COMMAND"
+    echo "  Worktree: ${CLAUDE_WORKTREE_NAME:-unknown}"
+    echo ""
+    echo "Work on your assigned branch. Create PRs to merge changes."
+    echo ""
+  } >&2
+  exit 2
+fi
+
+# Block merge. NOTE: this also blocks `git merge --ff-only` (e.g. a branch-sync
+# fast-forward). That is intended worktree-isolation policy — sync via
+# `git rebase origin/main`, not merge. The block-report on 2026-07-06 was that
+# the reason was invisible (message went to stdout); routing to stderr fixes the
+# "blocked with no explanation" symptom.
+if echo "$SCAN" | grep -qE "${SEG}git\s+merge\s"; then
+  {
+    echo ""
+    echo "BLOCKED: Cannot merge branches directly"
+    echo "  Command: $COMMAND"
+    echo "  Worktree: ${CLAUDE_WORKTREE_NAME:-unknown}"
+    echo ""
+    echo "Use pull requests to merge changes, or 'git rebase origin/main' to sync."
+    echo ""
+  } >&2
+  exit 2
+fi
+
+# Block push to main
+if echo "$SCAN" | grep -qE "${SEG}git\s+push\s+.*\s*origin\s+main"; then
+  {
+    echo ""
+    echo "BLOCKED: Cannot push to main"
+    echo "  Command: $COMMAND"
+    echo ""
+    echo "Push to your worktree branch and create a PR."
+    echo ""
+  } >&2
+  exit 2
+fi
+
+# ============================================================
+# All checks passed - allow the command
+# ============================================================
+exit 0

package/dist/agent-config/rules/eval-harness.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "benchmarks/**"
+  - "swe-bench-cl/**"
+  - "mcp-server/agent-tests/**"
+  - "core-api/scripts/*eval*"
+  - "core-api/scripts/*benchmark*"
+---
+
+# Eval Harness Rules
+
+Eval work is decision infrastructure. Treat harness code, fixtures, scoring, analysis, and benchmark data as high-risk.
+
+## Required Practices
+
+- Put new benchmark implementations under `benchmarks/<benchmark-slug>/` unless the user explicitly directs a different location.
+- Preregister the eval design before running scored comparisons: task set, variants, metrics, exclusion rules, and pass/fail interpretation.
+- Add deterministic fixtures for every scoring path, including negative controls, case sensitivity, empty results, malformed data, and boundary cases.
+- Validate the harness with replay runs against known transcripts before trusting aggregate results.
+- Use an independent Code Reviewer for harness, scoring, sampling, persistence, and report-generation changes.
+- Maintain a claim ledger for findings. Every claim must have source data, reproduction steps, and a confidence level.
+- Do not convert exploratory evidence into a benchmark conclusion without checking whether a harness bug could explain it.
+
+## Visual Investigation
+
+- For nontrivial evals, prefer a small UI or notebook-style workbench that lets reviewers inspect tasks, traces, memory retrieved, scoring decisions, and aggregate deltas.
+- The visual tool is not a substitute for fixtures or replay validation; it is for investigation and reviewer confidence.
+
+## Memory-Specific Diagnostics
+
+- Capture what memory was retrieved, shown, ignored, reused, contradicted, or invalidated in each run.
+- Ask the agent for a brief post-run memory-use reflection when diagnosing memory impact, but do not treat self-report as ground truth.
+- Check whether memory anchored the agent on a dead end, repeated an invalid patch, or suppressed exploration.

package/dist/agent-config/rules/frontend.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "customer-portal/**"
+  - "marketing-site/**"
+  - "coe/**"
+  - "product/**/src/**"
+---
+
+# Frontend Rules
+
+Frontend changes need visual verification, not just unit tests.
+
+- Match the existing app's design system, density, spacing, and interaction patterns.
+- Verify responsive behavior on mobile and desktop before claiming completion.
+- Check for text overflow, overlap, broken loading/error states, and empty-state regressions.
+- Use screenshots or Playwright when the change affects layout, navigation, canvas, media, or user workflows.
+- Do not add instructional in-app copy to compensate for unclear controls; improve the interaction instead.

package/dist/agent-config/rules/mcp-protocol.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "mcp-server/**"
+  - "packages/**/mcp*/**"
+---
+
+# MCP Protocol Rules
+
+MCP changes affect agent behavior and external tool contracts.
+
+- Preserve tool schemas and response shapes unless the change is explicitly versioned and documented.
+- Add or update protocol-level tests for tool argument validation, error handling, and response compatibility.
+- Verify behavior through the MCP surface, not only internal helper functions.
+- Check existing memories and issues for known MCP regressions before making claims about current behavior.
+- Treat noisy or partial tool failures as data to investigate, not as proof that the feature works or fails.

package/dist/agent-config/rules/retrieval.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "core-api/src/repositories/**"
+  - "core-api/src/**/retrieval/**"
+  - "core-api/scripts/retrieval-*"
+  - "retrieval-workbench/**"
+---
+
+# Retrieval Rules
+
+Retrieval changes need corpus-level evidence and careful interpretation.
+
+- Define the corpus, query set, filters, and expected behavior before comparing variants.
+- Include negative controls and hard filters in tests, especially conversation, topic, scope, and time filters.
+- Separate retrieval quality, summarization quality, and UI/tool formatting when diagnosing failures.
+- Preserve superseded and invalidated semantics. Do not surface stale memories as current facts without clear labeling.
+- Report confidence with evidence: sample size, representative failures, and whether the delta survives manual inspection.