cleargate 0.2.0 → 0.3.0

package/templates/cleargate-planning/.cleargate/scripts/file_surface_diff.sh

@@ -0,0 +1,320 @@
+#!/usr/bin/env bash
+# file_surface_diff.sh — Parse §3.1 of the active story file and compare
+# declared file paths against `git diff --cached --name-only`.
+#
+# Usage: file_surface_diff.sh [--story-file <path>] [--whitelist <path>] [--v1]
+#
+# Environment:
+#   SKIP_SURFACE_GATE=1    — bypass the gate (exit 0 always)
+#   CLEARGATE_REPO_ROOT    — override repo root (default: CWD git toplevel)
+#
+# Exit codes:
+#   0  — all staged files are on-surface or whitelisted, or v1 mode
+#   1  — off-surface files detected (v2 mode only)
+
+set -euo pipefail
+
+# ---- Configuration ---------------------------------------------------------
+
+REPO_ROOT="${CLEARGATE_REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+WHITELIST_DEFAULT="${REPO_ROOT}/.cleargate/scripts/surface-whitelist.txt"
+ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
+STATE_JSON_GLOB="${REPO_ROOT}/.cleargate/sprint-runs"
+
+# Parse args
+STORY_FILE=""
+WHITELIST_FILE="${WHITELIST_DEFAULT}"
+FORCE_V1=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --story-file) STORY_FILE="$2"; shift 2 ;;
+    --whitelist)  WHITELIST_FILE="$2"; shift 2 ;;
+    --v1)         FORCE_V1=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+# ---- Bypass check ----------------------------------------------------------
+
+if [[ "${SKIP_SURFACE_GATE:-0}" == "1" ]]; then
+  echo "[surface-gate] SKIP_SURFACE_GATE=1 — bypassing gate" >&2
+  exit 0
+fi
+
+# ---- Execution mode --------------------------------------------------------
+
+detect_execution_mode() {
+  local state_file="${STATE_JSON_GLOB}"
+  # Determine active sprint
+  local sprint_id=""
+  if [[ -f "${ACTIVE_SENTINEL}" ]]; then
+    sprint_id="$(tr -d '[:space:]' < "${ACTIVE_SENTINEL}")"
+  fi
+  if [[ -z "${sprint_id}" ]]; then
+    echo "v1"
+    return
+  fi
+  local state_json="${REPO_ROOT}/.cleargate/sprint-runs/${sprint_id}/state.json"
+  if [[ -f "${state_json}" ]]; then
+    local mode
+    mode="$(grep -oE '"execution_mode"\s*:\s*"v[12]"' "${state_json}" 2>/dev/null | grep -oE 'v[12]' | head -1 || true)"
+    if [[ -n "${mode}" ]]; then
+      echo "${mode}"
+      return
+    fi
+  fi
+  # Fallback: check sprint file frontmatter
+  local sprint_file
+  sprint_file="$(ls "${REPO_ROOT}/.cleargate/delivery/pending-sync/SPRINT-${sprint_id}_"*.md 2>/dev/null | head -1 || true)"
+  if [[ -z "${sprint_file}" ]]; then
+    sprint_file="$(ls "${REPO_ROOT}/.cleargate/delivery/archive/SPRINT-${sprint_id}_"*.md 2>/dev/null | head -1 || true)"
+  fi
+  if [[ -n "${sprint_file}" ]]; then
+    local mode
+    mode="$(grep -E '^execution_mode:' "${sprint_file}" 2>/dev/null | grep -oE 'v[12]' | head -1 || true)"
+    if [[ -n "${mode}" ]]; then
+      echo "${mode}"
+      return
+    fi
+  fi
+  echo "v1"
+}
+
+if [[ "${FORCE_V1}" == "1" ]]; then
+  EXECUTION_MODE="v1"
+else
+  EXECUTION_MODE="$(detect_execution_mode)"
+fi
+
+# ---- Resolve active story file ---------------------------------------------
+
+resolve_story_file() {
+  local sprint_id=""
+  if [[ -f "${ACTIVE_SENTINEL}" ]]; then
+    sprint_id="$(tr -d '[:space:]' < "${ACTIVE_SENTINEL}")"
+  fi
+  if [[ -z "${sprint_id}" ]]; then
+    echo ""
+    return
+  fi
+
+  local state_json="${REPO_ROOT}/.cleargate/sprint-runs/${sprint_id}/state.json"
+  if [[ ! -f "${state_json}" ]]; then
+    echo ""
+    return
+  fi
+
+  # Find first non-terminal story (In Progress or Ready)
+  local story_id=""
+  story_id="$(python3 -c "
+import json, sys
+data = json.load(open('${state_json}'))
+stories = data.get('stories', {})
+for sid, st in stories.items():
+    if st.get('state','') in ('In Progress','Ready','In Review'):
+        print(sid)
+        break
+" 2>/dev/null || true)"
+
+  if [[ -z "${story_id}" ]]; then
+    # Fallback: most recently updated
+    story_id="$(python3 -c "
+import json, sys
+data = json.load(open('${state_json}'))
+stories = data.get('stories', {})
+latest = max(stories.items(), key=lambda kv: kv[1].get('updated_at',''), default=(None,None))
+if latest[0]:
+    print(latest[0])
+" 2>/dev/null || true)"
+  fi
+
+  if [[ -z "${story_id}" ]]; then
+    echo ""
+    return
+  fi
+
+  # Convert e.g. STORY-014-01 -> find file
+  local story_num="${story_id#STORY-}"
+  local story_file
+  story_file="$(ls "${REPO_ROOT}/.cleargate/delivery/pending-sync/STORY-${story_num}_"*.md 2>/dev/null | head -1 || true)"
+  if [[ -z "${story_file}" ]]; then
+    story_file="$(ls "${REPO_ROOT}/.cleargate/delivery/archive/STORY-${story_num}_"*.md 2>/dev/null | head -1 || true)"
+  fi
+  echo "${story_file}"
+}
+
+if [[ -z "${STORY_FILE}" ]]; then
+  STORY_FILE="$(resolve_story_file)"
+fi
+
+if [[ -z "${STORY_FILE}" || ! -f "${STORY_FILE}" ]]; then
+  echo "[surface-gate] WARNING: No active story file found — skipping surface check" >&2
+  exit 0
+fi
+
+# ---- Parse §3.1 file surface table -----------------------------------------
+
+parse_surface_paths() {
+  local story_file="$1"
+  # Extract rows between "### 3.1" and the next "### " header.
+  # Table rows: | Item | Value |
+  # Only rows where Value cell looks like a path (contains . or /)
+  # Strip backticks. Split on ", " for multiple paths in one cell.
+  awk '
+    /^### 3\.1/ { in_section=1; next }
+    in_section && /^### / { in_section=0; next }
+    in_section && /^\|/ {
+      # Remove leading/trailing pipe, split into fields
+      line=$0
+      gsub(/^\||\|$/, "", line)
+      n=split(line, cols, "|")
+      if (n < 2) next
+      val=cols[2]
+      # Trim whitespace
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", val)
+      # Only process if value looks like a path (contains . or /)
+      if (val !~ /[.\/]/) next
+      # Strip backticks
+      gsub(/`/, "", val)
+      # Handle multiple paths separated by ", "
+      npaths=split(val, paths, ", ")
+      for (i=1; i<=npaths; i++) {
+        p=paths[i]
+        gsub(/^[[:space:]]+|[[:space:]]+$/, "", p)
+        if (p != "" && (p ~ /[.\/]/)) print p
+      }
+    }
+  ' "${story_file}"
+}
+
+# Collect declared paths into array (portable bash 3.2 compat — no mapfile)
+declared_paths=()
+while IFS= read -r p; do
+  declared_paths+=("$p")
+done < <(parse_surface_paths "${STORY_FILE}")
+
+if [[ ${#declared_paths[@]} -eq 0 ]]; then
+  echo "[surface-gate] WARNING: No file paths found in §3.1 of ${STORY_FILE} — skipping surface check" >&2
+  exit 0
+fi
+
+# ---- Get staged files -------------------------------------------------------
+
+staged_files=()
+while IFS= read -r f; do
+  staged_files+=("$f")
+done < <(git -C "${REPO_ROOT}" diff --cached --name-only 2>/dev/null || true)
+
+if [[ ${#staged_files[@]} -eq 0 ]]; then
+  # Nothing staged — nothing to check
+  exit 0
+fi
+
+# ---- Load whitelist ---------------------------------------------------------
+
+whitelist_patterns=()
+if [[ -f "${WHITELIST_FILE}" ]]; then
+  while IFS= read -r line; do
+    # Skip comments and blank lines
+    [[ -z "${line}" || "${line}" =~ ^# ]] && continue
+    whitelist_patterns+=("$line")
+  done < "${WHITELIST_FILE}"
+fi
+
+# ---- Helper: match file against whitelist -----------------------------------
+
+is_whitelisted() {
+  local file="$1"
+  local pattern
+  for pattern in "${whitelist_patterns[@]+"${whitelist_patterns[@]}"}"; do
+    # Use bash glob matching — convert ** to * for simple matching
+    # Try direct fnmatch with case
+    if [[ "${file}" == ${pattern} ]]; then
+      return 0
+    fi
+    # Try matching basename
+    local basename="${file##*/}"
+    local pat_base="${pattern##*/}"
+    if [[ "${basename}" == ${pat_base} && "${pat_base}" == "${basename}" ]]; then
+      : # need full path match
+    fi
+    # Try: if pattern has **, match any path segment
+    local simple_pat="${pattern//\*\*\//*/}"
+    if [[ "${file}" == ${simple_pat} ]]; then
+      return 0
+    fi
+    # Also: check if file path contains the pattern as suffix
+    if [[ "${file}" == *"${pattern}" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# ---- Helper: normalize path for comparison ----------------------------------
+
+normalize_path() {
+  local p="$1"
+  # Strip leading ./
+  p="${p#./}"
+  # If absolute path under REPO_ROOT, make it relative
+  if [[ "${p}" == "${REPO_ROOT}/"* ]]; then
+    p="${p#${REPO_ROOT}/}"
+  fi
+  echo "${p}"
+}
+
+# ---- Compare staged vs declared ---------------------------------------------
+
+off_surface=()
+for staged in "${staged_files[@]}"; do
+  staged_norm="$(normalize_path "${staged}")"
+
+  # Check whitelist first
+  if is_whitelisted "${staged_norm}"; then
+    continue
+  fi
+  # Also check absolute path against whitelist
+  if is_whitelisted "${REPO_ROOT}/${staged_norm}"; then
+    continue
+  fi
+
+  # Check against declared surface
+  found=0
+  for declared in "${declared_paths[@]+"${declared_paths[@]}"}"; do
+    declared_norm="$(normalize_path "${declared}")"
+    if [[ "${staged_norm}" == "${declared_norm}" ]]; then
+      found=1
+      break
+    fi
+  done
+
+  if [[ "${found}" == "0" ]]; then
+    off_surface+=("${staged_norm}")
+  fi
+done
+
+# ---- Report -----------------------------------------------------------------
+
+if [[ ${#off_surface[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+# Off-surface files detected
+if [[ "${EXECUTION_MODE}" == "v1" ]]; then
+  echo "[surface-gate] WARNING (v1 advisory): staged files outside declared §3.1 surface:" >&2
+  for f in "${off_surface[@]}"; do
+    echo "  off-surface: ${f}" >&2
+  done
+  echo "[surface-gate] v1 mode — not blocking commit. Switch to v2 to enforce." >&2
+  exit 0
+else
+  echo "[surface-gate] BLOCKED: staged files outside declared §3.1 surface:" >&2
+  for f in "${off_surface[@]}"; do
+    echo "  off-surface: ${f}" >&2
+  done
+  echo "[surface-gate] Commit blocked. Declare these files in §3.1 or open a CR:scope-change." >&2
+  echo "[surface-gate] Set SKIP_SURFACE_GATE=1 to bypass (v2 mode — use sparingly)." >&2
+  exit 1
+fi

package/templates/cleargate-planning/.cleargate/scripts/gate-checks.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": 1,
+  "qa": {
+    "typecheck": "npm run typecheck",
+    "debug_patterns": ["console.log", "console.debug", "debugger"],
+    "todo_patterns": ["TODO", "FIXME", "XXX"],
+    "test": "npm test"
+  },
+  "arch": {
+    "typecheck": "npm run typecheck",
+    "new_deps_check": true,
+    "stray_env_files": [".env", ".env.local", ".env.production"],
+    "file_count_report": true
+  }
+}

package/templates/cleargate-planning/.cleargate/scripts/init_gate_config.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# init_gate_config.sh — Idempotent seeder for gate-checks.json
+# Usage: init_gate_config.sh [--config-path <path>]
+# If gate-checks.json already exists, exits 0 without overwriting.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONFIG_PATH="${SCRIPT_DIR}/gate-checks.json"
+
+# Allow override via argument
+if [[ "${1:-}" == "--config-path" && -n "${2:-}" ]]; then
+  CONFIG_PATH="$2"
+fi
+
+if [[ -f "$CONFIG_PATH" ]]; then
+  echo "gate-checks.json already exists at ${CONFIG_PATH} — no-op." >&2
+  exit 0
+fi
+
+cat > "$CONFIG_PATH" << 'EOF'
+{
+  "schema_version": 1,
+  "qa": {
+    "typecheck": "npm run typecheck",
+    "debug_patterns": ["console.log", "console.debug", "debugger"],
+    "todo_patterns": ["TODO", "FIXME", "XXX"],
+    "test": "npm test"
+  },
+  "arch": {
+    "typecheck": "npm run typecheck",
+    "new_deps_check": true,
+    "stray_env_files": [".env", ".env.local", ".env.production"],
+    "file_count_report": true
+  }
+}
+EOF
+
+echo "gate-checks.json created at ${CONFIG_PATH}" >&2

package/templates/cleargate-planning/.cleargate/scripts/init_sprint.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * init_sprint.mjs — Initialize a sprint state.json
+ *
+ * Usage: node init_sprint.mjs <sprint-id> --stories ID1,ID2,... [--force]
+ *
+ * Creates .cleargate/sprint-runs/<sprint-id>/state.json with initial state
+ * "Ready to Bounce" for each story. Refuses if state.json already exists
+ * unless --force is passed.
+ *
+ * Under execution_mode: v2 (read from sprint frontmatter):
+ *   - Asserts all story files exist in pending-sync/ before writing state.json.
+ *   - On failure: prints missing list to stderr and exits 1 WITHOUT creating state.json.
+ *
+ * Under execution_mode: v1:
+ *   - Runs the same assertion but only warns on failure (does not block).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { SCHEMA_VERSION, VALID_STATES, TERMINAL_STATES } from './constants.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Resolve repo root: .cleargate/scripts/ -> ../../ (two levels up)
+// CLEARGATE_REPO_ROOT env var overrides for testing
+const REPO_ROOT = process.env.CLEARGATE_REPO_ROOT
+  ? path.resolve(process.env.CLEARGATE_REPO_ROOT)
+  : path.resolve(__dirname, '..', '..');
+
+function usage() {
+  process.stderr.write(
+    'Usage: node init_sprint.mjs <sprint-id> --stories ID1,ID2,... [--force]\n'
+  );
+  process.exit(2);
+}
+
+/**
+ * Read execution_mode from a sprint file's YAML frontmatter.
+ * Uses a single-field regex — does NOT hand-roll a full YAML parser.
+ * Returns 'v2' | 'v1' (defaults to 'v1' if field absent or unreadable).
+ */
+function readExecutionMode(sprintFilePath) {
+  let content;
+  try {
+    content = fs.readFileSync(sprintFilePath, 'utf8');
+  } catch {
+    return 'v1';
+  }
+  // Match frontmatter block
+  const fm = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return 'v1';
+  const modeMatch = fm[1].match(/^execution_mode:\s*["']?(v[12])/m);
+  if (!modeMatch) return 'v1';
+  return modeMatch[1];
+}
+
+/**
+ * Locate the sprint file in pending-sync/ or archive/ for the given sprint ID.
+ * Returns the absolute path if found, null otherwise.
+ */
+function findSprintFile(repoRoot, sprintId) {
+  const searchDirs = [
+    path.join(repoRoot, '.cleargate', 'delivery', 'pending-sync'),
+    path.join(repoRoot, '.cleargate', 'delivery', 'archive'),
+  ];
+  for (const dir of searchDirs) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    const prefix = `${sprintId}_`;
+    const match = entries.find(
+      (e) => (e === `${sprintId}.md` || e.startsWith(prefix)) && e.endsWith('.md')
+    );
+    if (match) return path.join(dir, match);
+  }
+  return null;
+}
+
+/**
+ * Run assert_story_files.mjs for the given sprint file.
+ * Returns { exitCode, stderr }.
+ */
+function runAssertStoryFiles(repoRoot, sprintFilePath) {
+  // Use __dirname to locate the sibling script (not CLEARGATE_REPO_ROOT, which is a test-isolation
+  // override that points to a tmpdir without scripts).
+  const assertScript = path.join(__dirname, 'assert_story_files.mjs');
+  const env = { ...process.env, CLEARGATE_REPO_ROOT: repoRoot };
+  const result = spawnSync(process.execPath, [assertScript, sprintFilePath], {
+    encoding: 'utf8',
+    env,
+  });
+  return {
+    exitCode: result.status ?? 1,
+    stderr: result.stderr || '',
+    stdout: result.stdout || '',
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  const sprintId = args[0];
+  if (!sprintId || sprintId.startsWith('--')) usage();
+
+  const storiesIdx = args.indexOf('--stories');
+  if (storiesIdx === -1 || !args[storiesIdx + 1]) usage();
+
+  const storyIds = args[storiesIdx + 1].split(',').map((s) => s.trim()).filter(Boolean);
+  if (storyIds.length === 0) {
+    process.stderr.write('Error: --stories requires at least one story ID\n');
+    process.exit(2);
+  }
+
+  const force = args.includes('--force');
+
+  const sprintDir = path.join(REPO_ROOT, '.cleargate', 'sprint-runs', sprintId);
+  const stateFile = path.join(sprintDir, 'state.json');
+
+  if (fs.existsSync(stateFile) && !force) {
+    process.stderr.write(
+      `state.json already exists at ${stateFile}; pass --force to overwrite\n`
+    );
+    process.exit(1);
+  }
+
+  // --- Read execution_mode from sprint frontmatter ---
+  const sprintFilePath = findSprintFile(REPO_ROOT, sprintId);
+  const executionMode = sprintFilePath ? readExecutionMode(sprintFilePath) : 'v1';
+
+  // --- Gate-2 story-file assertion ---
+  if (sprintFilePath) {
+    const { exitCode, stderr, stdout } = runAssertStoryFiles(REPO_ROOT, sprintFilePath);
+    if (exitCode !== 0) {
+      if (executionMode === 'v2') {
+        // Hard block: do not create state.json
+        process.stderr.write(stderr);
+        process.stderr.write(
+          `ERROR: v2 sprint init blocked — story files missing. Fix the above, then re-run init.\n`
+        );
+        process.exit(1);
+      } else {
+        // v1: warn only
+        process.stderr.write(
+          `WARN: missing story files: ${stderr.trim().split('\n').pop() || 'see above'}\n`
+        );
+      }
+    }
+  }
+
+  const now = new Date().toISOString();
+  const stories = {};
+  for (const id of storyIds) {
+    stories[id] = {
+      state: 'Ready to Bounce',
+      qa_bounces: 0,
+      arch_bounces: 0,
+      worktree: null,
+      updated_at: now,
+      notes: '',
+    };
+  }
+
+  const state = {
+    schema_version: SCHEMA_VERSION,
+    sprint_id: sprintId,
+    execution_mode: executionMode,
+    sprint_status: 'Active',
+    stories,
+    last_action: `Sprint ${sprintId} initialised`,
+    updated_at: now,
+  };
+
+  fs.mkdirSync(sprintDir, { recursive: true });
+
+  const tmpFile = `${stateFile}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmpFile, stateFile);
+
+  process.stdout.write(`Initialized state.json for sprint ${sprintId} with ${storyIds.length} stories\n`);
+}
+
+main();

package/templates/cleargate-planning/.cleargate/scripts/pre_gate_common.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# pre_gate_common.sh — Shared helpers for pre_gate_runner.sh
+# Sourced by pre_gate_runner.sh. Do NOT execute directly.
+# Handles Node+TS stacks only (no Python/Rust/Go/Java/Swift detectors).
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# read_config_field <field_path> <config_file>
+# Uses node -p to parse JSON and extract a field.
+# field_path: dot-separated path, e.g. "qa.typecheck"
+# ---------------------------------------------------------------------------
+read_config_field() {
+  local field_path="$1"
+  local config_file="$2"
+  node -p "
+    const c = JSON.parse(require('fs').readFileSync('${config_file}', 'utf8'));
+    const parts = '${field_path}'.split('.');
+    let v = c;
+    for (const p of parts) { v = v[p]; }
+    Array.isArray(v) ? JSON.stringify(v) : (v === undefined ? '' : String(v));
+  " 2>/dev/null || echo ""
+}
+
+# ---------------------------------------------------------------------------
+# get_modified_files <worktree_path>
+# Lists files modified in the current git index vs HEAD.
+# ---------------------------------------------------------------------------
+get_modified_files() {
+  local worktree="$1"
+  git -C "$worktree" diff --name-only HEAD 2>/dev/null || true
+  git -C "$worktree" diff --cached --name-only 2>/dev/null || true
+}
+
+# ---------------------------------------------------------------------------
+# get_staged_diff <worktree_path>
+# Returns unified diff of staged changes.
+# ---------------------------------------------------------------------------
+get_staged_diff() {
+  local worktree="$1"
+  git -C "$worktree" diff --cached 2>/dev/null || git -C "$worktree" diff HEAD 2>/dev/null || true
+}
+
+# ---------------------------------------------------------------------------
+# record_result <report_file> <check_name> <status> [details]
+# Appends one result line to the report.
+# status: PASS | FAIL | WARN | INFO
+# ---------------------------------------------------------------------------
+record_result() {
+  local report_file="$1"
+  local check_name="$2"
+  local status="$3"
+  local details="${4:-}"
+  echo "[${status}] ${check_name}: ${details}" >> "$report_file"
+}
+
+# ---------------------------------------------------------------------------
+# print_summary <report_file>
+# Prints count of PASS/FAIL/WARN lines from the report.
+# ---------------------------------------------------------------------------
+print_summary() {
+  local report_file="$1"
+  local pass_count fail_count warn_count
+  pass_count=$(grep -c '^\[PASS\]' "$report_file" 2>/dev/null || echo 0)
+  fail_count=$(grep -c '^\[FAIL\]' "$report_file" 2>/dev/null || echo 0)
+  warn_count=$(grep -c '^\[WARN\]' "$report_file" 2>/dev/null || echo 0)
+  echo "Summary: ${pass_count} passed, ${fail_count} failed, ${warn_count} warnings"
+}
+
+# ---------------------------------------------------------------------------
+# write_report <report_file> <mode> <worktree_path> <branch>
+# Writes the report header.
+# ---------------------------------------------------------------------------
+write_report_header() {
+  local report_file="$1"
+  local mode="$2"
+  local worktree="$3"
+  local branch="$4"
+  mkdir -p "$(dirname "$report_file")"
+  {
+    echo "# ClearGate Pre-Gate Scan Report"
+    echo "Mode: ${mode}"
+    echo "Worktree: ${worktree}"
+    echo "Branch: ${branch}"
+    echo "Timestamp: $(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+    echo "---"
+  } > "$report_file"
+}
+
+# ---------------------------------------------------------------------------
+# detect_stack <worktree_path>
+# Returns "node-ts" if package.json + tsconfig.json found, else "unknown".
+# Node+TS only — no Python/Rust/Go/Java/Swift detectors.
+# ---------------------------------------------------------------------------
+detect_stack() {
+  local worktree="$1"
+  if [[ -f "${worktree}/package.json" ]]; then
+    if [[ -f "${worktree}/tsconfig.json" ]]; then
+      echo "node-ts"
+    else
+      echo "node"
+    fi
+  else
+    echo "unknown"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# diff_package_json <worktree_path> <branch>
+# Prints new runtime deps (non-dev) introduced vs <branch>^.
+# Returns lines like: "new runtime dep: <name>"
+# ---------------------------------------------------------------------------
+diff_package_json() {
+  local worktree="$1"
+  local branch="$2"
+
+  # Get old package.json from branch parent (branch^ in the worktree's git)
+  local old_json
+  old_json=$(git -C "$worktree" show "${branch}^:package.json" 2>/dev/null || echo '{"dependencies":{}}')
+
+  local new_json
+  new_json=$(cat "${worktree}/package.json" 2>/dev/null || echo '{"dependencies":{}}')
+
+  # Extract dep keys using node
+  node -e "
+    const oldPkg = JSON.parse($(echo "$old_json" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>process.stdout.write(JSON.stringify(d)))"));
+    const newPkg = JSON.parse($(echo "$new_json" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>process.stdout.write(JSON.stringify(d)))"));
+    const oldDeps = Object.keys(oldPkg.dependencies || {});
+    const newDeps = Object.keys(newPkg.dependencies || {});
+    const added = newDeps.filter(d => !oldDeps.includes(d));
+    added.forEach(d => console.log('new runtime dep: ' + d));
+  " 2>/dev/null || true
+}