forge-workflow 0.0.3 → 0.0.5

package/scripts/behavioral-judge.sh

@@ -0,0 +1,378 @@
+#!/usr/bin/env bash
+# behavioral-judge.sh — Score /plan output using OpenRouter LLM judges
+#
+# Usage:
+#   echo '{"plan_output": "..."}' | bash scripts/behavioral-judge.sh
+#   bash scripts/behavioral-judge.sh '{"plan_output": "..."}'
+#
+# Environment:
+#   OPENROUTER_API_KEY              — Required (unless test mode)
+#   BEHAVIORAL_JUDGE_TEST_MODE      — Set to 1 to skip real HTTP calls
+#   BEHAVIORAL_JUDGE_MOCK_SCORES    — JSON scores for test mode, e.g. '{"security":4,"tdd":5,"design":4,"structural":3}'
+#   BEHAVIORAL_JUDGE_MOCK_PRIMARY_FAIL   — Set to 1 to simulate GLM-5 failure
+#   BEHAVIORAL_JUDGE_MOCK_SECONDARY_FAIL — Set to 1 to simulate MiniMax failure
+#   BEHAVIORAL_JUDGE_MOCK_TERTIARY_FAIL  — Set to 1 to simulate Kimi failure
+#
+# Output (stdout): JSON scoring result
+# Scores are NOT written to stderr — only diagnostic messages go there
+
+set -e
+
+# ─── Subcommand: check-lock-sync ─────────────────────────────────────────────
+# Usage: bash behavioral-judge.sh check-lock-sync <workflow.md>
+# Compares engine.model in .md frontmatter against the compiled .lock.yml.
+# Outputs: LOCK_IN_SYNC or LOCK_OUT_OF_SYNC (exit 0 in both cases)
+if [ "$1" = "check-lock-sync" ]; then
+  MD_FILE="${2:-}"
+  if [ -z "$MD_FILE" ] || [ ! -f "$MD_FILE" ]; then
+    echo "LOCK_OUT_OF_SYNC"
+    >&2 echo '{"result":"LOCK_OUT_OF_SYNC","reason":"md_file_not_found"}'
+    exit 0
+  fi
+  LOCK_FILE="${MD_FILE%.md}.lock.yml"
+  if [ ! -f "$LOCK_FILE" ]; then
+    echo "LOCK_OUT_OF_SYNC"
+    exit 0
+  fi
+  MD_MODEL=$(grep -A2 'engine:' "$MD_FILE" | grep 'model:' | awk '{print $2}' | tr -d '"' | head -1)
+  LOCK_MODEL=$(grep -A2 'engine:' "$LOCK_FILE" | grep 'model:' | awk '{print $2}' | tr -d '"' | head -1)
+  if [ "$MD_MODEL" = "$LOCK_MODEL" ]; then
+    echo "LOCK_IN_SYNC"
+  else
+    echo "LOCK_OUT_OF_SYNC"
+  fi
+  exit 0
+fi
+
+OPENROUTER_BASE_URL="https://openrouter.ai/api/v1/chat/completions"
+MODEL_PRIMARY="z-ai/glm-5"
+MODEL_SECONDARY="minimax/minimax-m2.5"
+MODEL_TERTIARY="moonshotai/kimi-k2.5"
+
+# Weighted scoring: security×3, tdd×3, design×2, structural×1 — max 45
+WEIGHT_SECURITY=3
+WEIGHT_TDD=3
+WEIGHT_DESIGN=2
+WEIGHT_STRUCTURAL=1
+
+# Classification thresholds
+THRESHOLD_PASS=36
+THRESHOLD_WEAK=27
+
+# Read input from stdin or $1
+if [ -n "$1" ]; then
+  INPUT="$1"
+else
+  INPUT="$(cat)"
+fi
+
+# Extract plan_output text if input is JSON, otherwise use raw input
+PLAN_TEXT="$INPUT"
+if command -v python3 >/dev/null 2>&1; then
+  EXTRACTED=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    val = d.get('plan_output', '')
+    if val:
+        print(val)
+except:
+    pass
+" 2>/dev/null) || true
+  if [ -n "$EXTRACTED" ]; then
+    PLAN_TEXT="$EXTRACTED"
+  fi
+fi
+
+# ─── Judge prompt ────────────────────────────────────────────────────────────
+build_prompt() {
+  local plan_output="$1"
+  cat <<PROMPT
+You are a strict quality judge for an AI development workflow. Score the following /plan execution output.
+
+Context: The forge /plan command has 3 phases:
+- Phase 1: Design Intent (Q&A → design doc with success criteria, edge cases, ambiguity policy)
+- Phase 2: Technical Research (OWASP analysis, TDD scenarios, library docs)
+- Phase 3: Setup (branch, worktree, Beads issue, task list with TDD steps)
+
+Scoring criteria (score each 0-5, where 5=excellent, 0=absent/unacceptable):
+
+SECURITY (weight ×3): Does Phase 2 include OWASP Top 10 analysis? Are security test scenarios identified? Is injection risk addressed for external API calls?
+
+TDD (weight ×3): Does Phase 3 task list have RED-GREEN-REFACTOR steps? Do >50% of tasks have explicit failing test step? Are test file paths specified?
+
+DESIGN (weight ×2): Does Phase 1 produce a design doc with: success criteria, edge cases, out-of-scope, ambiguity policy? Is it specific (not generic)?
+
+STRUCTURAL (weight ×1): Does Phase 3 include branch creation, worktree setup, Beads issue creation? Is a baseline test run included?
+
+Output ONLY valid JSON with no explanation:
+{"security": N, "tdd": N, "design": N, "structural": N}
+
+Plan output to score:
+${plan_output}
+PROMPT
+}
+
+# ─── Compute weighted scores and classification ───────────────────────────────
+compute_result() {
+  local security="$1"
+  local tdd="$2"
+  local design="$3"
+  local structural="$4"
+  local judge_model="$5"
+  local judge_calls="$6"
+
+  local sec_weighted=$(( security * WEIGHT_SECURITY ))
+  local tdd_weighted=$(( tdd * WEIGHT_TDD ))
+  local des_weighted=$(( design * WEIGHT_DESIGN ))
+  local str_weighted=$(( structural * WEIGHT_STRUCTURAL ))
+  local total=$(( sec_weighted + tdd_weighted + des_weighted + str_weighted ))
+
+  local result
+  if [ "$total" -ge "$THRESHOLD_PASS" ]; then
+    result="PASS"
+  elif [ "$total" -ge "$THRESHOLD_WEAK" ]; then
+    result="WEAK"
+  else
+    result="FAIL"
+  fi
+
+  cat <<JSON
+{
+  "result": "${result}",
+  "total": ${total},
+  "dimensions": {
+    "security": {"raw": ${security}, "weighted": ${sec_weighted}},
+    "tdd": {"raw": ${tdd}, "weighted": ${tdd_weighted}},
+    "design": {"raw": ${design}, "weighted": ${des_weighted}},
+    "structural": {"raw": ${structural}, "weighted": ${str_weighted}}
+  },
+  "judge_model": "${judge_model}",
+  "judge_calls": ${judge_calls}
+}
+JSON
+}
+
+# ─── Parse scores from LLM JSON response ─────────────────────────────────────
+parse_scores() {
+  local response="$1"
+  # Extract the JSON object from the LLM response content
+  local content
+  content=$(echo "$response" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    choices = data.get('choices', [])
+    if choices:
+        msg = choices[0].get('message', {})
+        content = msg.get('content', '')
+        print(content)
+except Exception as e:
+    pass
+" 2>/dev/null) || true
+
+  if [ -z "$content" ]; then
+    echo ""
+    return 1
+  fi
+
+  # Parse scores from content JSON
+  local scores
+  scores=$(echo "$content" | python3 -c "
+import sys, json, re
+text = sys.stdin.read().strip()
+# Try direct JSON parse first
+try:
+    d = json.loads(text)
+    s = int(d.get('security', -1))
+    t = int(d.get('tdd', -1))
+    de = int(d.get('design', -1))
+    st = int(d.get('structural', -1))
+    if all(0 <= x <= 5 for x in [s, t, de, st]):
+        print(f'{s} {t} {de} {st}')
+        sys.exit(0)
+except:
+    pass
+# Try extracting JSON from surrounding text
+m = re.search(r'\{[^}]+\}', text, re.DOTALL)
+if m:
+    try:
+        d = json.loads(m.group(0))
+        s = int(d.get('security', -1))
+        t = int(d.get('tdd', -1))
+        de = int(d.get('design', -1))
+        st = int(d.get('structural', -1))
+        if all(0 <= x <= 5 for x in [s, t, de, st]):
+            print(f'{s} {t} {de} {st}')
+            sys.exit(0)
+    except:
+        pass
+sys.exit(1)
+" 2>/dev/null) || { echo ""; return 1; }
+
+  echo "$scores"
+}
+
+# ─── Call OpenRouter with given model ────────────────────────────────────────
+call_openrouter() {
+  local model="$1"
+  local prompt="$2"
+  local extra_params="$3"
+
+  # Escape prompt for JSON
+  local escaped_prompt
+  escaped_prompt=$(echo "$prompt" | python3 -c "
+import sys, json
+print(json.dumps(sys.stdin.read()))
+" 2>/dev/null) || escaped_prompt='""'
+
+  local body
+  body=$(cat <<JSON
+{
+  "model": "${model}",
+  "messages": [{"role": "user", "content": ${escaped_prompt}}],
+  "response_format": {"type": "json_object"},
+  "temperature": 0${extra_params}
+}
+JSON
+)
+
+  local http_code
+  local response
+  response=$(curl -s -w "\n%{http_code}" \
+    -X POST "$OPENROUTER_BASE_URL" \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer ${OPENROUTER_API_KEY}" \
+    -H "HTTP-Referer: https://github.com/forge-cli/forge" \
+    -d "$body" \
+    --max-time 60 2>/dev/null) || { echo "CURL_FAILED"; return 1; }
+
+  http_code=$(echo "$response" | tail -n1)
+  local body_only
+  body_only=$(echo "$response" | sed '$d')
+
+  # Check for HTTP error codes indicating we should fall back
+  if [ "$http_code" = "429" ] || [[ "$http_code" =~ ^5 ]]; then
+    echo "HTTP_ERROR_${http_code}"
+    return 1
+  fi
+
+  echo "$body_only"
+}
+
+# ─── Test mode: bypass real HTTP calls ───────────────────────────────────────
+if [ "${BEHAVIORAL_JUDGE_TEST_MODE}" = "1" ]; then
+  # Determine which judge would succeed based on failure flags
+  judge_calls=0
+  judge_model=""
+  _default_scores='{"security":4,"tdd":4,"design":4,"structural":3}'
+  mock_scores="${BEHAVIORAL_JUDGE_MOCK_SCORES:-${_default_scores}}"
+  all_failed=false
+
+  # Attempt primary (GLM-5)
+  judge_calls=$(( judge_calls + 1 ))
+  if [ "${BEHAVIORAL_JUDGE_MOCK_PRIMARY_FAIL}" != "1" ]; then
+    judge_model="$MODEL_PRIMARY"
+  else
+    # Attempt secondary (MiniMax)
+    judge_calls=$(( judge_calls + 1 ))
+    if [ "${BEHAVIORAL_JUDGE_MOCK_SECONDARY_FAIL}" != "1" ]; then
+      judge_model="$MODEL_SECONDARY"
+    else
+      # Attempt tertiary (Kimi)
+      judge_calls=$(( judge_calls + 1 ))
+      if [ "${BEHAVIORAL_JUDGE_MOCK_TERTIARY_FAIL}" != "1" ]; then
+        judge_model="$MODEL_TERTIARY"
+      else
+        all_failed=true
+      fi
+    fi
+  fi
+
+  if [ "$all_failed" = "true" ]; then
+    echo '{"result": "INCONCLUSIVE", "reason": "all_judges_failed"}'
+    exit 0
+  fi
+
+  # Parse mock scores
+  scores=$(echo "$mock_scores" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+s = int(d.get('security', 3))
+t = int(d.get('tdd', 3))
+de = int(d.get('design', 3))
+st = int(d.get('structural', 3))
+print(f'{s} {t} {de} {st}')
+" 2>/dev/null) || scores="3 3 3 3"
+
+  read -r sec tdd_s des str <<< "$scores"
+  compute_result "$sec" "$tdd_s" "$des" "$str" "$judge_model" "$judge_calls"
+  exit 0
+fi
+
+# ─── Live mode: real API calls ───────────────────────────────────────────────
+if [ -z "$OPENROUTER_API_KEY" ]; then
+  >&2 echo "ERROR: OPENROUTER_API_KEY is not set"
+  echo '{"result": "INCONCLUSIVE", "reason": "missing_api_key"}'
+  exit 0
+fi
+
+PROMPT=$(build_prompt "$PLAN_TEXT")
+judge_calls=0
+
+# Primary: GLM-5 with reasoning disabled
+judge_calls=$(( judge_calls + 1 ))
+>&2 echo "Calling primary judge: $MODEL_PRIMARY"
+GLM5_EXTRA=', "reasoning": {"enabled": false}'
+response=$(call_openrouter "$MODEL_PRIMARY" "$PROMPT" "$GLM5_EXTRA" 2>/dev/null) || response="CALL_FAILED"
+
+if [ "$response" != "CALL_FAILED" ] && [[ "$response" != HTTP_ERROR* ]] && [ -n "$response" ]; then
+  scores=$(parse_scores "$response") || scores=""
+  if [ -n "$scores" ]; then
+    read -r sec tdd_s des str <<< "$scores"
+    compute_result "$sec" "$tdd_s" "$des" "$str" "$MODEL_PRIMARY" "$judge_calls"
+    exit 0
+  fi
+  >&2 echo "Primary judge returned unparseable response, falling back"
+else
+  >&2 echo "Primary judge failed (${response}), falling back to secondary"
+fi
+
+# Secondary: MiniMax M2.5 (no reasoning field)
+judge_calls=$(( judge_calls + 1 ))
+>&2 echo "Calling secondary judge: $MODEL_SECONDARY"
+response=$(call_openrouter "$MODEL_SECONDARY" "$PROMPT" "" 2>/dev/null) || response="CALL_FAILED"
+
+if [ "$response" != "CALL_FAILED" ] && [[ "$response" != HTTP_ERROR* ]] && [ -n "$response" ]; then
+  scores=$(parse_scores "$response") || scores=""
+  if [ -n "$scores" ]; then
+    read -r sec tdd_s des str <<< "$scores"
+    compute_result "$sec" "$tdd_s" "$des" "$str" "$MODEL_SECONDARY" "$judge_calls"
+    exit 0
+  fi
+  >&2 echo "Secondary judge returned unparseable response, falling back"
+else
+  >&2 echo "Secondary judge failed (${response}), falling back to tertiary"
+fi
+
+# Tertiary: Kimi K2.5 (chat_template_kwargs thinking:false, no tool calling)
+judge_calls=$(( judge_calls + 1 ))
+>&2 echo "Calling tertiary judge: $MODEL_TERTIARY"
+KIMI_EXTRA=', "chat_template_kwargs": {"thinking": false}'
+response=$(call_openrouter "$MODEL_TERTIARY" "$PROMPT" "$KIMI_EXTRA" 2>/dev/null) || response="CALL_FAILED"
+
+if [ "$response" != "CALL_FAILED" ] && [[ "$response" != HTTP_ERROR* ]] && [ -n "$response" ]; then
+  scores=$(parse_scores "$response") || scores=""
+  if [ -n "$scores" ]; then
+    read -r sec tdd_s des str <<< "$scores"
+    compute_result "$sec" "$tdd_s" "$des" "$str" "$MODEL_TERTIARY" "$judge_calls"
+    exit 0
+  fi
+  >&2 echo "Tertiary judge returned unparseable response"
+else
+  >&2 echo "Tertiary judge failed (${response})"
+fi
+
+# All judges failed
+>&2 echo "All judges failed — returning INCONCLUSIVE"
+echo '{"result": "INCONCLUSIVE", "reason": "all_judges_failed"}'

package/scripts/benchmark.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * Performance benchmark script for Forge CLI.
+ * Measures CLI startup time, autoDetect, and detectFramework performance.
+ *
+ * Usage:
+ *   node scripts/benchmark.js           # Human-readable output
+ *   node scripts/benchmark.js --json    # JSON output (for CI/tests)
+ */
+
+const { execFileSync } = require('node:child_process');
+const { performance } = require('node:perf_hooks');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const rootDir = path.join(__dirname, '..');
+const ITERATIONS = 3;
+
+function benchmarkCLIStartup() {
+  const times = [];
+  for (let i = 0; i < ITERATIONS; i++) {
+    const start = performance.now();
+    execFileSync('node', [path.join(rootDir, 'bin', 'forge.js'), '--help'], {
+      cwd: rootDir,
+      encoding: 'utf-8',
+      timeout: 10000,
+      stdio: 'pipe'
+    });
+    times.push(performance.now() - start);
+  }
+  const mean = times.reduce((a, b) => a + b, 0) / times.length;
+  return { name: 'CLI startup (--help)', mean: Math.round(mean), unit: 'ms', samples: ITERATIONS };
+}
+
+function benchmarkAutoDetect() {
+  const { autoDetect } = require(path.join(rootDir, 'lib', 'project-discovery.js'));
+  const times = [];
+  for (let i = 0; i < ITERATIONS; i++) {
+    const start = performance.now();
+    autoDetect(rootDir);
+    times.push(performance.now() - start);
+  }
+  const mean = times.reduce((a, b) => a + b, 0) / times.length;
+  return { name: 'autoDetect()', mean: Math.round(mean), unit: 'ms', samples: ITERATIONS };
+}
+
+function benchmarkDetectFramework() {
+  const { detectFramework } = require(path.join(rootDir, 'lib', 'project-discovery.js'));
+  const times = [];
+  for (let i = 0; i < ITERATIONS; i++) {
+    const start = performance.now();
+    detectFramework(rootDir);
+    times.push(performance.now() - start);
+  }
+  const mean = times.reduce((a, b) => a + b, 0) / times.length;
+  return { name: 'detectFramework()', mean: Math.round(mean), unit: 'ms', samples: ITERATIONS };
+}
+
+const results = [
+  benchmarkCLIStartup(),
+  benchmarkAutoDetect(),
+  benchmarkDetectFramework()
+];
+
+const jsonMode = process.argv.includes('--json');
+
+if (jsonMode) {
+  process.stdout.write(JSON.stringify(results));
+} else {
+  console.log('\n  Forge Performance Benchmarks');
+  console.log('  ===========================\n');
+  for (const r of results) {
+    const status = r.mean < 1000 ? 'PASS' : r.mean < 3000 ? 'WARN' : 'SLOW';
+    console.log(`  ${status}  ${r.name}: ${r.mean}${r.unit} (${r.samples} samples)`);
+  }
+  console.log('');
+
+  // Write results file
+  const outputPath = path.join(rootDir, 'benchmark-results.json');
+  fs.writeFileSync(outputPath, JSON.stringify(results, null, 2));
+  console.log(`  Results saved to: benchmark-results.json\n`);
+}
+
+module.exports = results;

package/scripts/branch-protection.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * Branch Protection Script (Cross-Platform)
+ *
+ * Prevents direct pushes to main/master branches.
+ * Uses Node.js for Windows compatibility (no shell-specific syntax).
+ *
+ * Exit codes:
+ *   0 - Push allowed
+ *   1 - Push blocked (protected branch)
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+// ANSI color codes
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const RESET = '\x1b[0m';
+
+/** Test-only: run mock-git.js via `node` so Windows does not need shell:true or git.exe shims */
+const GIT_MOCK_JS = process.env.NODE_ENV === 'test'
+  ? process.env.FORGE_GIT_MOCK_JS
+  : undefined;
+
+const EXEC_OPTS = { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+
+function fileExistsSync(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a real git binary (git.exe on Windows). Never uses shell — avoids injection via argv joining.
+ */
+function resolveGitBinary() {
+  const raw = (process.platform === 'win32'
+    ? (process.env.Path || process.env.PATH || '')
+    : (process.env.PATH || ''));
+  const dirs = raw.split(path.delimiter).filter(Boolean);
+  if (process.platform === 'win32') {
+    for (const d of dirs) {
+      const exe = path.join(d, 'git.exe');
+      if (fileExistsSync(exe)) return exe;
+    }
+    return 'git.exe';
+  }
+  for (const d of dirs) {
+    const g = path.join(d, 'git');
+    if (fileExistsSync(g)) return g;
+  }
+  return 'git';
+}
+
+/** Narrow ref shape for env-provided branch names (used in diff ref ranges). */
+function isSafeGitRefComponent(s) {
+  if (!s || s.length > 256) return false;
+  return /^[a-zA-Z0-9/._-]+$/.test(s);
+}
+
+function execGit(args) {
+  if (GIT_MOCK_JS) {
+    return execFileSync(process.execPath, [GIT_MOCK_JS, ...args], EXEC_OPTS);
+  }
+  return execFileSync(resolveGitBinary(), args, EXEC_OPTS);
+}
+
+// Protected branches
+const PROTECTED_BRANCHES = new Set(['main', 'master']);
+
+/**
+ * Get the current branch name
+ * @returns {string} Current git branch name
+ */
+function getCurrentBranch() {
+  try {
+    if (process.env.LEFTHOOK_GIT_BRANCH) {
+      const b = process.env.LEFTHOOK_GIT_BRANCH.trim();
+      if (!isSafeGitRefComponent(b)) {
+        console.error(`${RED}✗ Error: Invalid LEFTHOOK_GIT_BRANCH value${RESET}`);
+        process.exit(1);
+      }
+      return b;
+    }
+
+    const branch = execGit(['rev-parse', '--abbrev-ref', 'HEAD']).trim();
+    if (!isSafeGitRefComponent(branch)) {
+      console.error(`${RED}✗ Error: Invalid branch name from git${RESET}`);
+      process.exit(1);
+    }
+    return branch;
+  } catch (error) {
+    console.error(`${RED}✗ Error: Could not determine current branch${RESET}`);
+    console.error(`  ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Check if branch is protected
+ * @param {string} branch - Branch name to check
+ * @returns {boolean} True if branch is protected
+ */
+function isProtectedBranch(branch) {
+  return PROTECTED_BRANCHES.has(branch);
+}
+
+/**
+ * Main function
+ */
+function main() {
+  // Handle --help flag
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log('Branch Protection Script');
+    console.log('');
+    console.log('Prevents direct pushes to protected branches (main/master).');
+    console.log('');
+    console.log('Usage:');
+    console.log('  node scripts/branch-protection.js');
+    console.log('');
+    console.log('Exit codes:');
+    console.log('  0 - Push allowed');
+    console.log('  1 - Push blocked (protected branch)');
+    process.exit(0);
+  }
+
+  const currentBranch = getCurrentBranch();
+
+  if (isProtectedBranch(currentBranch)) {
+    // Allow beads-only commits (issue tracking metadata) to push directly
+    try {
+      let upstream;
+      try {
+        upstream = execGit(['rev-parse', '--abbrev-ref', '@{u}']).trim();
+      } catch (_e) {
+        upstream = `origin/${currentBranch}`;
+      }
+
+      if (!isSafeGitRefComponent(upstream)) {
+        throw new Error('unsafe upstream ref');
+      }
+
+      const output = execGit(['diff', '--name-only', `${upstream}..HEAD`]).trim();
+      const changedFiles = output.split('\n').filter(Boolean);
+
+      if (changedFiles.length === 0) {
+        console.error(`${YELLOW}Note: no changed files detected — nothing to bypass${RESET}`);
+      } else if (changedFiles.every(f => f.startsWith('.beads/'))) {
+        console.error(`${YELLOW}Beads-only push to '${currentBranch}' — allowed${RESET}`);
+        process.exit(0);
+      }
+    } catch (_e) {
+      console.error(`${YELLOW}Note: could not detect beads-only push (upstream ref missing?) — blocking by default${RESET}`);
+    }
+
+    console.error('');
+    console.error(`${RED}╔═══════════════════════════════════════════════════════════════╗${RESET}`);
+    console.error(`${RED}║                 ⚠  PUSH BLOCKED                              ║${RESET}`);
+    console.error(`${RED}╚═══════════════════════════════════════════════════════════════╝${RESET}`);
+    console.error('');
+    console.error(`${RED}✗ Direct pushes to '${currentBranch}' are forbidden.${RESET}`);
+    console.error('');
+    console.error(`${YELLOW}To push your changes:${RESET}`);
+    console.error(`  1. Create a feature branch: ${YELLOW}git checkout -b feat/my-feature${RESET}`);
+    console.error(`  2. Push to the feature branch: ${YELLOW}git push -u origin feat/my-feature${RESET}`);
+    console.error(`  3. Create a pull request for review`);
+    console.error('');
+    console.error(`${YELLOW}Emergency hook bypass is human-only and must not appear in agent logs.${RESET}`);
+    console.error(`  See ${YELLOW}CLAUDE.md${RESET} (Git Workflow) — AI agents must fix failing hooks, not bypass them.`);
+    console.error('');
+    process.exit(1);
+  }
+
+  // Push allowed
+  process.exit(0);
+}
+
+// Run main function
+main();