cleargate 0.2.0 → 0.3.0

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

package/dist/templates/cleargate-planning/.cleargate/scripts/pre_gate_runner.sh

@@ -0,0 +1,307 @@
+#!/usr/bin/env bash
+# pre_gate_runner.sh — Pre-gate scanner for QA and Architect agent spawning.
+# Usage: pre_gate_runner.sh qa|arch <worktree-path> <branch>
+#
+# Exit codes:
+#   0 — all checks pass → orchestrator proceeds to spawn QA/Architect
+#   1 — checks failed  → orchestrator returns story to Developer
+#   2 — scan couldn't run (missing config, missing worktree, bad args)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ---------------------------------------------------------------------------
+# Source shared helpers
+# ---------------------------------------------------------------------------
+# shellcheck source=pre_gate_common.sh
+source "${SCRIPT_DIR}/pre_gate_common.sh"
+
+# ---------------------------------------------------------------------------
+# Argument validation
+# ---------------------------------------------------------------------------
+if [[ $# -lt 3 ]]; then
+  echo "Usage: pre_gate_runner.sh qa|arch <worktree-path> <branch>" >&2
+  exit 2
+fi
+
+MODE="$1"
+WORKTREE="$2"
+BRANCH="$3"
+
+if [[ "$MODE" != "qa" && "$MODE" != "arch" ]]; then
+  echo "pre_gate_runner.sh: unknown mode '${MODE}' — must be 'qa' or 'arch'" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Validate worktree path
+# ---------------------------------------------------------------------------
+if [[ ! -d "$WORKTREE" ]]; then
+  echo "pre_gate_runner.sh: worktree path does not exist: ${WORKTREE}" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Locate gate-checks.json — auto-seed if missing
+# ---------------------------------------------------------------------------
+CONFIG_FILE="${SCRIPT_DIR}/gate-checks.json"
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "gate-checks.json not found at ${CONFIG_FILE}; running init_gate_config.sh …" >&2
+  bash "${SCRIPT_DIR}/init_gate_config.sh" || {
+    echo "pre_gate_runner.sh: init_gate_config.sh failed — cannot proceed" >&2
+    exit 2
+  }
+fi
+
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "pre_gate_runner.sh: gate-checks.json still missing after init — exit 2" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Prepare report file
+# ---------------------------------------------------------------------------
+REPORT_DIR="${WORKTREE}/.cleargate/reports"
+REPORT_FILE="${REPORT_DIR}/pre-${MODE}-scan.txt"
+write_report_header "$REPORT_FILE" "$MODE" "$WORKTREE" "$BRANCH"
+
+OVERALL_EXIT=0
+
+# ---------------------------------------------------------------------------
+# ── QA MODE ──────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------
+run_qa() {
+  # 1. Typecheck
+  local typecheck_cmd
+  typecheck_cmd="$(read_config_field "qa.typecheck" "$CONFIG_FILE")"
+  if [[ -n "$typecheck_cmd" && -f "${WORKTREE}/package.json" ]]; then
+    local tc_out tc_exit
+    tc_exit=0
+    tc_out=$(cd "$WORKTREE" && eval "$typecheck_cmd" 2>&1) || tc_exit=$?
+    if [[ $tc_exit -eq 0 ]]; then
+      record_result "$REPORT_FILE" "typecheck" "PASS" "$typecheck_cmd"
+    else
+      record_result "$REPORT_FILE" "typecheck" "FAIL" "$(echo "$tc_out" | head -5)"
+      OVERALL_EXIT=1
+    fi
+  else
+    record_result "$REPORT_FILE" "typecheck" "INFO" "skipped (no package.json or cmd empty)"
+  fi
+
+  # 2. Debug pattern grep (staged diff)
+  local debug_patterns_json
+  debug_patterns_json="$(read_config_field "qa.debug_patterns" "$CONFIG_FILE")"
+  local debug_patterns=()
+  while IFS= read -r _line; do
+    [[ -z "$_line" ]] || debug_patterns+=("$_line")
+  done < <(node -e "
+    try { JSON.parse('${debug_patterns_json}').forEach(p => console.log(p)); } catch(e) {}
+  " 2>/dev/null)
+
+  local staged_diff
+  staged_diff="$(get_staged_diff "$WORKTREE")"
+
+  if [[ ${#debug_patterns[@]} -gt 0 && -n "$staged_diff" ]]; then
+    local pattern_found=0
+    local found_details=""
+    for pattern in "${debug_patterns[@]}"; do
+      local matches
+      # Search all tracked files (not just diff) for the pattern since in test
+      # scenarios the file is committed but we want to detect it
+      matches="$(git -C "$WORKTREE" grep -n "$pattern" -- 2>/dev/null || true)"
+      if [[ -n "$matches" ]]; then
+        found_details+="$(echo "$matches" | head -5)"$'\n'
+        pattern_found=1
+      fi
+    done
+    if [[ $pattern_found -eq 1 ]]; then
+      record_result "$REPORT_FILE" "debug_patterns" "FAIL" "$(echo "$found_details" | head -10 | tr '\n' '|')"
+      echo "$found_details" >> "$REPORT_FILE"
+      OVERALL_EXIT=1
+    else
+      record_result "$REPORT_FILE" "debug_patterns" "PASS" "no debug statements found"
+    fi
+  else
+    # Fall back to grepping all files in worktree for debug patterns
+    local pattern_found=0
+    local found_details=""
+    for pattern in "${debug_patterns[@]:-}"; do
+      [[ -z "$pattern" ]] && continue
+      local matches
+      matches="$(grep -rn "$pattern" "${WORKTREE}" \
+        --include="*.js" --include="*.ts" --include="*.mjs" --include="*.cjs" \
+        --exclude-dir=".git" --exclude-dir="node_modules" \
+        2>/dev/null || true)"
+      if [[ -n "$matches" ]]; then
+        found_details+="$(echo "$matches" | head -5)"$'\n'
+        pattern_found=1
+      fi
+    done
+    if [[ $pattern_found -eq 1 ]]; then
+      record_result "$REPORT_FILE" "debug_patterns" "FAIL" "$(echo "$found_details" | head -10 | tr '\n' '|')"
+      echo "$found_details" >> "$REPORT_FILE"
+      OVERALL_EXIT=1
+    else
+      record_result "$REPORT_FILE" "debug_patterns" "PASS" "no debug statements found"
+    fi
+  fi
+
+  # 3. TODO/FIXME grep
+  local todo_patterns_json
+  todo_patterns_json="$(read_config_field "qa.todo_patterns" "$CONFIG_FILE")"
+  local todo_patterns=()
+  while IFS= read -r _line; do
+    [[ -z "$_line" ]] || todo_patterns+=("$_line")
+  done < <(node -e "
+    try { JSON.parse('${todo_patterns_json}').forEach(p => console.log(p)); } catch(e) {}
+  " 2>/dev/null)
+
+  local todo_found=0
+  local todo_details=""
+  for pattern in "${todo_patterns[@]:-}"; do
+    [[ -z "$pattern" ]] && continue
+    local matches
+    matches="$(grep -rn "$pattern" "${WORKTREE}" \
+      --include="*.js" --include="*.ts" --include="*.mjs" \
+      --exclude-dir=".git" --exclude-dir="node_modules" \
+      2>/dev/null || true)"
+    if [[ -n "$matches" ]]; then
+      todo_details+="$(echo "$matches" | head -3)"$'\n'
+      todo_found=1
+    fi
+  done
+  if [[ $todo_found -eq 1 ]]; then
+    record_result "$REPORT_FILE" "todo_patterns" "WARN" "$(echo "$todo_details" | head -5 | tr '\n' '|')"
+  else
+    record_result "$REPORT_FILE" "todo_patterns" "PASS" "no TODO/FIXME/XXX found"
+  fi
+
+  # 4. npm test
+  local test_cmd
+  test_cmd="$(read_config_field "qa.test" "$CONFIG_FILE")"
+  if [[ -n "$test_cmd" && -f "${WORKTREE}/package.json" ]]; then
+    local test_exit=0
+    cd "$WORKTREE" && eval "$test_cmd" > /dev/null 2>&1 || test_exit=$?
+    if [[ $test_exit -eq 0 ]]; then
+      record_result "$REPORT_FILE" "test" "PASS" "$test_cmd"
+    else
+      record_result "$REPORT_FILE" "test" "FAIL" "exit code ${test_exit}"
+      OVERALL_EXIT=1
+    fi
+  else
+    record_result "$REPORT_FILE" "test" "INFO" "skipped (no package.json or cmd empty)"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# ── ARCH MODE ─────────────────────────────────────────────────────────────
+# ---------------------------------------------------------------------------
+run_arch() {
+  # 1. Typecheck
+  local typecheck_cmd
+  typecheck_cmd="$(read_config_field "arch.typecheck" "$CONFIG_FILE")"
+  if [[ -n "$typecheck_cmd" && -f "${WORKTREE}/package.json" ]]; then
+    local tc_exit=0
+    cd "$WORKTREE" && eval "$typecheck_cmd" > /dev/null 2>&1 || tc_exit=$?
+    if [[ $tc_exit -eq 0 ]]; then
+      record_result "$REPORT_FILE" "typecheck" "PASS" "$typecheck_cmd"
+    else
+      record_result "$REPORT_FILE" "typecheck" "FAIL" "exit code ${tc_exit}"
+      OVERALL_EXIT=1
+    fi
+  else
+    record_result "$REPORT_FILE" "typecheck" "INFO" "skipped (no package.json or cmd empty)"
+  fi
+
+  # 2. New runtime deps vs branch^
+  local new_deps_check
+  new_deps_check="$(read_config_field "arch.new_deps_check" "$CONFIG_FILE")"
+  if [[ "$new_deps_check" == "true" && -f "${WORKTREE}/package.json" ]]; then
+    # Get old package.json from branch^
+    local old_json
+    old_json="$(git -C "$WORKTREE" show "${BRANCH}^:package.json" 2>/dev/null || echo '{}')"
+    local new_json
+    new_json="$(cat "${WORKTREE}/package.json")"
+
+    local new_deps
+    new_deps="$(node -e "
+      let oldPkg, newPkg;
+      try { oldPkg = JSON.parse(process.argv[1]); } catch(e) { oldPkg = {}; }
+      try { newPkg = JSON.parse(process.argv[2]); } catch(e) { newPkg = {}; }
+      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));
+    " "$old_json" "$new_json" 2>/dev/null || true)"
+
+    if [[ -n "$new_deps" ]]; then
+      record_result "$REPORT_FILE" "new_deps" "FAIL" "new runtime dependencies detected"
+      echo "$new_deps" >> "$REPORT_FILE"
+      OVERALL_EXIT=1
+    else
+      record_result "$REPORT_FILE" "new_deps" "PASS" "no new runtime deps"
+    fi
+  else
+    record_result "$REPORT_FILE" "new_deps" "INFO" "skipped"
+  fi
+
+  # 3. Stray .env* files
+  local stray_env_json
+  stray_env_json="$(read_config_field "arch.stray_env_files" "$CONFIG_FILE")"
+  local stray_patterns=()
+  while IFS= read -r _line; do
+    [[ -z "$_line" ]] || stray_patterns+=("$_line")
+  done < <(node -e "
+    try { JSON.parse('${stray_env_json}').forEach(p => console.log(p)); } catch(e) {}
+  " 2>/dev/null)
+
+  local stray_found=0
+  local stray_details=""
+  for pat in "${stray_patterns[@]:-}"; do
+    [[ -z "$pat" ]] && continue
+    if [[ -f "${WORKTREE}/${pat}" ]]; then
+      stray_details+="${pat}"$'\n'
+      stray_found=1
+    fi
+  done
+  if [[ $stray_found -eq 1 ]]; then
+    record_result "$REPORT_FILE" "stray_env_files" "FAIL" "$(echo "$stray_details" | tr '\n' ' ')"
+    OVERALL_EXIT=1
+  else
+    record_result "$REPORT_FILE" "stray_env_files" "PASS" "no stray .env files"
+  fi
+
+  # 4. File count per directory
+  local file_count_report
+  file_count_report="$(read_config_field "arch.file_count_report" "$CONFIG_FILE")"
+  if [[ "$file_count_report" == "true" ]]; then
+    record_result "$REPORT_FILE" "file_count_report" "INFO" "directory file counts:"
+    find "$WORKTREE" -maxdepth 2 -type d \
+      ! -path "*/.git*" ! -path "*/node_modules*" \
+      2>/dev/null | while read -r dir; do
+        local count
+        count=$(find "$dir" -maxdepth 1 -type f 2>/dev/null | wc -l | tr -d ' ')
+        echo "  ${dir}: ${count} files" >> "$REPORT_FILE"
+      done
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+case "$MODE" in
+  qa)   run_qa ;;
+  arch) run_arch ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Footer
+# ---------------------------------------------------------------------------
+{
+  echo "---"
+  print_summary "$REPORT_FILE"
+} >> "$REPORT_FILE"
+
+cat "$REPORT_FILE" >&2
+
+exit $OVERALL_EXIT