cleargate 0.2.0 → 0.3.0

package/dist/templates/cleargate-planning/.cleargate/scripts/test/test_file_surface.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# test_file_surface.sh — Gherkin-style tests for file_surface_diff.sh
+# Tests all 4 scenarios from STORY-014-01 §2.1
+#
+# Usage: bash .cleargate/scripts/test/test_file_surface.sh
+# Exit: 0 if all pass, 1 if any fail
+
+set -euo pipefail
+
+# Navigate up 3 levels: test/ -> scripts/ -> .cleargate/ -> repo-root/
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+SCRIPT="${REPO_ROOT}/.cleargate/scripts/file_surface_diff.sh"
+PASS=0
+FAIL=0
+TOTAL=0
+
+pass() { echo "  PASS: $1"; PASS=$((PASS+1)); TOTAL=$((TOTAL+1)); }
+fail() { echo "  FAIL: $1 --- $2"; FAIL=$((FAIL+1)); TOTAL=$((TOTAL+1)); }
+
+echo "REPO_ROOT: ${REPO_ROOT}"
+echo "SCRIPT: ${SCRIPT}"
+if [[ ! -f "${SCRIPT}" ]]; then
+  echo "ERROR: file_surface_diff.sh not found at ${SCRIPT}"
+  exit 1
+fi
+
+# ============================================================================
+# Setup helpers
+# ============================================================================
+
+setup_git_repo() {
+  local dir="$1"
+  git init -q "${dir}"
+  git -C "${dir}" config user.email "test@test.com"
+  git -C "${dir}" config user.name "Test"
+  git -C "${dir}" commit -q --allow-empty -m "init"
+}
+
+create_story_file() {
+  local dir="$1"
+  shift
+  # remaining args are file paths to declare in §3.1
+  mkdir -p "${dir}/.cleargate/delivery/pending-sync"
+  local story="${dir}/.cleargate/delivery/pending-sync/STORY-014-01_Test.md"
+  {
+    echo "---"
+    echo "story_id: STORY-014-01"
+    echo "---"
+    echo ""
+    echo "# Test Story"
+    echo ""
+    echo "## 3. Implementation Guide"
+    echo ""
+    echo "### 3.1 Context & Files"
+    echo ""
+    echo "| Item | Value |"
+    echo "|---|---|"
+    for f in "$@"; do
+      echo "| New script | \`${f}\` |"
+    done
+    echo ""
+    echo "### 3.2 Technical Logic"
+    echo "test"
+  } > "${story}"
+}
+
+create_sprint_state() {
+  local dir="$1"
+  local mode="${2:-v2}"
+  mkdir -p "${dir}/.cleargate/sprint-runs/SPRINT-10"
+  echo "SPRINT-10" > "${dir}/.cleargate/sprint-runs/.active"
+  echo "{\"execution_mode\":\"${mode}\",\"stories\":{\"STORY-014-01\":{\"state\":\"In Progress\",\"updated_at\":\"2026-04-21T12:00:00Z\"}}}" > "${dir}/.cleargate/sprint-runs/SPRINT-10/state.json"
+}
+
+# ============================================================================
+# Scenario 1: Gate catches off-surface edit
+# ============================================================================
+
+echo ""
+echo "Scenario 1: Gate catches off-surface edit"
+
+TMPDIR1="$(mktemp -d)"
+setup_git_repo "${TMPDIR1}"
+create_story_file "${TMPDIR1}" "hello.mjs" "README.md"
+create_sprint_state "${TMPDIR1}" "v2"
+
+touch "${TMPDIR1}/hello.mjs" "${TMPDIR1}/README.md" "${TMPDIR1}/unrelated.txt"
+git -C "${TMPDIR1}" add hello.mjs README.md unrelated.txt
+
+EXIT_CODE=0
+STDERR_OUT="$(CLEARGATE_REPO_ROOT="${TMPDIR1}" bash "${SCRIPT}" 2>&1 >/dev/null)" || EXIT_CODE=$?
+
+if [[ "${EXIT_CODE}" -ne 0 ]]; then
+  pass "exit code is non-zero"
+else
+  fail "exit code is non-zero" "got exit 0"
+fi
+
+if echo "${STDERR_OUT}" | grep -q "unrelated.txt"; then
+  pass "stderr lists unrelated.txt as off-surface"
+else
+  fail "stderr lists unrelated.txt as off-surface" "stderr was: ${STDERR_OUT}"
+fi
+
+rm -rf "${TMPDIR1}"
+
+# ============================================================================
+# Scenario 2: Gate passes when staged files match surface
+# ============================================================================
+
+echo ""
+echo "Scenario 2: Gate passes when staged files match surface"
+
+TMPDIR2="$(mktemp -d)"
+setup_git_repo "${TMPDIR2}"
+create_story_file "${TMPDIR2}" "hello.mjs" "README.md"
+create_sprint_state "${TMPDIR2}" "v2"
+
+touch "${TMPDIR2}/hello.mjs" "${TMPDIR2}/README.md"
+git -C "${TMPDIR2}" add hello.mjs README.md
+
+EXIT_CODE=0
+CLEARGATE_REPO_ROOT="${TMPDIR2}" bash "${SCRIPT}" 2>/dev/null || EXIT_CODE=$?
+
+if [[ "${EXIT_CODE}" -eq 0 ]]; then
+  pass "exit code is 0"
+else
+  fail "exit code is 0" "got exit ${EXIT_CODE}"
+fi
+
+rm -rf "${TMPDIR2}"
+
+# ============================================================================
+# Scenario 3: Whitelist admits generated files
+# ============================================================================
+
+echo ""
+echo "Scenario 3: Whitelist admits generated files"
+
+TMPDIR3="$(mktemp -d)"
+setup_git_repo "${TMPDIR3}"
+create_story_file "${TMPDIR3}" "hello.mjs"
+create_sprint_state "${TMPDIR3}" "v2"
+
+mkdir -p "${TMPDIR3}/.cleargate/scripts"
+{
+  echo "cleargate-planning/MANIFEST.json"
+  echo ".cleargate/hook-log/*"
+} > "${TMPDIR3}/.cleargate/scripts/surface-whitelist.txt"
+
+touch "${TMPDIR3}/hello.mjs"
+mkdir -p "${TMPDIR3}/cleargate-planning"
+touch "${TMPDIR3}/cleargate-planning/MANIFEST.json"
+git -C "${TMPDIR3}" add hello.mjs cleargate-planning/MANIFEST.json
+
+EXIT_CODE=0
+CLEARGATE_REPO_ROOT="${TMPDIR3}" bash "${SCRIPT}" 2>/dev/null || EXIT_CODE=$?
+
+if [[ "${EXIT_CODE}" -eq 0 ]]; then
+  pass "MANIFEST.json not flagged (whitelisted)"
+else
+  fail "MANIFEST.json not flagged (whitelisted)" "got exit ${EXIT_CODE}"
+fi
+
+rm -rf "${TMPDIR3}"
+
+# ============================================================================
+# Scenario 4: v1 mode is advisory
+# ============================================================================
+
+echo ""
+echo "Scenario 4: v1 mode is advisory"
+
+TMPDIR4="$(mktemp -d)"
+setup_git_repo "${TMPDIR4}"
+create_story_file "${TMPDIR4}" "hello.mjs"
+create_sprint_state "${TMPDIR4}" "v1"
+
+touch "${TMPDIR4}/hello.mjs" "${TMPDIR4}/unrelated.txt"
+git -C "${TMPDIR4}" add hello.mjs unrelated.txt
+
+EXIT_CODE=0
+STDERR_OUT="$(CLEARGATE_REPO_ROOT="${TMPDIR4}" bash "${SCRIPT}" 2>&1 >/dev/null)" || EXIT_CODE=$?
+
+if [[ "${EXIT_CODE}" -eq 0 ]]; then
+  pass "v1 mode exits 0 (advisory)"
+else
+  fail "v1 mode exits 0" "got exit ${EXIT_CODE}"
+fi
+
+if echo "${STDERR_OUT}" | grep -qi "warning"; then
+  pass "v1 mode prints warning"
+else
+  fail "v1 mode prints warning" "stderr was: ${STDERR_OUT}"
+fi
+
+rm -rf "${TMPDIR4}"
+
+# ============================================================================
+# Summary
+# ============================================================================
+
+echo ""
+echo "Results: ${PASS}/${TOTAL} passed, ${FAIL} failed"
+
+if [[ "${FAIL}" -gt 0 ]]; then
+  exit 1
+fi
+exit 0

