cleargate 0.2.1 → 0.4.0

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

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# run_script.sh — Wrapper that captures stdout/stderr separately and prints a
+# structured diagnostic block on non-zero exit.
+# Usage: run_script.sh <script-name> [args...]
+# Supported extensions: .mjs (runs via node), .sh (runs via bash)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ---------------------------------------------------------------------------
+# Usage guard
+# ---------------------------------------------------------------------------
+if [[ $# -lt 1 ]]; then
+  echo "Usage: run_script.sh <script-name> [args...]" >&2
+  exit 2
+fi
+
+SCRIPT_NAME="$1"
+shift
+SCRIPT_ARGS=()
+if [[ $# -gt 0 ]]; then
+  SCRIPT_ARGS=("$@")
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve path — script may be an absolute path or relative to SCRIPT_DIR
+# ---------------------------------------------------------------------------
+if [[ "$SCRIPT_NAME" == /* ]]; then
+  SCRIPT_PATH="$SCRIPT_NAME"
+else
+  SCRIPT_PATH="${SCRIPT_DIR}/${SCRIPT_NAME}"
+fi
+
+# ---------------------------------------------------------------------------
+# Extension routing
+# ---------------------------------------------------------------------------
+EXT="${SCRIPT_NAME##*.}"
+case "$EXT" in
+  mjs)  RUNNER="node" ;;
+  sh)   RUNNER="bash" ;;
+  *)
+    echo "unsupported extension: .${EXT}" >&2
+    exit 2
+    ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Check script exists
+# ---------------------------------------------------------------------------
+if [[ ! -f "$SCRIPT_PATH" ]]; then
+  echo "run_script.sh: script not found: ${SCRIPT_PATH}" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Capture stdout + stderr to temp files
+# ---------------------------------------------------------------------------
+STDOUT_FILE="$(mktemp)"
+STDERR_FILE="$(mktemp)"
+trap 'rm -f "$STDOUT_FILE" "$STDERR_FILE"' EXIT
+
+EXIT_CODE=0
+if [[ ${#SCRIPT_ARGS[@]} -gt 0 ]]; then
+  "$RUNNER" "$SCRIPT_PATH" "${SCRIPT_ARGS[@]}" > "$STDOUT_FILE" 2> "$STDERR_FILE" || EXIT_CODE=$?
+else
+  "$RUNNER" "$SCRIPT_PATH" > "$STDOUT_FILE" 2> "$STDERR_FILE" || EXIT_CODE=$?
+fi
+
+# ---------------------------------------------------------------------------
+# On success: pass through and exit 0
+# ---------------------------------------------------------------------------
+if [[ $EXIT_CODE -eq 0 ]]; then
+  cat "$STDOUT_FILE"
+  cat "$STDERR_FILE" >&2
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# On failure: pass stdout through, then print structured diagnostic to stderr
+# ---------------------------------------------------------------------------
+cat "$STDOUT_FILE"
+
+# Root-cause heuristic (6-branch)
+STDERR_CONTENT="$(cat "$STDERR_FILE")"
+ROOT_CAUSE="unknown error"
+SUGGESTED_FIX="check the script output above for details"
+
+if echo "$STDERR_CONTENT" | grep -q "state\.json not found"; then
+  ROOT_CAUSE="state.json not found — sprint may not be initialized"
+  SUGGESTED_FIX="run: node .cleargate/scripts/init_sprint.mjs <sprint-id> --stories <ids>"
+elif echo "$STDERR_CONTENT" | grep -qi "ENOENT"; then
+  ROOT_CAUSE="missing file (ENOENT)"
+  SUGGESTED_FIX="verify all required files exist at the expected paths"
+elif echo "$STDERR_CONTENT" | grep -qi "EACCES"; then
+  ROOT_CAUSE="permission denied (EACCES)"
+  SUGGESTED_FIX="chmod 755 the target file or directory"
+elif echo "$STDERR_CONTENT" | grep -qi "SyntaxError"; then
+  ROOT_CAUSE="JavaScript syntax error"
+  SUGGESTED_FIX="fix the syntax error in the script; run: node --check <file>"
+elif echo "$STDERR_CONTENT" | grep -qi "Cannot find module"; then
+  ROOT_CAUSE="missing module (import resolution failure)"
+  SUGGESTED_FIX="run npm install in the relevant package directory"
+elif echo "$STDERR_CONTENT" | grep -qi "command not found"; then
+  ROOT_CAUSE="required command not found on PATH"
+  SUGGESTED_FIX="install the missing tool or add it to PATH"
+fi
+
+{
+  echo ""
+  echo "## Script Incident"
+  echo "Script:     ${SCRIPT_NAME}"
+  echo "Runner:     ${RUNNER}"
+  echo "Exit code:  ${EXIT_CODE}"
+  echo ""
+  echo "### First 10 lines of stderr:"
+  echo "$STDERR_CONTENT" | head -10
+  echo ""
+  echo "Root cause: ${ROOT_CAUSE}"
+  echo "Suggested fix: ${SUGGESTED_FIX}"
+  echo "## End Incident"
+} >&2
+
+exit $EXIT_CODE

package/dist/templates/cleargate-planning/.cleargate/scripts/state.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cleargate.dev/schemas/state.v1.json",
+  "title": "ClearGate Sprint State v1",
+  "description": "Schema for .cleargate/sprint-runs/<sprint-id>/state.json. schema_version=1 is LOCKED — any field addition or removal must bump schema_version.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "sprint_id",
+    "execution_mode",
+    "sprint_status",
+    "stories",
+    "last_action",
+    "updated_at"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version. Must be 1 for v1 state files. Bump on any schema change."
+    },
+    "sprint_id": {
+      "type": "string",
+      "description": "Sprint identifier, e.g. S-09",
+      "examples": ["S-09", "S-10"]
+    },
+    "execution_mode": {
+      "type": "string",
+      "enum": ["v1", "v2"],
+      "description": "Execution mode for the sprint. v1 = legacy sequential; v2 = worktree-parallel."
+    },
+    "sprint_status": {
+      "type": "string",
+      "description": "Overall sprint status",
+      "examples": ["Active", "Closed"]
+    },
+    "stories": {
+      "type": "object",
+      "description": "Map of story ID to story state entry",
+      "additionalProperties": {
+        "$ref": "#/definitions/StoryEntry"
+      }
+    },
+    "last_action": {
+      "type": "string",
+      "description": "Human-readable description of the last operation performed"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp of last top-level update"
+    }
+  },
+  "definitions": {
+    "StoryEntry": {
+      "type": "object",
+      "required": [
+        "state",
+        "qa_bounces",
+        "arch_bounces",
+        "worktree",
+        "updated_at",
+        "notes"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "state": {
+          "type": "string",
+          "enum": [
+            "Ready to Bounce",
+            "Bouncing",
+            "QA Passed",
+            "Architect Passed",
+            "Sprint Review",
+            "Done",
+            "Escalated",
+            "Parking Lot"
+          ],
+          "description": "Current lifecycle state of the story"
+        },
+        "qa_bounces": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 3,
+          "description": "Number of QA bounce cycles. Reaching 3 triggers auto-escalation."
+        },
+        "arch_bounces": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 3,
+          "description": "Number of Architect bounce cycles. Reaching 3 triggers auto-escalation."
+        },
+        "worktree": {
+          "type": ["string", "null"],
+          "description": "Path to the story's git worktree checkout, or null if not in a worktree"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 timestamp of last update to this story entry"
+        },
+        "notes": {
+          "type": "string",
+          "description": "Free-form notes for this story (escalation reason, QA comments, etc.)"
+        }
+      }
+    }
+  }
+}

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