cleargate 0.14.0 → 0.15.0

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

@@ -1,209 +0,0 @@
-#!/usr/bin/env bash
-# run_script.sh — Arbitrary-command wrapper that captures stdout/stderr independently
-# and writes a structured JSON incident file on non-zero exit.
-#
-# Interface: bash run_script.sh <command> [args...]
-#   <command>  — any executable on PATH (e.g. node, bash, sh, true, false)
-#   [args...]  — forwarded to the command unchanged
-#
-# Example (node script):
-#   bash run_script.sh node .cleargate/scripts/update_state.mjs STORY-01 Done
-# Example (bash script):
-#   bash run_script.sh bash .cleargate/scripts/pre_gate_runner.sh qa .worktrees/X sprint/S-01
-#
-# On success (exit 0): stdout+stderr are passed through; no incident file written.
-# On failure (exit ≠ 0): stdout+stderr are passed through AND a JSON incident is
-#   written to .cleargate/sprint-runs/<active-sprint>/.script-incidents/<ts>-<hash>.json
-#
-# Self-exemption: if RUN_SCRIPT_ACTIVE=1 is already set, the wrapper is already
-# running — do not nest. Execute the command directly to avoid infinite recursion.
-# This guard implements the self-exempt contract documented in SKILL.md §C.x.
-#
-# Env vars read:
-#   ORCHESTRATOR_PROJECT_DIR  — project root override (falls back to CLAUDE_PROJECT_DIR,
-#                               then to git rev-parse --show-toplevel, then script dir ancestor)
-#   AGENT_TYPE                — populates incident JSON agent_type field (null if empty)
-#   WORK_ITEM_ID              — populates incident JSON work_item_id field (null if empty)
-#   RUN_SCRIPT_ACTIVE         — self-exemption guard (set to 1 by this wrapper)
-
-set -euo pipefail
-
-# ---------------------------------------------------------------------------
-# Self-exemption guard — do not wrap recursively
-# ---------------------------------------------------------------------------
-if [[ "${RUN_SCRIPT_ACTIVE:-}" == "1" ]]; then
-  # Already inside a wrapper invocation; pass through directly, no JSON capture
-  exec "$@"
-fi
-
-# ---------------------------------------------------------------------------
-# Usage guard
-# ---------------------------------------------------------------------------
-if [[ $# -lt 1 ]]; then
-  echo "Usage: bash run_script.sh <command> [args...]" >&2
-  exit 2
-fi
-
-# ---------------------------------------------------------------------------
-# Resolve project root for incident file path
-# ---------------------------------------------------------------------------
-_resolve_project_root() {
-  # Priority: ORCHESTRATOR_PROJECT_DIR → CLAUDE_PROJECT_DIR → git toplevel → script dir ancestor
-  if [[ -n "${ORCHESTRATOR_PROJECT_DIR:-}" ]]; then
-    echo "$ORCHESTRATOR_PROJECT_DIR"
-    return
-  fi
-  if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
-    echo "$CLAUDE_PROJECT_DIR"
-    return
-  fi
-  if _root=$(git rev-parse --show-toplevel 2>/dev/null); then
-    echo "$_root"
-    return
-  fi
-  # Fallback: assume run_script.sh lives in <repo>/.cleargate/scripts/
-  echo "$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd ../.. && pwd)"
-}
-
-PROJECT_ROOT="$(_resolve_project_root)"
-SPRINT_RUNS_DIR="${PROJECT_ROOT}/.cleargate/sprint-runs"
-ACTIVE_FILE="${SPRINT_RUNS_DIR}/.active"
-
-# Determine sprint incident dir
-if [[ -f "$ACTIVE_FILE" ]]; then
-  SPRINT_ID="$(cat "$ACTIVE_FILE" | tr -d '[:space:]')"
-  INCIDENTS_DIR="${SPRINT_RUNS_DIR}/${SPRINT_ID}/.script-incidents"
-else
-  # No active sprint sentinel → write to _off-sprint bucket
-  INCIDENTS_DIR="${SPRINT_RUNS_DIR}/_off-sprint/.script-incidents"
-fi
-
-# ---------------------------------------------------------------------------
-# Capture stdout + stderr to temp files
-# ---------------------------------------------------------------------------
-STDOUT_TMP="$(mktemp)"
-STDERR_TMP="$(mktemp)"
-trap 'rm -f "$STDOUT_TMP" "$STDERR_TMP"' EXIT
-
-# Mark self as active before running the wrapped command
-export RUN_SCRIPT_ACTIVE=1
-
-EXIT_CODE=0
-"$@" >"$STDOUT_TMP" 2>"$STDERR_TMP" || EXIT_CODE=$?
-
-# ---------------------------------------------------------------------------
-# Always pass through stdout + stderr to the caller
-# ---------------------------------------------------------------------------
-cat "$STDOUT_TMP"
-cat "$STDERR_TMP" >&2
-
-# ---------------------------------------------------------------------------
-# On success: nothing more to do
-# ---------------------------------------------------------------------------
-if [[ $EXIT_CODE -eq 0 ]]; then
-  exit 0
-fi
-
-# ---------------------------------------------------------------------------
-# On failure: write structured JSON incident file
-# ---------------------------------------------------------------------------
-MAX_BYTES=4096
-TRUNCATION_SUFFIX="... [truncated]"
-
-_truncate_stream() {
-  # Byte-correct truncation: use head -c for POSIX byte-count (not bash ${var:0:N}
-  # which is char-index — wrong for UTF-8 multi-byte input).
-  # Trade-off: output may end with a partial multi-byte char boundary; downstream
-  # Node.js JSON.stringify escapes the partial sequence, producing valid JSON.
-  local file="$1"
-  local file_bytes
-  file_bytes="$(wc -c < "$file")"
-  if [[ $file_bytes -le $MAX_BYTES ]]; then
-    # File fits within budget — emit as-is (no suffix)
-    head -c "$MAX_BYTES" "$file"
-  else
-    # Truncation occurred — emit first MAX_BYTES bytes then TRUNCATION_SUFFIX
-    printf '%s' "$(head -c "$MAX_BYTES" "$file")${TRUNCATION_SUFFIX}"
-  fi
-}
-
-STDOUT_CAPTURED="$(_truncate_stream "$STDOUT_TMP")"
-STDERR_CAPTURED="$(_truncate_stream "$STDERR_TMP")"
-
-# Build filename: <ts>-<hash>.json
-TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-TS_FILE="$(date -u +%Y%m%dT%H%M%SZ)"
-# Hash the full command string (first arg + all args)
-HASH="$(printf '%s' "$*" | shasum -a 1 | cut -c1-12)"
-INCIDENT_FILE="${INCIDENTS_DIR}/${TS_FILE}-${HASH}.json"
-
-# Ensure incident directory exists
-mkdir -p "$INCIDENTS_DIR"
-
-# Collect context
-COMMAND="$1"
-shift
-ARGS_JSON="["
-FIRST=1
-for ARG in "$@"; do
-  if [[ $FIRST -eq 1 ]]; then
-    FIRST=0
-  else
-    ARGS_JSON="${ARGS_JSON},"
-  fi
-  # JSON-escape the arg: replace \ with \\, " with \", newlines with \n
-  ARG_ESCAPED="${ARG//\\/\\\\}"
-  ARG_ESCAPED="${ARG_ESCAPED//\"/\\\"}"
-  ARG_ESCAPED="${ARG_ESCAPED//$'\n'/\\n}"
-  ARGS_JSON="${ARGS_JSON}\"${ARG_ESCAPED}\""
-done
-ARGS_JSON="${ARGS_JSON}]"
-
-CWD="$(pwd)"
-
-# Encode agent_type + work_item_id (null if empty)
-AGENT_TYPE_VAL="${AGENT_TYPE:-}"
-WORK_ITEM_ID_VAL="${WORK_ITEM_ID:-}"
-
-if [[ -z "$AGENT_TYPE_VAL" ]]; then
-  AGENT_TYPE_JSON="null"
-else
-  AGENT_TYPE_JSON="\"${AGENT_TYPE_VAL}\""
-fi
-
-if [[ -z "$WORK_ITEM_ID_VAL" ]]; then
-  WORK_ITEM_ID_JSON="null"
-else
-  WORK_ITEM_ID_JSON="\"${WORK_ITEM_ID_VAL}\""
-fi
-
-# JSON-encode captured streams (escape backslash, double-quote, and newlines)
-_json_str() {
-  local s="$1"
-  s="${s//\\/\\\\}"
-  s="${s//\"/\\\"}"
-  s="${s//$'\n'/\\n}"
-  s="${s//$'\r'/\\r}"
-  printf '%s' "$s"
-}
-
-STDOUT_JSON="$(_json_str "$STDOUT_CAPTURED")"
-STDERR_JSON="$(_json_str "$STDERR_CAPTURED")"
-COMMAND_JSON="$(_json_str "$COMMAND")"
-CWD_JSON="$(_json_str "$CWD")"
-
-cat > "$INCIDENT_FILE" <<JSON
-{
-  "ts": "${TS}",
-  "command": "${COMMAND_JSON}",
-  "args": ${ARGS_JSON},
-  "cwd": "${CWD_JSON}",
-  "exit_code": ${EXIT_CODE},
-  "stdout": "${STDOUT_JSON}",
-  "stderr": "${STDERR_JSON}",
-  "agent_type": ${AGENT_TYPE_JSON},
-  "work_item_id": ${WORK_ITEM_ID_JSON}
-}
-JSON
-
-exit $EXIT_CODE

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

@@ -1,71 +0,0 @@
-#!/usr/bin/env node
-/**
- * sprint_trends.mjs — Sprint trends stub (full implementation deferred to CR-027)
- *
- * Usage: node sprint_trends.mjs <sprint-id>
- *
- * Counts sibling Completed sprints and appends a placeholder Trends section
- * to the current sprint's improvement-suggestions.md.
- *
- * Test seams:
- *   CLEARGATE_SPRINT_DIR=<path>      — override sprint dir resolution
- *   CLEARGATE_SPRINT_RUNS_DIR=<path> — override .cleargate/sprint-runs/ root for sibling counting
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-
-function main() {
-  const sprintId = process.argv[2];
-  if (!sprintId) {
-    process.stderr.write('Usage: node sprint_trends.mjs <sprint-id>\n');
-    process.exit(2);
-  }
-
-  const sprintDir = process.env.CLEARGATE_SPRINT_DIR
-    ? path.resolve(process.env.CLEARGATE_SPRINT_DIR)
-    : path.join(REPO_ROOT, '.cleargate', 'sprint-runs', sprintId);
-
-  const sprintRunsDir = process.env.CLEARGATE_SPRINT_RUNS_DIR
-    ? path.resolve(process.env.CLEARGATE_SPRINT_RUNS_DIR)
-    : path.dirname(sprintDir);
-
-  // Count sibling sprint dirs whose state.json has sprint_status === 'Completed'
-  let completedCount = 0;
-  if (fs.existsSync(sprintRunsDir)) {
-    for (const entry of fs.readdirSync(sprintRunsDir)) {
-      if (entry === path.basename(sprintDir)) continue;
-      const siblingState = path.join(sprintRunsDir, entry, 'state.json');
-      if (!fs.existsSync(siblingState)) continue;
-      try {
-        const state = JSON.parse(fs.readFileSync(siblingState, 'utf8'));
-        if (state.sprint_status === 'Completed') completedCount++;
-      } catch { /* skip malformed state.json */ }
-    }
-  }
-
-  const suggestionsFile = path.join(sprintDir, 'improvement-suggestions.md');
-  const trendsSection = `\n## Trends\n\nTrends: ${completedCount} closed sprints visible — full analysis deferred to CR-027.\n`;
-
-  if (!fs.existsSync(suggestionsFile)) {
-    const header = `# Improvement Suggestions — ${sprintId}\n\n`;
-    const tmpFile = `${suggestionsFile}.tmp.${process.pid}`;
-    fs.writeFileSync(tmpFile, header + trendsSection, 'utf8');
-    fs.renameSync(tmpFile, suggestionsFile);
-  } else {
-    const existing = fs.readFileSync(suggestionsFile, 'utf8');
-    const tmpFile = `${suggestionsFile}.tmp.${process.pid}`;
-    fs.writeFileSync(tmpFile, existing.trimEnd() + trendsSection, 'utf8');
-    fs.renameSync(tmpFile, suggestionsFile);
-  }
-
-  process.stdout.write(
-    `sprint_trends: stub — full implementation deferred to CR-027 (counted ${completedCount} closed sprints).\n`
-  );
-}
-
-main();

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

