cleargate 0.2.1 → 0.4.0

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

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

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * prefill_report.mjs — Backfill missing YAML frontmatter fields in agent reports
+ *
+ * Usage: node prefill_report.mjs <sprint-id>
+ *   or:  CLEARGATE_STATE_FILE=... node prefill_report.mjs <sprint-id>
+ *
+ * Reads:
+ *   - state.json (v1 schema) for story metadata (bounce counts, states)
+ *   - token-ledger.jsonl for commit_sha attribution
+ *   - All STORY-<id>-dev.md and STORY-<id>-qa.md in sprint-runs/<id>/reports/
+ *
+ * Backfills missing deterministic YAML frontmatter fields:
+ *   - story_id, sprint_id, commit_sha, qa_bounces, arch_bounces
+ *
+ * Atomic write (tmp+rename per M1 pattern). Idempotent: re-run on a
+ * fully-prefilled report is a no-op.
+ *
+ * SubagentStop hook attribution note (FLASHCARD 2026-04-19 #reporting #hooks #ledger):
+ * Ledger rows may lack story_id; those are attributed to "unassigned" bucket
+ * and do not prevent backfill of reports that can be matched by filename.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateState } from './validate_state.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * Parse a minimal YAML frontmatter block from markdown content.
+ * Returns { frontmatter: string, body: string, fields: object }
+ * Only parses simple key: value pairs (no nested objects).
+ * @param {string} content
+ * @returns {{ hasFrontmatter: boolean, frontmatter: string, body: string, fields: object }}
+ */
+function parseFrontmatter(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!fmMatch) {
+    return { hasFrontmatter: false, frontmatter: '', body: content, fields: {} };
+  }
+  const rawFm = fmMatch[1];
+  const body = fmMatch[2];
+  const fields = {};
+  for (const line of rawFm.split('\n')) {
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/);
+    if (m) {
+      const key = m[1];
+      let val = m[2].trim();
+      // Strip surrounding quotes
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      // Parse nulls
+      if (val === 'null' || val === '') val = null;
+      fields[key] = val;
+    }
+  }
+  return { hasFrontmatter: true, frontmatter: rawFm, body, fields };
+}
+
+/**
+ * Serialize fields back to YAML frontmatter lines (simple key: value).
+ * @param {object} fields
+ * @param {string} originalFrontmatter - preserve original order and formatting
+ * @returns {string}
+ */
+function serializeFrontmatter(fields, originalFrontmatter) {
+  const lines = originalFrontmatter.split('\n');
+  const updatedLines = [];
+  const processedKeys = new Set();
+
+  for (const line of lines) {
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*):/);
+    if (m) {
+      const key = m[1];
+      processedKeys.add(key);
+      if (key in fields && fields[key] !== null && fields[key] !== undefined) {
+        const val = fields[key];
+        updatedLines.push(`${key}: "${val}"`);
+      } else {
+        updatedLines.push(line);
+      }
+    } else {
+      updatedLines.push(line);
+    }
+  }
+
+  // Append any new fields not in the original
+  for (const [key, val] of Object.entries(fields)) {
+    if (!processedKeys.has(key) && val !== null && val !== undefined) {
+      updatedLines.push(`${key}: "${val}"`);
+    }
+  }
+
+  return updatedLines.join('\n');
+}
+
+/**
+ * Atomic write to a file using tmp+rename pattern.
+ * @param {string} filePath
+ * @param {string} content
+ */
+function atomicWrite(filePath, content) {
+  const tmpFile = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpFile, content, 'utf8');
+  fs.renameSync(tmpFile, filePath);
+}
+
+/**
+ * Parse JSONL file, returning an array of parsed objects.
+ * Tolerates malformed lines (skips them with a warning).
+ * @param {string} filePath
+ * @returns {object[]}
+ */
+function parseJsonl(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(l => l.trim());
+  const results = [];
+  for (const line of lines) {
+    try {
+      results.push(JSON.parse(line));
+    } catch {
+      process.stderr.write(`Warning: skipping malformed JSONL line: ${line.slice(0, 80)}\n`);
+    }
+  }
+  return results;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 1) {
+    process.stderr.write('Usage: node prefill_report.mjs <sprint-id>\n');
+    process.exit(2);
+  }
+
+  const sprintId = args[0];
+  const sprintRunsDir = path.join(REPO_ROOT, '.cleargate', 'sprint-runs');
+  const sprintDir = process.env.CLEARGATE_SPRINT_DIR
+    ? path.resolve(process.env.CLEARGATE_SPRINT_DIR)
+    : path.join(sprintRunsDir, sprintId);
+
+  if (!fs.existsSync(sprintDir)) {
+    process.stderr.write(`Error: sprint directory not found: ${sprintDir}\n`);
+    process.exit(1);
+  }
+
+  // Load state.json
+  const stateFile = process.env.CLEARGATE_STATE_FILE
+    ? path.resolve(process.env.CLEARGATE_STATE_FILE)
+    : path.join(sprintDir, 'state.json');
+
+  if (!fs.existsSync(stateFile)) {
+    process.stderr.write(`Error: state.json not found at ${stateFile}\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 is invalid:\n');
+    for (const e of errors) process.stderr.write(`  - ${e}\n`);
+    process.exit(1);
+  }
+
+  // Load token-ledger.jsonl — build a map of story_id -> commit_sha
+  // Rows lacking story_id are attributed to 'unassigned' (per FLASHCARD 2026-04-19 #reporting #hooks #ledger)
+  const ledgerFile = path.join(sprintDir, 'token-ledger.jsonl');
+  const ledgerRows = parseJsonl(ledgerFile);
+  const storyCommits = {};
+  for (const row of ledgerRows) {
+    const sid = row.story_id || 'unassigned';
+    if (sid !== 'unassigned' && row.commit_sha) {
+      storyCommits[sid] = row.commit_sha;
+    }
+  }
+
+  // Find all agent reports in the sprint dir (reports/ subdirectory + top level)
+  const reportsDir = path.join(sprintDir, 'reports');
+  const reportFiles = [];
+
+  // Check reports subdirectory
+  if (fs.existsSync(reportsDir)) {
+    for (const f of fs.readdirSync(reportsDir)) {
+      if (/^STORY-.*-(dev|qa)\.md$/.test(f)) {
+        reportFiles.push(path.join(reportsDir, f));
+      }
+    }
+  }
+
+  // Check sprint dir directly
+  for (const f of fs.readdirSync(sprintDir)) {
+    if (/^STORY-.*-(dev|qa)\.md$/.test(f)) {
+      reportFiles.push(path.join(sprintDir, f));
+    }
+  }
+
+  if (reportFiles.length === 0) {
+    process.stdout.write(`No agent reports found in ${sprintDir}; nothing to prefill.\n`);
+    process.exit(0);
+  }
+
+  let prefilled = 0;
+  let noops = 0;
+
+  for (const reportPath of reportFiles) {
+    const filename = path.basename(reportPath);
+    // Extract story_id from filename: STORY-NNN-NN-dev.md or STORY-NNN-NN-qa.md
+    const storyMatch = filename.match(/^(STORY-\d+-\d+)-(dev|qa)\.md$/);
+    if (!storyMatch) continue;
+
+    const storyId = storyMatch[1];
+    const content = fs.readFileSync(reportPath, 'utf8');
+    const { hasFrontmatter, frontmatter, body, fields } = parseFrontmatter(content);
+
+    if (!hasFrontmatter) {
+      process.stdout.write(`Skipping ${filename}: no frontmatter found.\n`);
+      continue;
+    }
+
+    // Determine what needs backfill
+    const updates = {};
+    let needsUpdate = false;
+
+    if (!fields.story_id) {
+      updates.story_id = storyId;
+      needsUpdate = true;
+    }
+
+    if (!fields.sprint_id) {
+      updates.sprint_id = state.sprint_id || sprintId;
+      needsUpdate = true;
+    }
+
+    if (!fields.commit_sha && storyCommits[storyId]) {
+      updates.commit_sha = storyCommits[storyId];
+      needsUpdate = true;
+    }
+
+    const storyEntry = state.stories && state.stories[storyId];
+    if (storyEntry) {
+      if (fields.qa_bounces === null || fields.qa_bounces === undefined) {
+        updates.qa_bounces = String(storyEntry.qa_bounces || 0);
+        needsUpdate = true;
+      }
+      if (fields.arch_bounces === null || fields.arch_bounces === undefined) {
+        updates.arch_bounces = String(storyEntry.arch_bounces || 0);
+        needsUpdate = true;
+      }
+    }
+
+    if (!needsUpdate) {
+      noops++;
+      process.stdout.write(`No-op: ${filename} already fully prefilled.\n`);
+      continue;
+    }
+
+    // Merge updates into existing fields
+    const mergedFields = Object.assign({}, fields, updates);
+    const newFrontmatter = serializeFrontmatter(mergedFields, frontmatter);
+    const newContent = `---\n${newFrontmatter}\n---\n${body}`;
+
+    atomicWrite(reportPath, newContent);
+    prefilled++;
+    process.stdout.write(`Prefilled ${filename}: ${Object.keys(updates).join(', ')}\n`);
+  }
+
+  process.stdout.write(`\nDone. prefilled=${prefilled} noops=${noops}\n`);
+}
+
+main();