codecruise 0.1.0

package/config/hooks/enforce-state-machine.sh

@@ -0,0 +1,161 @@
+#!/bin/bash
+# PreToolUse hook - Enforces valid state transitions in progress.yaml
+#
+# P1 Enforcement: Prevents invalid TODO state transitions
+#
+# Valid transitions:
+#   pending → in_progress
+#   in_progress → done, blocked, failed
+#   blocked → in_progress
+#   failed → in_progress, skipped
+#   done → (terminal, no transitions)
+#   skipped → (terminal, no transitions)
+#
+# Also enforces:
+#   - Cannot mark done without passing quality gates
+#   - Cannot skip from pending (must attempt first)
+
+# Load settings library
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$SCRIPT_DIR/lib/read-settings.sh" ]]; then
+  source "$SCRIPT_DIR/lib/read-settings.sh"
+elif [[ -f "$HOME/.claude/hooks/lib/read-settings.sh" ]]; then
+  source "$HOME/.claude/hooks/lib/read-settings.sh"
+else
+  get_enforce_mode() { echo "${CODECRUISE_ENFORCE:-strict}"; }
+fi
+
+# Load enforcement tracking
+if [[ -f "$SCRIPT_DIR/track-enforcement.sh" ]]; then
+  source "$SCRIPT_DIR/track-enforcement.sh"
+elif [[ -f "$HOME/.claude/hooks/track-enforcement.sh" ]]; then
+  source "$HOME/.claude/hooks/track-enforcement.sh"
+else
+  track_enforcement() { :; }
+fi
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')
+
+# Only check Edit/Write to progress.yaml or roadmap files
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+# Check if editing state files
+if [[ "$FILE" != *"progress.yaml"* && "$FILE" != *"roadmap/"* ]]; then
+  exit 0
+fi
+
+# Get enforcement mode
+ENFORCE_MODE=$(get_enforce_mode "state")
+
+if [[ "$ENFORCE_MODE" == "off" ]]; then
+  exit 0
+fi
+
+# For progress.yaml edits, validate state transitions
+if [[ "$FILE" == *"progress.yaml"* ]]; then
+  # Read current state
+  if [[ -f "progress.yaml" ]]; then
+    CURRENT_STATUS=$(grep -E "^\s*status:" progress.yaml | head -1 | sed 's/.*status:\s*//' | tr -d ' "' || echo "")
+  else
+    CURRENT_STATUS=""
+  fi
+
+  # Try to extract new status from the edit
+  # This is tricky because we get the new content, need to parse what's changing
+  NEW_STATUS=$(echo "$NEW_CONTENT" | grep -E "status:" | head -1 | sed 's/.*status:\s*//' | tr -d ' "' || echo "")
+
+  # If no status change detected, allow
+  if [[ -z "$NEW_STATUS" || "$NEW_STATUS" == "$CURRENT_STATUS" ]]; then
+    exit 0
+  fi
+
+  # Define valid transitions
+  VALID=false
+  case "$CURRENT_STATUS" in
+    "pending")
+      [[ "$NEW_STATUS" == "in_progress" ]] && VALID=true
+      ;;
+    "in_progress")
+      [[ "$NEW_STATUS" == "done" || "$NEW_STATUS" == "blocked" || "$NEW_STATUS" == "failed" ]] && VALID=true
+      ;;
+    "blocked")
+      [[ "$NEW_STATUS" == "in_progress" ]] && VALID=true
+      ;;
+    "failed")
+      [[ "$NEW_STATUS" == "in_progress" || "$NEW_STATUS" == "skipped" ]] && VALID=true
+      ;;
+    "done"|"skipped")
+      # Terminal states - no transitions allowed
+      VALID=false
+      ;;
+    "")
+      # No current status - allow setting initial status
+      VALID=true
+      ;;
+    *)
+      # Unknown current status - allow
+      VALID=true
+      ;;
+  esac
+
+  if [[ "$VALID" == false ]]; then
+    if [[ "$ENFORCE_MODE" == "ask" ]]; then
+      DECISION="ask"
+      REASON="Invalid state transition: $CURRENT_STATUS → $NEW_STATUS. Allow anyway?"
+      track_enforcement "state_ask" "$CURRENT_STATUS -> $NEW_STATUS" "enforce-state-machine"
+    else
+      DECISION="deny"
+      REASON="Invalid state transition: $CURRENT_STATUS → $NEW_STATUS. Valid transitions: pending→in_progress, in_progress→done/blocked/failed, blocked→in_progress, failed→in_progress/skipped. Terminal states (done, skipped) cannot transition."
+      track_enforcement "state_block" "$CURRENT_STATUS -> $NEW_STATUS" "enforce-state-machine"
+    fi
+
+    cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "$DECISION",
+    "permissionDecisionReason": "$REASON"
+  }
+}
+EOF
+    exit 0
+  fi
+
+  # Additional check: Cannot mark done without quality gates
+  if [[ "$NEW_STATUS" == "done" ]]; then
+    SUMMARY_FILE=".codecruise/verification/summary.json"
+    if [[ -f "$SUMMARY_FILE" ]]; then
+      TEST_EXIT=$(jq -r '.tests.exit_code // 0' "$SUMMARY_FILE")
+      LINT_EXIT=$(jq -r '.lint.exit_code // 0' "$SUMMARY_FILE")
+
+      if [[ "$TEST_EXIT" != "0" && "$TEST_EXIT" != "-1" ]] || [[ "$LINT_EXIT" != "0" && "$LINT_EXIT" != "-1" ]]; then
+        if [[ "$ENFORCE_MODE" == "ask" ]]; then
+          DECISION="ask"
+          REASON="Quality gates not passed (test=$TEST_EXIT, lint=$LINT_EXIT). Mark as done anyway?"
+        else
+          DECISION="deny"
+          REASON="Cannot mark TODO as done: quality gates not passed (test exit=$TEST_EXIT, lint exit=$LINT_EXIT). Fix issues first or use /skip to skip this TODO."
+        fi
+
+        cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "$DECISION",
+    "permissionDecisionReason": "$REASON"
+  }
+}
+EOF
+        exit 0
+      fi
+    fi
+  fi
+fi
+
+# Allow the operation
+exit 0

