@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/scripts/smoke-lib-scripts.sh

@@ -0,0 +1,395 @@
+#!/usr/bin/env bash
+# smoke-lib-scripts.sh — sanity checks for picker library scripts.
+# Verifies each lib emits the expected JSON shape so the picker pipeline can
+# rely on it. Network-dependent paths (real Jira/GH fetch) are skipped; only
+# offline-detectable behavior is asserted.
+#
+# Covered:
+#   credential-store.sh   doctor, platform detection, get/set/delete cycle (macOS only)
+#   account-resolver.sh   returns JSON array with required fields
+#   issue-fetcher.sh      input-kind detection + maturity object shape
+#   multi-repo-pipeline.sh bridge → schema-valid agent-state.json v2.1.0
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+LIB_DIR="$REPO_ROOT/pipeline/lib"
+
+PASS=0
+FAIL=0
+
+ok()   { echo "  ✓ $1"; PASS=$((PASS+1)); }
+fail() { echo "  ✗ $1" >&2; FAIL=$((FAIL+1)); }
+
+# --- credential-store.sh -----------------------------------------------------
+echo "→ credential-store.sh"
+CRED="$LIB_DIR/credential-store.sh"
+if [ ! -x "$CRED" ]; then
+  fail "credential-store.sh missing or not executable"
+else
+  PLATFORM=$("$CRED" platform 2>/dev/null || echo "")
+  case "$PLATFORM" in
+    macos|windows|linux|unknown) ok "platform detected: $PLATFORM" ;;
+    *) fail "unexpected platform output: $PLATFORM" ;;
+  esac
+
+  if "$CRED" doctor 2>&1 | grep -qE '^Backend:'; then
+    ok "doctor reports backend"
+  else
+    fail "doctor missing Backend: line"
+  fi
+
+  # macOS only: full get/set/delete round-trip with throwaway key
+  if [ "$PLATFORM" = "macos" ]; then
+    KEY="multi-agent-smoke-test-$$"
+    VAL="smoke-value-$(date +%s)"
+    if "$CRED" set "$KEY" "$VAL" 2>/dev/null; then
+      readback=$("$CRED" get "$KEY" 2>/dev/null || echo "")
+      if [ "$readback" = "$VAL" ]; then
+        ok "set/get round-trip works"
+      else
+        fail "get returned '$readback' instead of '$VAL'"
+      fi
+      "$CRED" delete "$KEY" 2>/dev/null
+      empty=$("$CRED" get "$KEY" 2>/dev/null || echo "")
+      if [ -z "$empty" ]; then
+        ok "delete clears the entry"
+      else
+        fail "entry still present after delete"
+      fi
+    else
+      fail "set failed on macOS"
+    fi
+  fi
+fi
+
+# --- account-resolver.sh -----------------------------------------------------
+echo "→ account-resolver.sh"
+RESOLVER="$LIB_DIR/account-resolver.sh"
+if [ ! -x "$RESOLVER" ]; then
+  fail "account-resolver.sh missing or not executable"
+else
+  out=$("$RESOLVER" 2>/dev/null || echo "[]")
+  if printf '%s' "$out" | python3 -c 'import json,sys; json.loads(sys.stdin.read())' 2>/dev/null; then
+    ok "emits valid JSON"
+  else
+    fail "JSON output invalid: $(printf '%s' "$out" | head -c 200)"
+  fi
+
+  # When non-empty, every account must have the required fields
+  python3 - <<PY
+import json, sys
+try:
+    data = json.loads('''$out''')
+except Exception as e:
+    print(f"PARSE_FAIL:{e}")
+    sys.exit(0)
+
+if not data:
+    print("EMPTY")
+    sys.exit(0)
+
+required = {"id","label","prefix","providers","tokens","userKeys","users","jiraHost","bitbucketHost","isWork"}
+missing = []
+for i, acc in enumerate(data):
+    miss = required - set(acc.keys())
+    if miss:
+        missing.append((i, sorted(miss)))
+if missing:
+    print(f"MISSING_FIELDS:{missing}")
+else:
+    print(f"OK:{len(data)} accounts, all required fields present")
+PY
+  status=$(python3 - <<PY
+import json
+data = json.loads('''$out''')
+print("ok" if data and all({"id","label","prefix","providers","tokens","userKeys","users","jiraHost","bitbucketHost","isWork"} <= set(a.keys()) for a in data) else ("empty" if not data else "fields-missing"))
+PY
+)
+  case "$status" in
+    ok)             ok "all accounts have required schema fields" ;;
+    empty)          ok "no accounts on this machine (skipping schema check)" ;;
+    fields-missing) fail "some accounts missing required fields" ;;
+  esac
+fi
+
+# --- issue-fetcher.sh: input-kind detection (no network) ---------------------
+echo "→ issue-fetcher.sh"
+FETCHER="$LIB_DIR/issue-fetcher.sh"
+if [ ! -x "$FETCHER" ]; then
+  fail "issue-fetcher.sh missing or not executable"
+else
+  # detect_kind is internal; we exercise via freetext + jira-id paths that
+  # don't hit the network. Freetext is the safest offline assertion.
+  out=$("$FETCHER" "Login crash on iOS 17" 2>/dev/null || echo "")
+  if printf '%s' "$out" | python3 -c 'import json,sys; d=json.loads(sys.stdin.read()); assert d["kind"]=="freetext", d["kind"]; assert d["maturity"]["score"] is None, "freetext score should be None"' 2>/dev/null; then
+    ok "freetext path emits kind=freetext + maturity.score=None"
+  else
+    fail "freetext path output unexpected: $(printf '%s' "$out" | head -c 200)"
+  fi
+
+  # Jira-id detection without token (fetch will fail, but kind detection should still work)
+  out=$(ACCOUNT_JIRA_TOKEN_KEY="" ACCOUNT_JIRA_HOST="" "$FETCHER" "PROJ-1" 2>/dev/null || echo "")
+  if printf '%s' "$out" | python3 -c 'import json,sys; d=json.loads(sys.stdin.read()); assert d["kind"]=="jira", d["kind"]; assert d["key"]=="PROJ-1", d["key"]' 2>/dev/null; then
+    ok "jira-id path emits kind=jira + key parsed"
+  else
+    fail "jira-id path output unexpected"
+  fi
+fi
+
+# --- multi-repo-pipeline.sh: bridge --------------------------------------
+echo "→ multi-repo-pipeline.sh bridge"
+MRP="$LIB_DIR/multi-repo-pipeline.sh"
+if [ ! -x "$MRP" ]; then
+  fail "multi-repo-pipeline.sh missing or not executable"
+else
+  TMP=$(mktemp -d)
+  cat > "$TMP/state.json" <<EOF
+{
+  "taskId": "PROJ-1-smoke-$$",
+  "shortId": 1,
+  "branch": "feature/PROJ-1",
+  "baseBranch": "develop",
+  "issueRef": {"kind":"jira","key":"PROJ-1","title":"Smoke test"},
+  "primary": {"name":"my-app","cloneUrl":"git@github.com:org/my-app.git","provider":"github"},
+  "extras": [{"name":"common","cloneUrl":"git@github.com:org/common.git","provider":"github"}],
+  "worktreeRoot": "$TMP/worktree",
+  "commitType": "feat",
+  "identity": {"name":"Smoke","email":"smoke@example.com"}
+}
+EOF
+  bridged=$("$MRP" bridge "$TMP/state.json" 2>/dev/null || echo "")
+  if [ -z "$bridged" ] || [ ! -f "$bridged" ]; then
+    fail "bridge did not write agent-state.json"
+  else
+    if python3 - <<PY 2>/dev/null
+import json
+import jsonschema  # may not be installed in CI; fall back to shape check
+PY
+    then
+      python3 - "$bridged" "$REPO_ROOT/pipeline/schemas/agent-state.schema.json" <<'PY' && ok "bridge output schema-valid (jsonschema)" || fail "bridge output schema-invalid"
+import json, sys
+from jsonschema import Draft202012Validator
+data = json.load(open(sys.argv[1]))
+schema = json.load(open(sys.argv[2]))
+errs = list(Draft202012Validator(schema).iter_errors(data))
+if errs:
+    for e in errs: print("✗", "/".join(str(p) for p in e.absolute_path), e.message)
+    sys.exit(1)
+PY
+    else
+      # Fallback: shape-only check
+      if python3 - "$bridged" <<'PY' 2>/dev/null
+import json, sys
+d = json.load(open(sys.argv[1]))
+required = {"schemaVersion","taskId","shortId","project","branch","baseBranch","currentPhase","status","startedAt","phases","identity","projects"}
+missing = required - set(d.keys())
+assert not missing, f"missing: {missing}"
+assert d["schemaVersion"] == "2.1.0"
+assert len(d["projects"]) == 2
+PY
+      then
+        ok "bridge output has required fields (jsonschema unavailable; shape check)"
+      else
+        fail "bridge output missing required fields"
+      fi
+    fi
+    rm -rf "$(dirname "$bridged")"
+  fi
+  rm -rf "$TMP"
+fi
+
+# --- multi-repo-pipeline.sh: prepare + commit + teardown (offline) -----------
+# Uses local bare-repo fixtures so we can exercise prepare/commit/teardown
+# without network access. push and pr remain unverified (network-bound).
+echo "→ multi-repo-pipeline.sh prepare/commit/teardown (offline fixtures)"
+MRP="$LIB_DIR/multi-repo-pipeline.sh"
+if [ ! -x "$MRP" ]; then
+  fail "multi-repo-pipeline.sh not executable (already reported above)"
+else
+  FIXTURE_ROOT=$(mktemp -d)
+  REPO_A_BARE="$FIXTURE_ROOT/repo-a.git"
+  REPO_B_BARE="$FIXTURE_ROOT/repo-b.git"
+  WORKTREE_ROOT="$FIXTURE_ROOT/wt"
+
+  # Build two bare-repo fixtures with one initial commit each.
+  for bare in "$REPO_A_BARE" "$REPO_B_BARE"; do
+    git init --quiet --bare "$bare"
+    seed=$(mktemp -d)
+    git -C "$seed" init --quiet -b main
+    echo "init" > "$seed/README.md"
+    git -C "$seed" add README.md
+    git -C "$seed" -c user.email=t@e.com -c user.name=T commit --quiet -m "init"
+    git -C "$seed" remote add origin "$bare"
+    git -C "$seed" push --quiet origin main
+    rm -rf "$seed"
+  done
+
+  cat > "$FIXTURE_ROOT/state.json" <<EOF
+{
+  "taskId":"OFFLINE-1",
+  "shortId":1,
+  "branch":"feature/OFFLINE-1",
+  "baseBranch":"main",
+  "issueRef":{"kind":"jira","key":"OFFLINE-1","title":"smoke fixture"},
+  "primary":{"name":"repo-a","cloneUrl":"$REPO_A_BARE","provider":"github"},
+  "extras":[{"name":"repo-b","cloneUrl":"$REPO_B_BARE","provider":"github"}],
+  "worktreeRoot":"$WORKTREE_ROOT",
+  "commitType":"feat",
+  "identity":{"name":"T","email":"t@e.com"}
+}
+EOF
+
+  # prepare
+  if "$MRP" prepare "$FIXTURE_ROOT/state.json" >/dev/null 2>&1; then
+    if [ -d "$WORKTREE_ROOT/repo-a/.git" ] && [ -d "$WORKTREE_ROOT/repo-b/.git" ]; then
+      ok "prepare clones every repo into worktreeRoot"
+    else
+      fail "prepare did not create both worktrees"
+    fi
+    branch_a=$(git -C "$WORKTREE_ROOT/repo-a" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+    branch_b=$(git -C "$WORKTREE_ROOT/repo-b" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+    if [ "$branch_a" = "feature/OFFLINE-1" ] && [ "$branch_b" = "feature/OFFLINE-1" ]; then
+      ok "prepare checks out the task branch in every repo"
+    else
+      fail "prepare branch mismatch: a=$branch_a b=$branch_b"
+    fi
+  else
+    fail "prepare exited non-zero on offline fixture"
+  fi
+
+  # commit
+  echo "change-a" > "$WORKTREE_ROOT/repo-a/feature.txt"
+  echo "change-b" > "$WORKTREE_ROOT/repo-b/feature.txt"
+  git -C "$WORKTREE_ROOT/repo-a" config user.email t@e.com >/dev/null 2>&1
+  git -C "$WORKTREE_ROOT/repo-a" config user.name T >/dev/null 2>&1
+  git -C "$WORKTREE_ROOT/repo-b" config user.email t@e.com >/dev/null 2>&1
+  git -C "$WORKTREE_ROOT/repo-b" config user.name T >/dev/null 2>&1
+
+  if "$MRP" commit "$FIXTURE_ROOT/state.json" >/dev/null 2>&1; then
+    msg_a=$(git -C "$WORKTREE_ROOT/repo-a" log -1 --pretty=%s 2>/dev/null || echo "")
+    msg_b=$(git -C "$WORKTREE_ROOT/repo-b" log -1 --pretty=%s 2>/dev/null || echo "")
+    if printf '%s' "$msg_a" | grep -q '\[OFFLINE-1\]' && printf '%s' "$msg_b" | grep -q '\[OFFLINE-1\]'; then
+      ok "commit creates one commit per repo with [JIRA-KEY] suffix"
+    else
+      fail "commit messages missing key suffix: a=$msg_a b=$msg_b"
+    fi
+  else
+    fail "commit exited non-zero"
+  fi
+
+  # bridge (re-verify schema-valid output uses the repo names)
+  bridged=$("$MRP" bridge "$FIXTURE_ROOT/state.json" 2>/dev/null || echo "")
+  if [ -n "$bridged" ] && python3 -c '
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert len(d["projects"]) == 2
+assert d["projects"][0]["project"] == "repo-a"
+assert d["projects"][1]["project"] == "repo-b"
+' "$bridged" 2>/dev/null; then
+    ok "bridge populates projects[] from primary + extras"
+    rm -rf "$(dirname "$bridged")"
+  else
+    fail "bridge output missing projects[] entries"
+  fi
+
+  # teardown
+  "$MRP" teardown "$FIXTURE_ROOT/state.json" >/dev/null 2>&1
+  if [ ! -d "$WORKTREE_ROOT" ]; then
+    ok "teardown removes worktreeRoot"
+  else
+    fail "teardown left $WORKTREE_ROOT in place"
+  fi
+
+  rm -rf "$FIXTURE_ROOT"
+fi
+
+# --- channels-multi-repo.sh: render fan-out (offline) ------------------------
+echo "→ channels-multi-repo.sh renderers"
+CMR="$LIB_DIR/channels-multi-repo.sh"
+if [ ! -x "$CMR" ]; then
+  fail "channels-multi-repo.sh missing or not executable"
+else
+  TMP=$(mktemp -d)
+  cat > "$TMP/multi.json" <<'EOF'
+{
+  "schemaVersion":"2.1.0","taskId":"X","shortId":1,"project":"my-app",
+  "branch":"feature/X","baseBranch":"develop","currentPhase":6,"status":"in_progress",
+  "startedAt":"2026-04-27T12:00:00Z","phases":{},"identity":{"name":"T","email":"t@e.com"},
+  "projects":[
+    {"project":"my-app","projectRoot":"/tmp/a","branch":"feature/X","baseBranch":"develop","identity":{"name":"T","email":"t@e.com"},"pr":{"number":42,"url":"https://github.com/org/my-app/pull/42"}},
+    {"project":"common","projectRoot":"/tmp/b","branch":"feature/X","baseBranch":"develop","identity":{"name":"T","email":"t@e.com"},"pr":{"number":17,"url":"https://github.com/org/common/pull/17"}}
+  ]
+}
+EOF
+  cat > "$TMP/single.json" <<'EOF'
+{
+  "schemaVersion":"2.1.0","taskId":"Y","shortId":1,"project":"my-app",
+  "branch":"feature/Y","baseBranch":"develop","currentPhase":6,"status":"in_progress",
+  "startedAt":"2026-04-27T12:00:00Z","phases":{},"identity":{"name":"T","email":"t@e.com"},
+  "pr":{"number":1,"url":"https://github.com/org/my-app/pull/1"}
+}
+EOF
+  echo "body content" > "$TMP/body.md"
+
+  # targets: multi-repo gives 2 entries with cross-links populated
+  count=$("$CMR" targets "$TMP/multi.json" 2>/dev/null | python3 -c 'import json,sys; d=json.load(sys.stdin); print(len(d))')
+  if [ "$count" = "2" ]; then
+    ok "targets emits one entry per project (multi-repo)"
+  else
+    fail "targets count $count != 2"
+  fi
+
+  # render-pr: extras body must mention 'Part of:' primary URL
+  rendered=$("$CMR" render-pr "$TMP/multi.json" "$TMP/body.md" "common" 2>/dev/null)
+  if printf '%s' "$rendered" | grep -q "Part of: https://github.com/org/my-app"; then
+    ok "render-pr injects 'Part of:' link on extras"
+  else
+    fail "render-pr missing 'Part of:' on extras"
+  fi
+  rendered=$("$CMR" render-pr "$TMP/multi.json" "$TMP/body.md" "my-app" 2>/dev/null)
+  if printf '%s' "$rendered" | grep -q "Related: https://github.com/org/common"; then
+    ok "render-pr injects 'Related:' link on primary"
+  else
+    fail "render-pr missing 'Related:' on primary"
+  fi
+
+  # render-jira: bulleted PR list at top
+  rendered=$("$CMR" render-jira "$TMP/multi.json" "$TMP/body.md" 2>/dev/null)
+  bullet_count=$(printf '%s' "$rendered" | grep -c '^\* PR:' || echo 0)
+  if [ "$bullet_count" = "2" ]; then
+    ok "render-jira prepends bulleted PR list (2 entries)"
+  else
+    fail "render-jira bullet count $bullet_count != 2"
+  fi
+
+  # render-conf: ## Related PRs heading
+  rendered=$("$CMR" render-conf "$TMP/multi.json" "$TMP/body.md" 2>/dev/null)
+  if printf '%s' "$rendered" | grep -q "## Related PRs"; then
+    ok "render-conf prepends 'Related PRs' heading"
+  else
+    fail "render-conf missing heading block"
+  fi
+
+  # single-repo passthrough: render-pr on single state must return body unchanged
+  rendered=$("$CMR" render-pr "$TMP/single.json" "$TMP/body.md" "my-app" 2>/dev/null)
+  if [ "$rendered" = "body content" ]; then
+    ok "single-repo passthrough leaves body unchanged"
+  else
+    fail "single-repo passthrough mutated body: $rendered"
+  fi
+
+  rm -rf "$TMP"
+fi
+
+# --- Summary -----------------------------------------------------------------
+echo ""
+TOTAL=$((PASS+FAIL))
+if [ $FAIL -eq 0 ]; then
+  echo "══ lib-scripts smoke: $PASS passed, 0 failed ══"
+  exit 0
+else
+  echo "══ lib-scripts smoke: $PASS passed, $FAIL failed (of $TOTAL) ══" >&2
+  exit 1
+fi

package/pipeline/scripts/smoke-migrate-state.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# smoke-migrate-state.sh — verify migrate-state.mjs behavior with synthetic
+# migrations. Does not depend on any real migration file existing — it lays
+# one down in a temp dir and points the runner at a fixture.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RUNNER="$SCRIPT_DIR/migrate-state.mjs"
+
+if [ ! -f "$RUNNER" ]; then
+  echo "FAIL: migrate-state.mjs not found" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+pass() { PASS=$((PASS+1)); echo "  ✓ $1"; }
+fail() { FAIL=$((FAIL+1)); echo "  ✗ $1"; }
+
+TMPDIR=$(mktemp -d) || { echo "FAIL: mktemp" >&2; exit 1; }
+trap 'rm -rf "$TMPDIR"' EXIT
+
+# Test 1 — file at current version exits 0, no migration needed
+cat > "$TMPDIR/agent-state.json" <<'EOF'
+{"schemaVersion":"2.1.0","foo":"bar"}
+EOF
+OUT=$(node "$RUNNER" "$TMPDIR/agent-state.json" 2>&1)
+if echo "$OUT" | grep -q "already at schemaVersion 2.1.0"; then
+  pass "current-version file is a no-op"
+else
+  fail "current-version file should be a no-op (got: $OUT)"
+fi
+
+# Test 2 — missing schemaVersion exits 1
+echo '{"foo":"bar"}' > "$TMPDIR/bad.json"
+node "$RUNNER" --type=state "$TMPDIR/bad.json" 2>/dev/null
+if [ $? -eq 1 ]; then
+  pass "missing schemaVersion exits 1"
+else
+  fail "missing schemaVersion did not exit 1"
+fi
+
+# Test 3 — invalid JSON exits 1
+echo 'not-json' > "$TMPDIR/junk.json"
+node "$RUNNER" --type=state "$TMPDIR/junk.json" 2>/dev/null
+if [ $? -eq 1 ]; then
+  pass "invalid JSON exits 1"
+else
+  fail "invalid JSON did not exit 1"
+fi
+
+# Test 4 — missing file exits 1
+node "$RUNNER" --type=state "$TMPDIR/does-not-exist.json" 2>/dev/null
+if [ $? -eq 1 ]; then
+  pass "missing file exits 1"
+else
+  fail "missing file did not exit 1"
+fi
+
+# Test 5 — no migration path (older version than any migration)
+echo '{"schemaVersion":"0.1.0"}' > "$TMPDIR/ancient.json"
+node "$RUNNER" --type=state "$TMPDIR/ancient.json" 2>/dev/null
+if [ $? -eq 2 ]; then
+  pass "no migration path exits 2"
+else
+  fail "no migration path did not exit 2"
+fi
+
+# Test 6 — unknown flag exits 1
+node "$RUNNER" --nonsense "$TMPDIR/agent-state.json" 2>/dev/null
+if [ $? -eq 1 ]; then
+  pass "unknown flag exits 1"
+else
+  fail "unknown flag did not exit 1"
+fi
+
+# Test 7 — type auto-detection works
+cat > "$TMPDIR/multi-agent-preferences.json" <<'EOF'
+{"schemaVersion":"2.3.0","global":{"identities":[],"keychainMapping":{},"recentAccounts":[],"accounts":[]},"projects":{}}
+EOF
+OUT=$(node "$RUNNER" "$TMPDIR/multi-agent-preferences.json" 2>&1)
+if echo "$OUT" | grep -q "already at schemaVersion 2.3.0"; then
+  pass "prefs type auto-detected from filename"
+else
+  fail "prefs auto-detection failed (got: $OUT)"
+fi
+
+# Test 8 — ambiguous path requires --type
+cat > "$TMPDIR/ambig.json" <<'EOF'
+{"schemaVersion":"2.0.0"}
+EOF
+node "$RUNNER" "$TMPDIR/ambig.json" 2>/dev/null
+if [ $? -eq 1 ]; then
+  pass "ambiguous filename requires --type"
+else
+  fail "ambiguous filename did not require --type"
+fi
+
+echo ""
+echo "══ migrate-state smoke: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -eq 0 ] || exit 1

package/pipeline/scripts/smoke-mode-dispatch-drift.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+#
+# smoke-mode-dispatch-drift.sh — assert each mode dispatch file's tracker
+# section is consistent with the canonical generator output.
+#
+# Each mode dispatch file (dev.md, dev-autopilot.md, dev-local.md,
+# dev-local-autopilot.md, autopilot.md, local.md, local-autopilot.md) must
+# carry an inline "## Required: Phase Tracker Contract" section. v7.9.1 added
+# this contract; v8.0.0 added gen-mode-dispatch.mjs as the canonical
+# generator.
+#
+# As of v8.0.0 this smoke ENFORCES byte equality with the generator output.
+# Each mode dispatch file's tracker section must match `node gen-mode-dispatch.mjs
+# --mode=<name>` exactly. The generator is the source of truth; the on-disk
+# section is regenerated from it, never hand-edited.
+#
+# Mode → mode-name mapping (each pair is `<file>:<gen-mode>`):
+#   dev.md                   → dev
+#   dev-autopilot.md         → dev-autopilot
+#   dev-local.md             → dev-local
+#   dev-local-autopilot.md   → dev-local-autopilot
+#   autopilot.md             → autopilot
+#   local.md                 → local
+#   local-autopilot.md       → local-autopilot
+#
+# Exit codes: 0=pass, 1=drift detected
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+CMD_DIR="$REPO_ROOT/pipeline/commands/multi-agent"
+GEN="$REPO_ROOT/pipeline/scripts/gen-mode-dispatch.mjs"
+
+[ -f "$GEN" ] || { echo "FAIL: gen-mode-dispatch.mjs missing"; exit 2; }
+
+declare -a MODE_FAST_WITH_TEST=("dev.md")
+declare -a MODE_FAST_NO_TEST=("dev-autopilot.md" "dev-local.md" "dev-local-autopilot.md")
+declare -a MODE_FAST=("${MODE_FAST_WITH_TEST[@]}" "${MODE_FAST_NO_TEST[@]}")
+declare -a MODE_FULL=("autopilot.md" "local.md" "local-autopilot.md")
+
+PASS=0
+FAIL=0
+pass() { echo "  ✓ $*"; PASS=$((PASS + 1)); }
+fail() { echo "  ✗ $*"; FAIL=$((FAIL + 1)); }
+
+assert_section_present() {
+  local file="$1"
+  local count
+  count=$(grep -c '^## Required: Phase Tracker Contract' "$CMD_DIR/$file" || true)
+  case "$count" in
+    1) pass "$file declares tracker section exactly once" ;;
+    0) fail "$file is missing the tracker section" ;;
+    *) fail "$file has $count tracker sections (must be exactly 1)" ;;
+  esac
+}
+
+assert_phases() {
+  local file="$1"
+  shift
+  local expected_phases=("$@")
+  local section
+  section=$(awk '/^## Required: Phase Tracker Contract/{p=1} p{print} /^## /&&!/Required: Phase Tracker Contract/{p=0}' "$CMD_DIR/$file")
+  for ph in "${expected_phases[@]}"; do
+    if echo "$section" | grep -Fq "\"$ph\""; then
+      pass "$file declares phase $ph"
+    else
+      fail "$file missing phase $ph (expected for its mode family)"
+    fi
+  done
+}
+
+assert_ref_link() {
+  local file="$1"
+  if grep -Fq 'refs/tracker-contract.md' "$CMD_DIR/$file"; then
+    pass "$file links the tracker contract ref"
+  else
+    fail "$file missing tracker-contract.md link"
+  fi
+}
+
+echo "→ 1. Mode files declare the tracker contract section exactly once"
+for f in "${MODE_FAST[@]}" "${MODE_FULL[@]}"; do
+  assert_section_present "$f"
+done
+
+echo ""
+echo "→ 2a. Fast-mode files that keep User Test (dev.md) declare 5 phases (0/3/5/6/7)"
+for f in "${MODE_FAST_WITH_TEST[@]}"; do
+  assert_phases "$f" "0:Init" "3:Dev" "5:Test" "6:Commit" "7:Report"
+done
+
+echo ""
+echo "→ 2b. Fast-mode files that skip User Test (dev-autopilot/local/local-autopilot) declare 4 phases (0/3/6/7)"
+for f in "${MODE_FAST_NO_TEST[@]}"; do
+  assert_phases "$f" "0:Init" "3:Dev" "6:Commit" "7:Report"
+done
+
+echo ""
+echo "→ 3. Full-mode files (autopilot/local) declare all 8 phases"
+for f in "${MODE_FULL[@]}"; do
+  assert_phases "$f" "0:Init" "1:Analysis" "2:Planning" "3:Dev" "4:Review" "5:Test" "6:Commit" "7:Report"
+done
+
+echo ""
+echo "→ 4. Every mode file links refs/tracker-contract.md"
+for f in "${MODE_FAST[@]}" "${MODE_FULL[@]}"; do
+  assert_ref_link "$f"
+done
+
+echo ""
+echo "→ 5. Generator emits valid output for each mode"
+for mode in dev dev-autopilot dev-local dev-local-autopilot autopilot full local local-autopilot full-local; do
+  if node "$GEN" --mode="$mode" >/dev/null 2>&1; then
+    pass "gen-mode-dispatch.mjs --mode=$mode emits cleanly"
+  else
+    fail "gen-mode-dispatch.mjs --mode=$mode crashed or non-zero"
+  fi
+done
+
+if node "$GEN" --mode=bogus >/dev/null 2>&1; then
+  fail "gen-mode-dispatch.mjs accepted unknown mode 'bogus' — exit guard missing"
+else
+  pass "gen-mode-dispatch.mjs rejects unknown mode (exit 2)"
+fi
+
+echo ""
+echo "→ 6. Each mode file's tracker section is byte-equal to the generator output"
+# This is the strict gate: the generator is the source of truth, on-disk
+# sections are regenerated from it. Drift here means someone hand-edited a
+# mode file's tracker section without updating the generator. Fix:
+#   node pipeline/scripts/gen-mode-dispatch.mjs --mode=<m> > /tmp/gen.md
+#   <splice into the file's tracker section, or run the helper sync script>
+for pair in "dev.md:dev" "dev-autopilot.md:dev-autopilot" "dev-local.md:dev-local" \
+            "dev-local-autopilot.md:dev-local-autopilot" "autopilot.md:autopilot" \
+            "local.md:local" "local-autopilot.md:local-autopilot"; do
+  file="${pair%:*}"
+  mode="${pair#*:}"
+  path="$CMD_DIR/$file"
+  expected=$(node "$GEN" --mode="$mode")
+  # Extract on-disk section: from "## Required: Phase Tracker Contract" up to
+  # (but not including) the next top-level "## " heading. Trim trailing blank
+  # lines so the generator (which ends with one trailing newline) matches.
+  actual=$(awk '
+    /^## Required: Phase Tracker Contract/ { p=1 }
+    p && /^## / && !/^## Required: Phase Tracker Contract/ { exit }
+    p { print }
+  ' "$path")
+  if [ "$(printf '%s' "$expected" | sha256sum | cut -d" " -f1)" = \
+       "$(printf '%s' "$actual"   | sha256sum | cut -d" " -f1)" ]; then
+    pass "$file tracker section matches gen-mode-dispatch.mjs --mode=$mode"
+  else
+    fail "$file tracker section drift vs --mode=$mode"
+    diff <(printf '%s\n' "$expected") <(printf '%s\n' "$actual") | head -20 | sed 's/^/      /'
+  fi
+done
+
+echo ""
+echo "══ smoke-mode-dispatch-drift: $PASS passed, $FAIL failed ══"
+[ "$FAIL" -gt 0 ] && exit 1 || exit 0