cleargate 0.2.0 → 0.3.0

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

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * suggest_improvements.mjs — Generate stable improvement suggestions from REPORT.md
+ *
+ * Usage: node suggest_improvements.mjs <sprint-id>
+ *
+ * Reads:
+ *   - .cleargate/sprint-runs/<id>/REPORT.md §5 Framework Self-Assessment tables
+ *   - .cleargate/sprint-runs/<prev-id>/improvement-suggestions.md (if present, for context)
+ *
+ * Emits:
+ *   - .cleargate/sprint-runs/<id>/improvement-suggestions.md
+ *     with stable SUG-<sprint>-<n> IDs
+ *
+ * Append-only idempotency (R5):
+ *   - IDs are derived from a stable hash of (category, title) tuple
+ *   - Re-running produces zero new entries if all suggestions already captured
+ *   - Script exits 0 in both cases
+ *
+ * Note: "section" as used in §5 table extraction refers to the Framework Self-Assessment
+ * subsections: Templates, Handoffs, Skills, Process, Tooling.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// §5 subsection names used in sprint_report.md template
+const SELF_ASSESSMENT_SECTIONS = ['Templates', 'Handoffs', 'Skills', 'Process', 'Tooling'];
+
+/**
+ * Generate a stable short hash from a string.
+ * Used for SUG ID stability — same (category, title) always produces same ID.
+ * @param {string} input
+ * @returns {string} 6-char hex
+ */
+function stableHash(input) {
+  return createHash('sha256').update(input).digest('hex').slice(0, 6);
+}
+
+/**
+ * Parse §5 Framework Self-Assessment from REPORT.md content.
+ * Extracts Yellow/Red-rated rows as improvement candidates.
+ * @param {string} content
+ * @returns {{ category: string, item: string, rating: string, notes: string }[]}
+ */
+function parseSelfAssessment(content) {
+  const suggestions = [];
+
+  // Find the §5 Framework Self-Assessment section
+  const selfAssessmentMatch = content.match(/##\s*§5[^\n]*\n([\s\S]*?)(?=##\s*§6|$)/);
+  if (!selfAssessmentMatch) return suggestions;
+
+  const sectionContent = selfAssessmentMatch[1];
+
+  // Extract each subsection table
+  for (const category of SELF_ASSESSMENT_SECTIONS) {
+    // Find table rows under the category header
+    // Pattern: ### <category>\n | <item> | <rating> | <notes> |
+    const categoryMatch = sectionContent.match(
+      new RegExp(`###\\s+${category}\\s*\\n([\\s\\S]*?)(?=###|$)`, 'i')
+    );
+    if (!categoryMatch) continue;
+
+    const tableContent = categoryMatch[1];
+    // Parse table rows (skip header rows with ---)
+    const rows = tableContent.split('\n').filter(l => l.startsWith('|') && !l.includes('---'));
+
+    for (const row of rows) {
+      const cells = row.split('|').map(c => c.trim()).filter(Boolean);
+      if (cells.length < 2) continue;
+
+      const item = cells[0];
+      const rating = cells[1] || '';
+      const notes = cells[2] || '';
+
+      // Only flag Yellow or Red items as needing improvement
+      if (rating.toLowerCase().includes('yellow') || rating.toLowerCase().includes('red')) {
+        // Skip header rows
+        if (item === 'Item' || item === '---') continue;
+        suggestions.push({ category, item, rating, notes });
+      }
+    }
+  }
+
+  return suggestions;
+}
+
+/**
+ * Parse existing improvement-suggestions.md to extract already-captured SUG IDs.
+ * @param {string} content
+ * @returns {Set<string>} Set of SUG IDs
+ */
+function parseExistingIds(content) {
+  const ids = new Set();
+  // Match SUG-<sprint>-<n> patterns
+  const matches = content.matchAll(/SUG-[A-Z0-9-]+-\d+/g);
+  for (const m of matches) {
+    ids.add(m[0]);
+  }
+  return ids;
+}
+
+/**
+ * Atomic write 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);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 1) {
+    process.stderr.write('Usage: node suggest_improvements.mjs <sprint-id>\n');
+    process.exit(2);
+  }
+
+  const sprintId = args[0];
+  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 reportFile = path.join(sprintDir, 'REPORT.md');
+  const suggestionsFile = path.join(sprintDir, 'improvement-suggestions.md');
+
+  if (!fs.existsSync(reportFile)) {
+    process.stderr.write(`Error: REPORT.md not found at ${reportFile}\n`);
+    process.stderr.write('Run the Reporter agent first to generate the report.\n');
+    process.exit(1);
+  }
+
+  const reportContent = fs.readFileSync(reportFile, 'utf8');
+
+  // Parse §5 self-assessment for improvement candidates
+  const candidates = parseSelfAssessment(reportContent);
+
+  // Read existing suggestions if present (idempotency)
+  let existingContent = '';
+  const existingIds = new Set();
+  let nextN = 1;
+
+  if (fs.existsSync(suggestionsFile)) {
+    existingContent = fs.readFileSync(suggestionsFile, 'utf8');
+    // Parse existing IDs
+    const parsed = parseExistingIds(existingContent);
+    for (const id of parsed) {
+      existingIds.add(id);
+    }
+    // Determine the highest existing N for this sprint to continue from
+    const sprintPrefix = `SUG-${sprintId}-`;
+    let maxN = 0;
+    for (const id of parsed) {
+      if (id.startsWith(sprintPrefix)) {
+        const n = parseInt(id.slice(sprintPrefix.length), 10);
+        if (!isNaN(n) && n > maxN) maxN = n;
+      }
+    }
+    nextN = maxN + 1;
+  }
+
+  // Determine which candidates are new (stable hash-based dedup)
+  const newEntries = [];
+  for (const candidate of candidates) {
+    const hashKey = `${candidate.category}|${candidate.item}`;
+    const hash = stableHash(hashKey);
+    // Check if we already have an entry with this hash in existing content
+    // We encode the hash in a comment to enable stable lookup
+    const hashMarker = `<!-- hash:${hash} -->`;
+    if (existingContent.includes(hashMarker)) {
+      continue; // Already captured
+    }
+    const sugId = `SUG-${sprintId}-${String(nextN).padStart(2, '0')}`;
+    nextN++;
+    newEntries.push({ sugId, hash, hashMarker, ...candidate });
+  }
+
+  if (newEntries.length === 0) {
+    process.stdout.write(
+      `Idempotent: no new suggestions to add for sprint ${sprintId}.\n` +
+      `Existing file has ${existingIds.size} suggestion(s).\n`
+    );
+    process.exit(0);
+  }
+
+  // Build new entries markdown
+  const timestamp = new Date().toISOString();
+  const newEntriesLines = [];
+
+  // If file doesn't exist yet, write a header
+  if (!existingContent) {
+    newEntriesLines.push(`# Improvement Suggestions — ${sprintId}`);
+    newEntriesLines.push('');
+    newEntriesLines.push('Generated by `suggest_improvements.mjs`. Append-only; IDs are stable.');
+    newEntriesLines.push(`Vocabulary: Templates | Handoffs | Skills | Process | Tooling`);
+    newEntriesLines.push('');
+    newEntriesLines.push('---');
+    newEntriesLines.push('');
+  }
+
+  for (const entry of newEntries) {
+    newEntriesLines.push(`## ${entry.sugId} — ${entry.category}: ${entry.item}`);
+    newEntriesLines.push(`${entry.hashMarker}`);
+    newEntriesLines.push('');
+    newEntriesLines.push(`**Category:** ${entry.category}`);
+    newEntriesLines.push(`**Rating:** ${entry.rating}`);
+    newEntriesLines.push(`**Added:** ${timestamp}`);
+    newEntriesLines.push('');
+    if (entry.notes && entry.notes !== '' && entry.notes !== '<notes>') {
+      newEntriesLines.push(`**Context from report:** ${entry.notes}`);
+      newEntriesLines.push('');
+    }
+    newEntriesLines.push('**Suggested action:**');
+    newEntriesLines.push(`> _(to be filled by orchestrator or next sprint planning)_`);
+    newEntriesLines.push('');
+    newEntriesLines.push('---');
+    newEntriesLines.push('');
+  }
+
+  const appendContent = newEntriesLines.join('\n');
+  const finalContent = existingContent
+    ? existingContent.trimEnd() + '\n\n' + appendContent
+    : appendContent;
+
+  atomicWrite(suggestionsFile, finalContent);
+
+  process.stdout.write(
+    `suggest_improvements: added ${newEntries.length} new suggestion(s) to ${suggestionsFile}\n`
+  );
+  for (const e of newEntries) {
+    process.stdout.write(`  ${e.sugId}: [${e.category}] ${e.item} (${e.rating})\n`);
+  }
+}
+
+main();

package/dist/templates/cleargate-planning/.cleargate/scripts/surface-whitelist.txt

@@ -0,0 +1,27 @@
+# surface-whitelist.txt — Files always admitted by the pre-commit surface gate
+# regardless of the active story's §3.1 declared surface.
+#
+# Format: one pattern per line. Supports bash glob patterns.
+#   *     matches any non-path-separator sequence
+#   **    matches any sequence (including path separators)
+# Lines starting with # are comments; blank lines are ignored.
+#
+# These patterns are matched against repo-root-relative staged file paths.
+
+# Build manifest (regenerated by npm run build)
+cleargate-planning/MANIFEST.json
+
+# Hook execution logs
+.cleargate/hook-log/*
+
+# Token ledger files (auto-generated by SubagentStop hook)
+.cleargate/sprint-runs/**/token-ledger.jsonl
+
+# Pending-task sentinel files (auto-generated by PreToolUse hook)
+.cleargate/sprint-runs/**/.pending-task-*.json
+
+# Sprint state files (auto-managed)
+.cleargate/sprint-runs/**/state.json
+
+# Gate check log (auto-generated)
+.cleargate/hook-log/gate-check.log

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

@@ -0,0 +1,261 @@
+#!/usr/bin/env bash
+# test_assert_story_files.sh — 4-scenario Gherkin test for STORY-014-02
+#
+# Tests:
+#   Scenario 1: v2 init refuses when stories are missing
+#   Scenario 2: v2 init succeeds when all stories exist
+#   Scenario 3: v1 init warns but does not block
+#   Scenario 4: assert_story_files standalone CLI
+#
+# Run: bash .cleargate/scripts/test/test_assert_story_files.sh
+# Requires Node 24+.
+#
+# Story IDs must use digit-only parts (STORY-\d+-\d+), e.g. STORY-099-01.
+
+set -euo pipefail
+
+SCRIPTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REPO_ROOT="$(cd "${SCRIPTS_DIR}/../.." && pwd)"
+
+PASS=0
+FAIL=0
+ERRORS=()
+
+assert_eq() {
+  local label="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    echo "  PASS: $label"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $label"
+    echo "        expected: $expected"
+    echo "        actual:   $actual"
+    FAIL=$((FAIL + 1))
+    ERRORS+=("$label")
+  fi
+}
+
+assert_contains() {
+  local label="$1" needle="$2" haystack="$3"
+  if echo "$haystack" | grep -qF "$needle"; then
+    echo "  PASS: $label"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $label (needle not found)"
+    echo "        needle:   $needle"
+    echo "        haystack: $haystack"
+    FAIL=$((FAIL + 1))
+    ERRORS+=("$label")
+  fi
+}
+
+assert_not_exists() {
+  local label="$1" filepath="$2"
+  if [ ! -e "$filepath" ]; then
+    echo "  PASS: $label"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $label (file exists but should not)"
+    echo "        path: $filepath"
+    FAIL=$((FAIL + 1))
+    ERRORS+=("$label")
+  fi
+}
+
+assert_exists() {
+  local label="$1" filepath="$2"
+  if [ -e "$filepath" ]; then
+    echo "  PASS: $label"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $label (file does not exist)"
+    echo "        path: $filepath"
+    FAIL=$((FAIL + 1))
+    ERRORS+=("$label")
+  fi
+}
+
+# Create a minimal sprint file with given execution_mode
+# Story IDs must be STORY-\d+-\d+ (all numeric parts) for the regex to match.
+# Usage: make_sprint_file <dir> <sprint-id> <execution_mode> <story-id-1> [<story-id-2> ...]
+make_sprint_file() {
+  local dir="$1" sprint_id="$2" exec_mode="$3"
+  shift 3
+  local story_ids=("$@")
+
+  local sprint_file="${dir}/.cleargate/delivery/pending-sync/${sprint_id}_Test_Sprint.md"
+  mkdir -p "$(dirname "$sprint_file")"
+
+  {
+    echo "---"
+    echo "sprint_id: \"${sprint_id}\""
+    echo "execution_mode: \"${exec_mode}\""
+    echo "approved: true"
+    echo "---"
+    echo ""
+    echo "# ${sprint_id}: Test Sprint"
+    echo ""
+    echo "## 1. Consolidated Deliverables"
+    echo ""
+    echo "| Story | Complexity | Milestone |"
+    echo "|---|---|---|"
+    for sid in "${story_ids[@]}"; do
+      echo "| [\`${sid}\`](${sid}_Placeholder.md) Placeholder | L2 | M1 |"
+    done
+    echo ""
+    echo "## 2. Other Section"
+    echo ""
+    echo "Some content here."
+  } > "$sprint_file"
+
+  echo "$sprint_file"
+}
+
+# Create a minimal story file in pending-sync/
+make_story_file() {
+  local dir="$1" story_id="$2"
+  local pending_sync="${dir}/.cleargate/delivery/pending-sync"
+  mkdir -p "$pending_sync"
+  echo "# ${story_id}: Placeholder" > "${pending_sync}/${story_id}_Placeholder.md"
+}
+
+# ---------------------------------------------------------------------------
+echo ""
+echo "=== Scenario 1: v2 init refuses when stories are missing ==="
+# ---------------------------------------------------------------------------
+TMP1="$(mktemp -d)"
+trap 'rm -rf "$TMP1"' EXIT
+
+SPRINT_ID="SPRINT-099"
+make_sprint_file "$TMP1" "$SPRINT_ID" "v2" \
+  "STORY-099-01" "STORY-099-02" "STORY-099-03" > /dev/null
+
+# Only create STORY-099-01, leave 02 and 03 missing
+make_story_file "$TMP1" "STORY-099-01"
+
+STATE_JSON="${TMP1}/.cleargate/sprint-runs/${SPRINT_ID}/state.json"
+
+STDERR_OUT=""
+EXIT_CODE=0
+STDERR_OUT="$(CLEARGATE_REPO_ROOT="$TMP1" node "$SCRIPTS_DIR/init_sprint.mjs" \
+  "$SPRINT_ID" --stories "STORY-099-01,STORY-099-02,STORY-099-03" 2>&1 >/dev/null)" || EXIT_CODE=$?
+
+assert_eq "Sc1: exit code non-zero" "1" "$EXIT_CODE"
+assert_contains "Sc1: stderr mentions STORY-099-02" "STORY-099-02" "$STDERR_OUT"
+assert_contains "Sc1: stderr mentions STORY-099-03" "STORY-099-03" "$STDERR_OUT"
+assert_not_exists "Sc1: state.json NOT created" "$STATE_JSON"
+
+trap - EXIT
+rm -rf "$TMP1"
+
+# ---------------------------------------------------------------------------
+echo ""
+echo "=== Scenario 2: v2 init succeeds when all stories exist ==="
+# ---------------------------------------------------------------------------
+TMP2="$(mktemp -d)"
+trap 'rm -rf "$TMP2"' EXIT
+
+SPRINT_ID="SPRINT-098"
+make_sprint_file "$TMP2" "$SPRINT_ID" "v2" \
+  "STORY-098-01" "STORY-098-02" "STORY-098-03" > /dev/null
+
+make_story_file "$TMP2" "STORY-098-01"
+make_story_file "$TMP2" "STORY-098-02"
+make_story_file "$TMP2" "STORY-098-03"
+
+STATE_JSON="${TMP2}/.cleargate/sprint-runs/${SPRINT_ID}/state.json"
+
+EXIT_CODE=0
+CLEARGATE_REPO_ROOT="$TMP2" node "$SCRIPTS_DIR/init_sprint.mjs" \
+  "$SPRINT_ID" --stories "STORY-098-01,STORY-098-02,STORY-098-03" 2>/dev/null || EXIT_CODE=$?
+
+assert_eq "Sc2: exit code 0" "0" "$EXIT_CODE"
+assert_exists "Sc2: state.json created" "$STATE_JSON"
+
+# Verify execution_mode in state.json is v2
+if [ -f "$STATE_JSON" ]; then
+  EM="$(node -e "const s=JSON.parse(require('fs').readFileSync('$STATE_JSON','utf8')); console.log(s.execution_mode)")"
+  assert_eq "Sc2: state.json execution_mode=v2" "v2" "$EM"
+fi
+
+trap - EXIT
+rm -rf "$TMP2"
+
+# ---------------------------------------------------------------------------
+echo ""
+echo "=== Scenario 3: v1 init warns but does not block ==="
+# ---------------------------------------------------------------------------
+TMP3="$(mktemp -d)"
+trap 'rm -rf "$TMP3"' EXIT
+
+SPRINT_ID="SPRINT-097"
+make_sprint_file "$TMP3" "$SPRINT_ID" "v1" \
+  "STORY-097-01" "STORY-097-02" > /dev/null
+
+# Only create STORY-097-01, leave 02 missing
+make_story_file "$TMP3" "STORY-097-01"
+
+STATE_JSON="${TMP3}/.cleargate/sprint-runs/${SPRINT_ID}/state.json"
+
+EXIT_CODE=0
+STDERR_OUT="$(CLEARGATE_REPO_ROOT="$TMP3" node "$SCRIPTS_DIR/init_sprint.mjs" \
+  "$SPRINT_ID" --stories "STORY-097-01,STORY-097-02" 2>&1 >/dev/null)" || EXIT_CODE=$?
+
+assert_eq "Sc3: exit code 0 (v1 warns but continues)" "0" "$EXIT_CODE"
+assert_exists "Sc3: state.json created despite missing file" "$STATE_JSON"
+assert_contains "Sc3: stderr contains WARN" "WARN" "$STDERR_OUT"
+assert_contains "Sc3: stderr mentions STORY-097-02" "STORY-097-02" "$STDERR_OUT"
+
+trap - EXIT
+rm -rf "$TMP3"
+
+# ---------------------------------------------------------------------------
+echo ""
+echo "=== Scenario 4: assert_story_files standalone CLI ==="
+# ---------------------------------------------------------------------------
+TMP4="$(mktemp -d)"
+trap 'rm -rf "$TMP4"' EXIT
+
+SPRINT_ID="SPRINT-096"
+SPRINT_FILE="$(make_sprint_file "$TMP4" "$SPRINT_ID" "v2" \
+  "STORY-096-01" "STORY-096-02")"
+
+# Only create STORY-096-01, leave 02 missing
+make_story_file "$TMP4" "STORY-096-01"
+
+# Run standalone assert_story_files.mjs — should exit 1 with missing list
+STDERR_OUT=""
+EXIT_CODE=0
+STDERR_OUT="$(CLEARGATE_REPO_ROOT="$TMP4" node "$SCRIPTS_DIR/assert_story_files.mjs" \
+  "$SPRINT_FILE" 2>&1 >/dev/null)" || EXIT_CODE=$?
+
+assert_eq "Sc4: standalone exits non-zero when missing" "1" "$EXIT_CODE"
+assert_contains "Sc4: stderr lists STORY-096-02 as missing" "STORY-096-02" "$STDERR_OUT"
+
+# Now add the missing story file and re-run — should exit 0
+make_story_file "$TMP4" "STORY-096-02"
+
+EXIT_CODE=0
+STDOUT_OUT="$(CLEARGATE_REPO_ROOT="$TMP4" node "$SCRIPTS_DIR/assert_story_files.mjs" \
+  "$SPRINT_FILE" 2>/dev/null)" || EXIT_CODE=$?
+
+assert_eq "Sc4: standalone exits 0 when all present" "0" "$EXIT_CODE"
+assert_contains "Sc4: stdout confirms all present" "OK:" "$STDOUT_OUT"
+
+trap - EXIT
+rm -rf "$TMP4"
+
+# ---------------------------------------------------------------------------
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS"
+echo "Failed: $FAIL"
+if [ ${#ERRORS[@]} -gt 0 ]; then
+  echo "Failing scenarios:"
+  for e in "${ERRORS[@]}"; do
+    echo "  - $e"
+  done
+  exit 1
+fi
+echo "All tests passed."
+exit 0