package/config/hooks/enforce-tdd.sh

@@ -0,0 +1,180 @@
+#!/bin/bash
+# PreToolUse hook - Enforces TDD by requiring tests before implementation
+#
+# P0 Enforcement: Blocks writes to implementation files unless:
+# 1. A corresponding test file already exists, OR
+# 2. The file being written IS a test file, OR
+# 3. The file is configuration/non-code
+#
+# Configuration (highest to lowest priority):
+# 1. Command flag: /run --enforce=off
+# 2. Project: .claude/settings.json → codecruise.enforce_tdd
+# 3. User: ~/.claude/settings.json → codecruise.enforce_tdd
+# 4. Default: strict
+
+# Load settings library
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$SCRIPT_DIR/lib/read-settings.sh" ]]; then
+  source "$SCRIPT_DIR/lib/read-settings.sh"
+elif [[ -f "$HOME/.claude/hooks/lib/read-settings.sh" ]]; then
+  source "$HOME/.claude/hooks/lib/read-settings.sh"
+else
+  # Fallback if library not found
+  get_enforce_mode() { echo "${CODECRUISE_ENFORCE:-strict}"; }
+fi
+
+# Load enforcement tracking
+if [[ -f "$SCRIPT_DIR/track-enforcement.sh" ]]; then
+  source "$SCRIPT_DIR/track-enforcement.sh"
+elif [[ -f "$HOME/.claude/hooks/track-enforcement.sh" ]]; then
+  source "$HOME/.claude/hooks/track-enforcement.sh"
+else
+  track_enforcement() { :; }  # no-op fallback
+fi
+
+INPUT=$(cat)
+
+# Get enforcement mode from settings hierarchy
+ENFORCE_MODE=$(get_enforce_mode "tdd")
+
+# If enforcement is off, allow everything
+if [[ "$ENFORCE_MODE" == "off" ]]; then
+  exit 0
+fi
+
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only check Write and Edit operations
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+# Skip if no file path
+if [[ -z "$FILE" ]]; then
+  exit 0
+fi
+
+# Skip if not in a codecruise project
+if [[ ! -f "progress.yaml" ]]; then
+  exit 0
+fi
+
+# Get execution status - only enforce during active TODO execution
+EXEC_STATUS=$(grep "status:" progress.yaml 2>/dev/null | head -1 | sed 's/.*status: //' | tr -d ' "' || echo "")
+if [[ "$EXEC_STATUS" != "running" && "$EXEC_STATUS" != "in_progress" ]]; then
+  exit 0
+fi
+
+# Files that don't need tests (configuration, assets, etc.)
+SKIP_PATTERNS=(
+  "*.json"
+  "*.yaml"
+  "*.yml"
+  "*.md"
+  "*.txt"
+  "*.css"
+  "*.scss"
+  "*.svg"
+  "*.png"
+  "*.jpg"
+  "*.ico"
+  "*.env*"
+  "*.config.*"
+  "*.d.ts"
+  "tsconfig*"
+  "package.json"
+  "pnpm-lock.yaml"
+  ".gitignore"
+  ".eslintrc*"
+  ".prettierrc*"
+  "vite.config.*"
+  "next.config.*"
+  "tailwind.config.*"
+  "postcss.config.*"
+  "prisma/*"
+  "migrations/*"
+)
+
+# Check if file matches skip patterns
+for pattern in "${SKIP_PATTERNS[@]}"; do
+  if [[ "$FILE" == $pattern ]]; then
+    exit 0
+  fi
+done
+
+# Check if this IS a test file (allow these)
+if [[ "$FILE" == *.test.* ]] || \
+   [[ "$FILE" == *.spec.* ]] || \
+   [[ "$FILE" == *_test.* ]] || \
+   [[ "$FILE" == *_spec.* ]] || \
+   [[ "$FILE" == */__tests__/* ]] || \
+   [[ "$FILE" == */test/* ]] || \
+   [[ "$FILE" == */tests/* ]] || \
+   [[ "$FILE" == */e2e/* ]]; then
+  exit 0
+fi
+
+# Check if this is a source file that needs a test
+if [[ "$FILE" == *.ts ]] || \
+   [[ "$FILE" == *.tsx ]] || \
+   [[ "$FILE" == *.js ]] || \
+   [[ "$FILE" == *.jsx ]] || \
+   [[ "$FILE" == *.py ]] || \
+   [[ "$FILE" == *.go ]] || \
+   [[ "$FILE" == *.rs ]]; then
+
+  # Get base name and extension
+  BASENAME="${FILE%.*}"
+  EXT="${FILE##*.}"
+  DIR=$(dirname "$FILE")
+  FILENAME=$(basename "$FILE")
+  FILENAME_NO_EXT="${FILENAME%.*}"
+
+  # Possible test file patterns
+  TEST_PATTERNS=(
+    "${BASENAME}.test.${EXT}"
+    "${BASENAME}.spec.${EXT}"
+    "${BASENAME}_test.${EXT}"
+    "${DIR}/__tests__/${FILENAME_NO_EXT}.test.${EXT}"
+    "${DIR}/__tests__/${FILENAME_NO_EXT}.spec.${EXT}"
+    "${DIR}/tests/${FILENAME_NO_EXT}.test.${EXT}"
+    "${DIR}/test/${FILENAME_NO_EXT}.test.${EXT}"
+  )
+
+  # Check if any test file exists
+  TEST_EXISTS=false
+  for test_file in "${TEST_PATTERNS[@]}"; do
+    if [[ -f "$test_file" ]]; then
+      TEST_EXISTS=true
+      break
+    fi
+  done
+
+  if [[ "$TEST_EXISTS" == false ]]; then
+    # Determine action based on enforcement mode
+    if [[ "$ENFORCE_MODE" == "ask" ]]; then
+      DECISION="ask"
+      REASON="TDD: No test file found. Expected: ${BASENAME}.test.${EXT}. Allow implementation anyway?"
+      track_enforcement "tdd_ask" "Missing test for $FILE" "enforce-tdd"
+    else
+      DECISION="deny"
+      REASON="TDD violation: Write tests first before implementing. Expected test file: ${BASENAME}.test.${EXT} or ${DIR}/__tests__/${FILENAME_NO_EXT}.test.${EXT}. Create the test file with failing tests (RED), then implement (GREEN)."
+      track_enforcement "tdd_block" "Missing test for $FILE" "enforce-tdd"
+    fi
+
+    cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "$DECISION",
+    "permissionDecisionReason": "$REASON"
+  }
+}
+EOF
+    exit 0
+  fi
+fi
+
+# Allow the operation
+exit 0

package/config/hooks/format.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# PostToolUse hook - auto-formats files after edit/write
+# "Handles the last 10% before CI" — Boris Cherny
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [[ -z "$FILE" || ! -f "$FILE" ]]; then
+  exit 0
+fi
+
+EXT="${FILE##*.}"
+
+case "$EXT" in
+  js|ts|jsx|tsx|json|css|scss|md|html|yaml|yml)
+    if command -v npx &> /dev/null; then
+      npx prettier --write "$FILE" 2>/dev/null || true
+    fi
+    ;;
+  py)
+    if command -v black &> /dev/null; then
+      black "$FILE" 2>/dev/null || true
+    fi
+    if command -v isort &> /dev/null; then
+      isort "$FILE" 2>/dev/null || true
+    fi
+    ;;
+  go)
+    if command -v gofmt &> /dev/null; then
+      gofmt -w "$FILE" 2>/dev/null || true
+    fi
+    ;;
+  rs)
+    if command -v rustfmt &> /dev/null; then
+      rustfmt "$FILE" 2>/dev/null || true
+    fi
+    ;;
+esac
+
+exit 0

package/config/hooks/lib/activity-helpers.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# activity-helpers.sh — Helper functions for activity logging
+#
+# Source this in hooks or commands to log OODA events:
+#   source ~/.claude/hooks/lib/activity-helpers.sh
+#
+# Usage:
+#   log_ooda_observe "todo-1.1b-004"
+#   log_ooda_orient "0.85" ""
+#   log_ooda_decide "execute"
+#   log_ooda_act "todo-1.1b-004" "Implement validation"
+#   log_todo_complete "todo-1.1b-004" "3m 30s" "abc123"
+#   log_todo_fail "todo-1.1b-004" "connection refused"
+#   log_retry "todo-1.1b-004" "2" "3"
+#   log_skip "todo-1.1b-004" "external dep down"
+#   log_session_start
+#   log_session_pause
+
+ACTIVITY_LOG="${CODECRUISE_ACTIVITY_LOG:-.codecruise/activity.log}"
+
+# Ensure directory exists
+_ensure_log_dir() {
+  mkdir -p "$(dirname "$ACTIVITY_LOG")" 2>/dev/null || true
+}
+
+# Get timestamp
+_ts() {
+  date "+%Y-%m-%d %H:%M:%S"
+}
+
+# Base log function
+_log() {
+  _ensure_log_dir
+  echo "[$(_ts)] $1" >> "$ACTIVITY_LOG"
+}
+
+# Indented detail
+_log_detail() {
+  _ensure_log_dir
+  echo "[$(_ts)]    $1" >> "$ACTIVITY_LOG"
+}
+
+# --- Session Events ---
+
+log_session_start() {
+  _log "━━━ SESSION START ━━━"
+}
+
+log_session_pause() {
+  _log "⏸ PAUSE"
+  _log "━━━ SESSION PAUSE ━━━"
+}
+
+log_session_resume() {
+  _log "▶ RESUME"
+}
+
+# --- OODA Phase Events ---
+
+log_ooda_observe() {
+  local todo="$1"
+  _log "👁 OBSERVE $todo"
+}
+
+log_ooda_observe_detail() {
+  local key="$1"
+  local value="$2"
+  local symbol="${3:-├─}"  # Use └─ for last item
+  _log_detail "$symbol $key: $value"
+}
+
+log_ooda_orient() {
+  local confidence="$1"
+  local patterns="$2"
+  _log "🧭 ORIENT confidence=$confidence"
+  if [[ -n "$patterns" ]]; then
+    _log_detail "└─ patterns: $patterns"
+  fi
+}
+
+log_ooda_decide() {
+  local decision="$1"
+  _log "⚡ DECIDE $decision"
+}
+
+log_ooda_act() {
+  local todo="$1"
+  local description="$2"
+  _log "▶ ACT $todo \"$description\""
+}
+
+log_ooda_act_phase() {
+  local phase="$1"  # red, green, refactor
+  local detail="$2"
+  case "$phase" in
+    red)     _log_detail "├─ RED: $detail" ;;
+    green)   _log_detail "├─ GREEN: $detail" ;;
+    refactor) _log_detail "├─ REFACTOR: $detail" ;;
+    verify)  _log_detail "└─ VERIFY: $detail" ;;
+  esac
+}
+
+# --- TODO Events ---
+
+log_todo_complete() {
+  local todo="$1"
+  local duration="$2"
+  local commit="$3"
+  _log "✓ COMPLETE $todo ($duration) commit:$commit"
+}
+
+log_todo_fail() {
+  local todo="$1"
+  local error="$2"
+  _log_detail "└─ ✗ FAIL: $error"
+}
+
+log_retry() {
+  local todo="$1"
+  local attempt="$2"
+  local max="$3"
+  _log "⚠ RETRY $todo (attempt $attempt/$max)"
+}
+
+log_skip() {
+  local todo="$1"
+  local reason="$2"
+  _log "⏭ SKIP $todo ($reason)"
+}
+
+log_next() {
+  local todo="$1"
+  _log "→ NEXT $todo"
+}
+
+# --- Verification Events ---
+
+log_verify() {
+  local lint="$1"   # ✓ or ✗
+  local tsc="$2"    # ✓ or ✗
+  local test="$3"   # ✓ or ✗
+  _log_detail "└─ VERIFY: lint $lint | tsc $tsc | test $test"
+}
+
+# --- Blocker Events ---
+
+log_blocker() {
+  local pattern="$1"
+  local detail="$2"
+  _log "🔴 BLOCKER DETECTED $pattern"
+  _log_detail "└─ $detail"
+}
+
+# --- Checkpoint Events ---
+
+log_checkpoint() {
+  local type="$1"  # subfeature, feature
+  local id="$2"
+  local todos_done="$3"
+  local total="$4"
+  _log "═══ CHECKPOINT: $type $id ($todos_done/$total) ═══"
+}

package/config/hooks/lib/read-settings.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# read-settings.sh - Reads codecruise settings with proper hierarchy
+#
+# Priority (highest to lowest):
+# 1. Environment variable (from command flags)
+# 2. Project settings (.claude/settings.json)
+# 3. User settings (~/.claude/settings.json)
+# 4. Default value
+#
+# Usage:
+#   source ~/.claude/hooks/lib/read-settings.sh
+#   ENFORCE=$(get_setting "enforce" "strict")
+#   TDD_ENFORCE=$(get_setting "enforce_tdd" "$ENFORCE")
+
+# Get a codecruise setting with fallback chain
+# Args: $1 = setting name, $2 = default value
+get_setting() {
+  local setting_name="$1"
+  local default_value="$2"
+
+  # Convert setting name to env var name (enforce -> CODECRUISE_ENFORCE)
+  local env_var="CODECRUISE_$(echo "$setting_name" | tr '[:lower:]' '[:upper:]')"
+
+  # 1. Check environment variable first (highest priority - from command flags)
+  local env_value="${!env_var}"
+  if [[ -n "$env_value" ]]; then
+    echo "$env_value"
+    return
+  fi
+
+  # 2. Check project settings (.claude/settings.json)
+  if [[ -f ".claude/settings.json" ]]; then
+    local project_value
+    project_value=$(jq -r ".codecruise.${setting_name} // empty" .claude/settings.json 2>/dev/null)
+    if [[ -n "$project_value" && "$project_value" != "null" ]]; then
+      echo "$project_value"
+      return
+    fi
+  fi
+
+  # 3. Check user settings (~/.claude/settings.json)
+  if [[ -f "$HOME/.claude/settings.json" ]]; then
+    local user_value
+    user_value=$(jq -r ".codecruise.${setting_name} // empty" "$HOME/.claude/settings.json" 2>/dev/null)
+    if [[ -n "$user_value" && "$user_value" != "null" ]]; then
+      echo "$user_value"
+      return
+    fi
+  fi
+
+  # 4. Return default
+  echo "$default_value"
+}
+
+# Check if enforcement is enabled for a specific check
+# Args: $1 = check name (tdd, quality, criteria)
+# Returns: "strict", "ask", or "off"
+get_enforce_mode() {
+  local check_name="$1"
+
+  # Get specific setting first, fall back to global enforce
+  local specific_setting="enforce_${check_name}"
+  local global_enforce
+  global_enforce=$(get_setting "enforce" "strict")
+
+  get_setting "$specific_setting" "$global_enforce"
+}
+
+# Export functions for use in hooks
+export -f get_setting
+export -f get_enforce_mode