@@ -1,127 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://cleargate.dev/schemas/state.v3.json",
-  "title": "ClearGate Sprint State v3",
-  "description": "Schema for .cleargate/sprint-runs/<sprint-id>/state.json. schema_version=3 removes execution_mode (retired by STORY-070-01 — single always-enforced behavior). Migrated from v2 by _migrate-schema-v3.mjs on first read.",
-  "type": "object",
-  "required": [
-    "schema_version",
-    "sprint_id",
-    "sprint_status",
-    "stories",
-    "last_action",
-    "updated_at"
-  ],
-  "additionalProperties": true,
-  "properties": {
-    "schema_version": {
-      "type": "integer",
-      "const": 3,
-      "description": "Schema version. Must be 3 for v3 state files. Bumped from v2 by _migrate-schema-v3.mjs."
-    },
-    "sprint_id": {
-      "type": "string",
-      "description": "Sprint identifier, e.g. SPRINT-09",
-      "examples": ["SPRINT-09", "SPRINT-10"]
-    },
-    "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",
-        "lane",
-        "lane_assigned_by",
-        "lane_demoted_at",
-        "lane_demotion_reason"
-      ],
-      "additionalProperties": true,
-      "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.)"
-        },
-        "lane": {
-          "type": "string",
-          "enum": ["standard", "fast"],
-          "description": "Execution lane for this story. Default 'standard'. Set by Architect at sprint design or via --lane flag."
-        },
-        "lane_assigned_by": {
-          "type": "string",
-          "enum": ["architect", "human-override", "migration-default"],
-          "description": "Who assigned the lane value. 'migration-default' for stories migrated from v1."
-        },
-        "lane_demoted_at": {
-          "type": ["string", "null"],
-          "format": "date-time",
-          "description": "ISO-8601 timestamp when the story was demoted from fast to standard, or null if never demoted."
-        },
-        "lane_demotion_reason": {
-          "type": ["string", "null"],
-          "description": "Human-readable reason for lane demotion, or null if never demoted."
-        }
-      }
-    }
-  }
-}