package/dist/templates/cleargate-planning/.cleargate/scripts/test/test_flashcard_gate.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# test_flashcard_gate.sh — STORY-013-06: Immediate Flashcard Hard-Gate
+# Gherkin scenario: "Gate blocks next worktree creation until flashcards processed"
+#
+# Strategy: grep-based. Creates a synthetic dev-report fixture with
+# flashcards_flagged, simulates a mock worktree-creation step, and asserts
+# the gate contract documented in protocol §18 and the agent output-shape
+# blocks in developer.md + qa.md.
+#
+# Usage: bash .cleargate/scripts/test/test_flashcard_gate.sh
+# Exit: 0 if all assertions pass, 1 on first failure.
+
+set -euo pipefail
+
+REPO_ROOT="${CLEARGATE_REPO_ROOT:-$(cd "$(dirname "$0")/../../.." && pwd)}"
+PASS=0
+FAIL=0
+
+pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+# ---------------------------------------------------------------------------
+# Scenario: Gate blocks next worktree creation until flashcards processed
+# ---------------------------------------------------------------------------
+# §2.1 Gherkin from STORY-013-06:
+#   Given STORY-014-05 has just merged into sprint/S-XX
+#   And STORY-014-05-dev.md has flashcards_flagged: [...]
+#   When the orchestrator attempts to create .worktrees/STORY-014-06/
+#   Then the gate presents each flagged flashcard to the user for approval
+#   And upon approval each card is appended to .cleargate/FLASHCARD.md
+#   And only then does worktree creation proceed
+#
+# This script validates the contract (protocol §18 + output-shape fields)
+# that makes the scenario enforceable. The gate logic itself is orchestrator-
+# out-of-band (v1: informational; v2: mandatory). The test therefore checks:
+#   (a) developer.md output-shape contains flashcards_flagged field
+#   (b) qa.md output-shape contains flashcards_flagged field
+#   (c) protocol.md §18 exists with the correct heading
+#   (d) §18 specifies the approve/reject processing rule
+#   (e) §18 specifies the worktree creation gate
+#   (f) live vs mirror diff is empty for all three files
+
+DEV_MD="$REPO_ROOT/.claude/agents/developer.md"
+QA_MD="$REPO_ROOT/.claude/agents/qa.md"
+PROTOCOL_MD="$REPO_ROOT/.cleargate/knowledge/cleargate-protocol.md"
+
+PLANNING_DEV_MD="$REPO_ROOT/cleargate-planning/.claude/agents/developer.md"
+PLANNING_QA_MD="$REPO_ROOT/cleargate-planning/.claude/agents/qa.md"
+PLANNING_PROTOCOL_MD="$REPO_ROOT/cleargate-planning/.cleargate/knowledge/cleargate-protocol.md"
+
+# (a) developer.md has flashcards_flagged in output-shape block
+if grep -q "flashcards_flagged:" "$DEV_MD"; then
+  pass "developer.md output-shape contains flashcards_flagged field"
+else
+  fail "developer.md missing flashcards_flagged field in output-shape"
+fi
+
+# (b) qa.md has flashcards_flagged in output-shape block
+if grep -q "flashcards_flagged:" "$QA_MD"; then
+  pass "qa.md output-shape contains flashcards_flagged field"
+else
+  fail "qa.md missing flashcards_flagged field in output-shape"
+fi
+
+# (c) protocol.md §18 heading exists
+if grep -q "^## 18. Immediate Flashcard Gate (v2)" "$PROTOCOL_MD"; then
+  pass "protocol.md contains ## 18. Immediate Flashcard Gate (v2)"
+else
+  fail "protocol.md missing ## 18. Immediate Flashcard Gate (v2)"
+fi
+
+# (d) §18 specifies approve + reject processing
+if grep -q "Approve" "$PROTOCOL_MD" && grep -q "Reject" "$PROTOCOL_MD"; then
+  pass "protocol §18 documents Approve/Reject processing rule"
+else
+  fail "protocol §18 missing Approve/Reject processing rule"
+fi
+
+# (e) §18 specifies the worktree creation gate
+if grep -q "Worktree creation gate\|worktree creation gate\|MUST NOT.*worktree\|worktree.*MUST NOT" "$PROTOCOL_MD"; then
+  pass "protocol §18 documents worktree creation gate"
+else
+  fail "protocol §18 missing worktree creation gate rule"
+fi
+
+# (f) qa.md says QA list is additive to Developer's
+if grep -q "additive" "$QA_MD"; then
+  pass "qa.md notes that flashcards_flagged list is additive to Developer's"
+else
+  fail "qa.md missing note that flashcards_flagged is additive"
+fi
+
+# (g) developer.md references protocol §18
+if grep -q "protocol §18\|§18" "$DEV_MD"; then
+  pass "developer.md references protocol §18"
+else
+  fail "developer.md does not reference protocol §18"
+fi
+
+# (h) qa.md references protocol §18
+if grep -q "protocol §18\|§18" "$QA_MD"; then
+  pass "qa.md references protocol §18"
+else
+  fail "qa.md does not reference protocol §18"
+fi
+
+# (i) three-surface diff: live developer.md vs mirror
+if diff -q "$DEV_MD" "$PLANNING_DEV_MD" > /dev/null 2>&1; then
+  pass "developer.md live vs mirror diff is empty"
+else
+  fail "developer.md live vs mirror diff is NOT empty"
+fi
+
+# (j) three-surface diff: live qa.md vs mirror
+if diff -q "$QA_MD" "$PLANNING_QA_MD" > /dev/null 2>&1; then
+  pass "qa.md live vs mirror diff is empty"
+else
+  fail "qa.md live vs mirror diff is NOT empty"
+fi
+
+# (k) three-surface diff: live protocol.md vs mirror
+if diff -q "$PROTOCOL_MD" "$PLANNING_PROTOCOL_MD" > /dev/null 2>&1; then
+  pass "cleargate-protocol.md live vs mirror diff is empty"
+else
+  fail "cleargate-protocol.md live vs mirror diff is NOT empty"
+fi
+
+# (l) synthetic fixture: dev report with flashcards_flagged triggers gate
+# Simulate: write a temp dev report with flashcards_flagged, grep for it
+TMPDIR_FIXTURE="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_FIXTURE"' EXIT
+
+cat > "$TMPDIR_FIXTURE/STORY-014-05-dev.md" << 'FIXTURE'
+STORY: STORY-014-05
+STATUS: done
+COMMIT: abc1234
+TYPECHECK: pass
+TESTS: 5 passed, 0 failed
+FILES_CHANGED: src/foo.ts
+NOTES: all green
+flashcards_flagged:
+  - "2026-04-22 · #test-harness · vitest fake-timers conflict with worker.spawn"
+FIXTURE
+
+# Assert the fixture has the flashcard entry
+if grep -q "flashcards_flagged:" "$TMPDIR_FIXTURE/STORY-014-05-dev.md"; then
+  pass "synthetic dev-report fixture contains flashcards_flagged field"
+else
+  fail "synthetic dev-report fixture missing flashcards_flagged field"
+fi
+
+# Assert extraction of the flagged card matches the FLASHCARD.md format
+EXTRACTED=$(grep -A1 "flashcards_flagged:" "$TMPDIR_FIXTURE/STORY-014-05-dev.md" | tail -1 | sed 's/^[[:space:]]*- "//' | sed 's/"$//')
+if echo "$EXTRACTED" | grep -qE "^[0-9]{4}-[0-9]{2}-[0-9]{2} · #[a-z-]+ · .+"; then
+  pass "extracted flashcard matches YYYY-MM-DD · #tag · lesson format"
+else
+  fail "extracted flashcard does NOT match expected format: '$EXTRACTED'"
+fi
+
+# Mock worktree guard: confirm the gate would block by checking the field is non-empty
+FLAGGED_COUNT=$(grep -c "  - " "$TMPDIR_FIXTURE/STORY-014-05-dev.md" || true)
+if [ "$FLAGGED_COUNT" -gt 0 ]; then
+  pass "gate detects non-empty flashcards_flagged — worktree creation would be blocked"
+else
+  fail "gate failed to detect non-empty flashcards_flagged list"
+fi
+
+# Mock approval: append to a temp FLASHCARD.md and confirm it was written
+TEMP_FLASHCARD="$TMPDIR_FIXTURE/FLASHCARD.md"
+echo "# ClearGate Flashcards" > "$TEMP_FLASHCARD"
+echo "" >> "$TEMP_FLASHCARD"
+echo "$EXTRACTED" >> "$TEMP_FLASHCARD"
+
+if grep -q "vitest fake-timers conflict" "$TEMP_FLASHCARD"; then
+  pass "approved flashcard appended to FLASHCARD.md mock"
+else
+  fail "approved flashcard NOT found in FLASHCARD.md mock"
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+TOTAL=$((PASS + FAIL))
+echo ""
+echo "Results: $PASS/$TOTAL passed"
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+exit 0