cleargate 0.2.0 → 0.3.0

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();

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.)"
+        }
+      }
+    }
+  }
+}