cleargate 0.2.0 → 0.3.0

package/dist/templates/cleargate-planning/.cleargate/scripts/close_sprint.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * close_sprint.mjs — Six-step sprint close pipeline
+ *
+ * Usage: node close_sprint.mjs <sprint-id> [--assume-ack]
+ *        node close_sprint.mjs <sprint-id> --report-body-stdin   (STORY-014-10)
+ *
+ * Steps:
+ *   1. Load and validate state.json via validateState
+ *   2. Refuse if any story state is not in TERMINAL_STATES (exit non-zero, list offenders)
+ *   3. Invoke prefill_report.mjs on all agent reports
+ *   4. Orchestrator spawns Reporter separately (script validates preconditions only)
+ *   5. On Reporter success + user ack (or --assume-ack flag), flip sprint_status -> "Completed"
+ *   6. Invoke suggest_improvements.mjs unconditionally
+ *
+ * Stdin fallback (STORY-014-10): when `--report-body-stdin` is passed, the script
+ * reads the full REPORT.md body from stdin and writes it atomically in lieu of
+ * waiting for a Reporter-produced file. Replaces the Step-4 gate; implies ack.
+ * Refuses empty stdin or pre-existing REPORT.md.
+ *
+ * Does NOT archive the sprint file (pending-sync -> archive stays human per EPIC-013 §4.5 step 7).
+ *
+ * Reuse: TERMINAL_STATES, VALID_STATES from constants.mjs
+ *        validateState from validate_state.mjs
+ *        atomicWrite pattern from update_state.mjs
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+import { TERMINAL_STATES } from './constants.mjs';
+import { validateState } from './validate_state.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const SCRIPTS_DIR = __dirname;
+
+function usage() {
+  process.stderr.write(
+    'Usage: node close_sprint.mjs <sprint-id> [--assume-ack | --report-body-stdin]\n' +
+    '\n' +
+    'Options:\n' +
+    '  --assume-ack           Skip user acknowledgement prompt (for automated tests)\n' +
+    '  --report-body-stdin    Read REPORT.md body from stdin; implies ack (STORY-014-10)\n'
+  );
+  process.exit(2);
+}
+
+/**
+ * Atomic write using tmp+rename pattern (per M1 update_state.mjs convention).
+ * @param {string} filePath
+ * @param {object} data
+ */
+function atomicWrite(filePath, data) {
+  const tmpFile = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpFile, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmpFile, filePath);
+}
+
+/**
+ * Atomic write for a string body. Separate from atomicWrite() so we don't
+ * accidentally JSON.stringify a markdown body.
+ * @param {string} filePath
+ * @param {string} body
+ */
+function atomicWriteString(filePath, body) {
+  const tmpFile = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpFile, body, 'utf8');
+  fs.renameSync(tmpFile, filePath);
+}
+
+/**
+ * Invoke a script via node (for .mjs scripts in the same directory).
+ * Throws on non-zero exit.
+ * @param {string} scriptName
+ * @param {string[]} scriptArgs
+ * @param {object} env
+ */
+function invokeScript(scriptName, scriptArgs, env) {
+  const scriptPath = path.join(SCRIPTS_DIR, scriptName);
+  if (!fs.existsSync(scriptPath)) {
+    throw new Error(`Script not found: ${scriptPath}`);
+  }
+  const argStr = scriptArgs.map(a => JSON.stringify(a)).join(' ');
+  const cmd = `node ${JSON.stringify(scriptPath)} ${argStr}`;
+  execSync(cmd, {
+    stdio: 'inherit',
+    env: Object.assign({}, process.env, env || {}),
+  });
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) usage();
+
+  const sprintId = args[0];
+  const reportBodyStdin = args.includes('--report-body-stdin');
+  const assumeAck = args.includes('--assume-ack') || reportBodyStdin;
+
+  const sprintDir = process.env.CLEARGATE_SPRINT_DIR
+    ? path.resolve(process.env.CLEARGATE_SPRINT_DIR)
+    : path.join(REPO_ROOT, '.cleargate', 'sprint-runs', sprintId);
+
+  if (!fs.existsSync(sprintDir)) {
+    process.stderr.write(`Error: sprint directory not found: ${sprintDir}\n`);
+    process.exit(1);
+  }
+
+  const stateFile = process.env.CLEARGATE_STATE_FILE
+    ? path.resolve(process.env.CLEARGATE_STATE_FILE)
+    : path.join(sprintDir, 'state.json');
+
+  // ── Step 1: Load and validate state.json ──────────────────────────────────
+  if (!fs.existsSync(stateFile)) {
+    process.stderr.write(
+      `Error: state.json not found at ${stateFile}\n` +
+      `Hint: run init_sprint.mjs ${sprintId} --stories <ids> first\n`
+    );
+    process.exit(1);
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`Error: failed to parse state.json: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const { valid, errors } = validateState(state);
+  if (!valid) {
+    process.stderr.write('Error: state.json validation failed:\n');
+    for (const e of errors) process.stderr.write(`  - ${e}\n`);
+    process.exit(1);
+  }
+
+  // ── Step 2: Refuse if any story not in TERMINAL_STATES ────────────────────
+  const nonTerminal = [];
+  for (const [storyId, story] of Object.entries(state.stories || {})) {
+    if (!TERMINAL_STATES.includes(story.state)) {
+      nonTerminal.push(`${storyId}: ${story.state} — not terminal`);
+    }
+  }
+
+  if (nonTerminal.length > 0) {
+    process.stderr.write('Error: sprint cannot close — non-terminal stories:\n');
+    for (const msg of nonTerminal) {
+      process.stderr.write(`  ${msg}\n`);
+    }
+    process.exit(1);
+  }
+
+  process.stdout.write(`Step 1-2 passed: all ${Object.keys(state.stories || {}).length} stories are terminal.\n`);
+
+  // ── Step 3: Invoke prefill_report.mjs ─────────────────────────────────────
+  process.stdout.write('Step 3: running prefill_report.mjs...\n');
+  try {
+    invokeScript('prefill_report.mjs', [sprintId], {
+      CLEARGATE_STATE_FILE: stateFile,
+      CLEARGATE_SPRINT_DIR: sprintDir,
+    });
+  } catch (err) {
+    process.stderr.write(`Error: prefill_report.mjs failed: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  // ── Step 4: Orchestrator spawns Reporter separately ───────────────────────
+  // This script only validates preconditions; it does NOT fork the Reporter agent.
+  process.stdout.write(
+    'Step 4: preconditions satisfied — orchestrator should now spawn the Reporter agent.\n' +
+    '        The Reporter writes REPORT.md using the sprint_report.md template.\n' +
+    `        Expected output: ${path.join(sprintDir, 'REPORT.md')}\n`
+  );
+
+  // Check if REPORT.md already exists (e.g., --assume-ack path in tests)
+  const reportFile = path.join(sprintDir, 'REPORT.md');
+
+  // ── Step 4.5 (STORY-014-10): --report-body-stdin fallback ────────────────
+  // Orchestrator pipes the Reporter's markdown body here when the Reporter's
+  // Write tool is blocked. Refuses empty stdin + pre-existing REPORT.md.
+  if (reportBodyStdin) {
+    if (fs.existsSync(reportFile)) {
+      process.stderr.write(
+        `Error: REPORT.md already exists at ${reportFile}\n` +
+        'Delete it or skip --report-body-stdin mode to use the primary Reporter-write path.\n'
+      );
+      process.exit(1);
+    }
+    let body;
+    try {
+      body = fs.readFileSync(0, 'utf8');
+    } catch (err) {
+      process.stderr.write(`Error: failed to read stdin: ${err.message}\n`);
+      process.exit(1);
+    }
+    if (!body || body.trim().length === 0) {
+      process.stderr.write('Error: empty report body — refusing to write.\n');
+      process.exit(1);
+    }
+    atomicWriteString(reportFile, body);
+    process.stdout.write(
+      `Step 4.5 (stdin mode): REPORT.md written (${body.length} bytes) at ${reportFile}\n`
+    );
+    // Fall through to Step 5 + 6 unconditionally — stdin mode implies ack.
+  } else if (!assumeAck) {
+    if (!fs.existsSync(reportFile)) {
+      process.stdout.write(
+        '\nWaiting for Reporter to produce REPORT.md...\n' +
+        'After Reporter succeeds, re-run with --assume-ack to complete the close.\n'
+      );
+      process.exit(0);
+    }
+    // In non-assume-ack mode with existing REPORT.md, prompt user
+    process.stdout.write(
+      `\nREPORT.md found at ${reportFile}\n` +
+      'Review the report, then confirm close by re-running with --assume-ack\n'
+    );
+    process.exit(0);
+  }
+
+  // ── Step 5: Flip sprint_status to "Completed" ────────────────────────────
+  process.stdout.write('Step 5: flipping sprint_status to "Completed"...\n');
+  const now = new Date().toISOString();
+  state.sprint_status = 'Completed';
+  state.last_action = `close_sprint: sprint ${sprintId} completed`;
+  state.updated_at = now;
+  atomicWrite(stateFile, state);
+  process.stdout.write(`sprint_status flipped to "Completed" at ${now}\n`);
+
+  // ── Step 6: Invoke suggest_improvements.mjs unconditionally ───────────────
+  process.stdout.write('Step 6: running suggest_improvements.mjs...\n');
+  try {
+    invokeScript('suggest_improvements.mjs', [sprintId], {
+      CLEARGATE_STATE_FILE: stateFile,
+      CLEARGATE_SPRINT_DIR: sprintDir,
+    });
+  } catch (err) {
+    // suggest_improvements failure is non-fatal — log but do not abort
+    process.stderr.write(`Warning: suggest_improvements.mjs failed: ${err.message}\n`);
+    process.stderr.write('Sprint is still marked Completed; improvement suggestions may be incomplete.\n');
+  }
+
+  process.stdout.write(`\nSprint ${sprintId} close pipeline complete.\n`);
+  process.stdout.write(`  state.json: sprint_status = Completed\n`);
+  process.stdout.write(`  improvement-suggestions.md: ${path.join(sprintDir, 'improvement-suggestions.md')}\n`);
+}
+
+main();

package/dist/templates/cleargate-planning/.cleargate/scripts/constants.mjs

@@ -0,0 +1,57 @@
+/**
+ * ClearGate Execution Phase v2 — Constants
+ *
+ * state.json v1 Schema (LOCKED — any future field change must bump schema_version):
+ *
+ * {
+ *   "schema_version": 1,          // integer, mandatory
+ *   "sprint_id": "S-NN",          // string
+ *   "execution_mode": "v1"|"v2",  // string
+ *   "sprint_status": "Active",    // string
+ *   "stories": {
+ *     "STORY-NNN-NN": {
+ *       "state": "Ready to Bounce",  // one of VALID_STATES
+ *       "qa_bounces": 0,             // integer 0..BOUNCE_CAP
+ *       "arch_bounces": 0,           // integer 0..BOUNCE_CAP
+ *       "worktree": null,            // string|null — path to worktree checkout
+ *       "updated_at": "<ISO-8601>",  // string
+ *       "notes": ""                  // string
+ *     }
+ *   },
+ *   "last_action": "<string>",    // human-readable last operation
+ *   "updated_at": "<ISO-8601>"    // string
+ * }
+ */
+
+export const SCHEMA_VERSION = 1;
+
+export const BOUNCE_CAP = 3;
+
+export const VALID_STATES = [
+  'Ready to Bounce',
+  'Bouncing',
+  'QA Passed',
+  'Architect Passed',
+  'Sprint Review',
+  'Done',
+  'Escalated',
+  'Parking Lot',
+];
+
+export const TERMINAL_STATES = ['Done', 'Escalated', 'Parking Lot'];
+
+/**
+ * Canonical state-machine transitions table.
+ * Key: current state. Value: array of allowed next states.
+ * Terminal states have empty arrays (no transitions out).
+ */
+export const STATE_TRANSITIONS = {
+  'Ready to Bounce':   ['Bouncing', 'Parking Lot'],
+  'Bouncing':          ['QA Passed', 'Ready to Bounce', 'Escalated', 'Parking Lot'],
+  'QA Passed':         ['Architect Passed', 'Ready to Bounce', 'Escalated', 'Parking Lot'],
+  'Architect Passed':  ['Sprint Review', 'Ready to Bounce', 'Escalated', 'Parking Lot'],
+  'Sprint Review':     ['Done', 'Ready to Bounce', 'Escalated', 'Parking Lot'],
+  'Done':              [],
+  'Escalated':         [],
+  'Parking Lot':       [],
+};

package/dist/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/dist/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/dist/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