codecruise 0.1.0

package/config/hooks/validate-plan.sh

@@ -0,0 +1,213 @@
+#!/bin/bash
+# validate-plan.sh — Plan consistency validation
+#
+# Called by /doctor --validate-plan
+# Checks roadmap vs progress.yaml for consistency
+#
+# Outputs JSON to .codecruise/validation-results.json
+#
+# Checks:
+# 1. Orphan TODOs (in queue but not roadmap)
+# 2. Missing TODOs (in roadmap but not queue)
+# 3. Circular dependencies
+# 4. Invalid depends_on references
+# 5. Stale state detection
+
+set -e
+
+ROADMAP_DIR="roadmap"
+PROGRESS_FILE="progress.yaml"
+OUTPUT_FILE=".codecruise/validation-results.json"
+
+# Ensure output directory exists
+mkdir -p "$(dirname "$OUTPUT_FILE")"
+
+# Initialize results
+ORPHANS=()
+MISSING=()
+INVALID_DEPS=()
+HAS_CYCLES=false
+STALE_STATE=""
+
+# --- Helper Functions ---
+
+# Extract all TODO IDs from roadmap files
+get_roadmap_todos() {
+  if [[ -d "$ROADMAP_DIR" ]]; then
+    find "$ROADMAP_DIR" -name "*.yaml" -exec grep -ohE "todo-[0-9]+\.[0-9]+[a-z]-[0-9]+" {} \; 2>/dev/null | sort -u
+  fi
+}
+
+# Extract all TODO IDs from progress.yaml queues
+get_queue_todos() {
+  if [[ -f "$PROGRESS_FILE" ]]; then
+    grep -ohE "todo-[0-9]+\.[0-9]+[a-z]-[0-9]+" "$PROGRESS_FILE" 2>/dev/null | sort -u
+  fi
+}
+
+# Extract depends_on relationships from roadmap
+get_dependencies() {
+  if [[ -d "$ROADMAP_DIR" ]]; then
+    # Output: "dependent_todo dependency_todo" pairs
+    find "$ROADMAP_DIR" -name "*.yaml" -exec awk '
+      /^[[:space:]]*-[[:space:]]*id:/ { current_id = $3 }
+      /depends_on:/ {
+        gsub(/[\[\],]/, " ")
+        for (i=2; i<=NF; i++) {
+          if ($i ~ /todo-/) {
+            print $i, current_id
+          }
+        }
+      }
+    ' {} \; 2>/dev/null
+  fi
+}
+
+# Check for circular dependencies using tsort
+check_circular_deps() {
+  local deps
+  deps=$(get_dependencies)
+
+  if [[ -z "$deps" ]]; then
+    echo "false"
+    return
+  fi
+
+  # tsort returns non-zero if cycle detected
+  if echo "$deps" | tsort >/dev/null 2>&1; then
+    echo "false"
+  else
+    echo "true"
+  fi
+}
+
+# Check stale state (paused too long)
+check_stale_state() {
+  if [[ ! -f "$PROGRESS_FILE" ]]; then
+    return
+  fi
+
+  local paused_at
+  paused_at=$(grep "paused_at:" "$PROGRESS_FILE" 2>/dev/null | head -1 | sed 's/.*paused_at:[[:space:]]*//' | tr -d '"' || echo "")
+
+  if [[ -z "$paused_at" ]] || [[ "$paused_at" == "null" ]]; then
+    return
+  fi
+
+  # Calculate hours since pause (rough calculation)
+  local pause_date
+  pause_date=$(echo "$paused_at" | cut -d'T' -f1)
+  local today
+  today=$(date "+%Y-%m-%d")
+
+  if [[ "$pause_date" != "$today" ]]; then
+    # Different day, check how many days
+    local pause_epoch today_epoch days_diff
+
+    # macOS uses -j -f, Linux uses -d
+    if [[ "$(uname)" == "Darwin" ]]; then
+      pause_epoch=$(date -j -f "%Y-%m-%d" "$pause_date" "+%s" 2>/dev/null || echo 0)
+      today_epoch=$(date "+%s")
+    else
+      pause_epoch=$(date -d "$pause_date" "+%s" 2>/dev/null || echo 0)
+      today_epoch=$(date "+%s")
+    fi
+
+    if [[ "$pause_epoch" -gt 0 ]]; then
+      days_diff=$(( (today_epoch - pause_epoch) / 86400 ))
+
+      if [[ "$days_diff" -gt 7 ]]; then
+        echo "stale_7d"
+      elif [[ "$days_diff" -gt 1 ]]; then
+        echo "stale_24h"
+      fi
+    fi
+  fi
+}
+
+# --- Main Validation ---
+
+echo "Validating plan consistency..." >&2
+
+# Get TODO lists
+ROADMAP_TODOS=$(get_roadmap_todos)
+QUEUE_TODOS=$(get_queue_todos)
+
+# Find orphan TODOs (in queue but not roadmap)
+if [[ -n "$QUEUE_TODOS" ]] && [[ -n "$ROADMAP_TODOS" ]]; then
+  while IFS= read -r todo; do
+    if ! echo "$ROADMAP_TODOS" | grep -q "^$todo$"; then
+      ORPHANS+=("$todo")
+    fi
+  done <<< "$QUEUE_TODOS"
+fi
+
+# Find missing TODOs (in roadmap but not queue)
+if [[ -n "$ROADMAP_TODOS" ]] && [[ -n "$QUEUE_TODOS" ]]; then
+  while IFS= read -r todo; do
+    if ! echo "$QUEUE_TODOS" | grep -q "^$todo$"; then
+      MISSING+=("$todo")
+    fi
+  done <<< "$ROADMAP_TODOS"
+fi
+
+# Check for circular dependencies
+HAS_CYCLES=$(check_circular_deps)
+
+# Validate depends_on references
+DEPS=$(get_dependencies)
+if [[ -n "$DEPS" ]]; then
+  while read -r dep_todo dependent_todo; do
+    if ! echo "$ROADMAP_TODOS" | grep -q "^$dep_todo$"; then
+      INVALID_DEPS+=("$dependent_todo references invalid $dep_todo")
+    fi
+  done <<< "$DEPS"
+fi
+
+# Check stale state
+STALE_STATE=$(check_stale_state)
+
+# --- Generate Output ---
+
+# Convert arrays to JSON
+orphans_json=$(printf '%s\n' "${ORPHANS[@]}" | jq -R . | jq -s .)
+missing_json=$(printf '%s\n' "${MISSING[@]}" | jq -R . | jq -s .)
+invalid_deps_json=$(printf '%s\n' "${INVALID_DEPS[@]}" | jq -R . | jq -s .)
+
+# Handle empty arrays
+[[ "$orphans_json" == "null" ]] && orphans_json="[]"
+[[ "$missing_json" == "null" ]] && missing_json="[]"
+[[ "$invalid_deps_json" == "null" ]] && invalid_deps_json="[]"
+
+# Determine overall status
+STATUS="pass"
+if [[ ${#ORPHANS[@]} -gt 0 ]] || [[ ${#INVALID_DEPS[@]} -gt 0 ]] || [[ "$HAS_CYCLES" == "true" ]]; then
+  STATUS="fail"
+elif [[ ${#MISSING[@]} -gt 0 ]] || [[ -n "$STALE_STATE" ]]; then
+  STATUS="warn"
+fi
+
+# Write results
+cat << EOF > "$OUTPUT_FILE"
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "status": "$STATUS",
+  "orphan_todos": $orphans_json,
+  "missing_todos": $missing_json,
+  "invalid_dependencies": $invalid_deps_json,
+  "has_circular_deps": $HAS_CYCLES,
+  "stale_state": "${STALE_STATE:-null}",
+  "roadmap_todo_count": $(echo "$ROADMAP_TODOS" | grep -c . || echo 0),
+  "queue_todo_count": $(echo "$QUEUE_TODOS" | grep -c . || echo 0)
+}
+EOF
+
+# Output results to stdout for /doctor
+cat "$OUTPUT_FILE"
+
+# Exit with appropriate code
+case "$STATUS" in
+  pass) exit 0 ;;
+  warn) exit 1 ;;
+  fail) exit 2 ;;
+esac

package/config/hooks/verify-criteria.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Stop hook helper - Extracts TODO criteria for agent verification
+#
+# This script reads the current TODO and outputs context for the agent hook
+# to verify that acceptance criteria have been met.
+#
+# Used by the Stop agent hook to get criteria context.
+
+# Check if we're in a codecruise project
+if [[ ! -f "progress.yaml" ]]; then
+  echo "Not in a codecruise project"
+  exit 0
+fi
+
+# Get current TODO ID
+CURRENT_TODO=$(grep -A5 "current:" progress.yaml | grep "todo:" | sed 's/.*todo: //' | tr -d ' "' || echo "")
+
+if [[ -z "$CURRENT_TODO" || "$CURRENT_TODO" == "null" ]]; then
+  echo "No active TODO"
+  exit 0
+fi
+
+# Find the roadmap file containing this TODO
+ROADMAP_FILE=$(grep -rl "id: $CURRENT_TODO" roadmap/ 2>/dev/null | head -1 || echo "")
+
+if [[ -z "$ROADMAP_FILE" ]]; then
+  echo "TODO $CURRENT_TODO not found in roadmap/"
+  exit 0
+fi
+
+# Extract TODO block with criteria
+echo "=== Current TODO: $CURRENT_TODO ==="
+echo ""
+
+# Use awk to extract the TODO block
+awk "/id: $CURRENT_TODO/,/^[[:space:]]*- id:/" "$ROADMAP_FILE" | head -n -1
+
+echo ""
+echo "=== Verification Checklist ==="
+echo ""
+echo "Check each criterion above against the current codebase:"
+echo "1. Read the files listed in 'files:' section"
+echo "2. Verify each item in 'criteria:' is implemented"
+echo "3. Verify each item in 'tests:' has a passing test"
+echo ""
+echo "Return {\"ok\": true} if ALL criteria met, or {\"ok\": false, \"reason\": \"what's missing\"}"

package/config/hooks/verify-todo-completion.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# Stop hook - Verifies TODO completion before allowing Claude to stop
+#
+# P0 Enforcement: Prevents "false done" by requiring:
+# 1. Tests exist for implementation files
+# 2. All tests pass
+# 3. Lint passes
+# 4. Typecheck passes (if TypeScript)
+#
+# Configuration (highest to lowest priority):
+# 1. Command flag: /run --enforce=off
+# 2. Project: .claude/settings.json → codecruise.enforce_quality
+# 3. User: ~/.claude/settings.json → codecruise.enforce_quality
+# 4. Default: strict
+
+set -e
+
+# 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() { :; }
+fi
+
+INPUT=$(cat)
+
+# Get enforcement mode from settings hierarchy
+ENFORCE_MODE=$(get_enforce_mode "quality")
+
+# If enforcement is off, allow stop
+if [[ "$ENFORCE_MODE" == "off" ]]; then
+  exit 0
+fi
+
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+
+# Prevent infinite loop - if we already triggered continuation, allow stop
+if [[ "$STOP_HOOK_ACTIVE" == "true" ]]; then
+  exit 0
+fi
+
+# Check if we're in a codecruise execution context
+if [[ ! -f "progress.yaml" ]]; then
+  exit 0
+fi
+
+# Get current TODO from progress.yaml
+CURRENT_TODO=$(grep -A1 "current:" progress.yaml | grep "todo:" | sed 's/.*todo: //' | tr -d ' "' || echo "")
+
+# If no current TODO, allow stop
+if [[ -z "$CURRENT_TODO" || "$CURRENT_TODO" == "null" ]]; then
+  exit 0
+fi
+
+# Get execution status
+EXEC_STATUS=$(grep "status:" progress.yaml | head -1 | sed 's/.*status: //' | tr -d ' "' || echo "")
+
+# Only enforce during active execution
+if [[ "$EXEC_STATUS" != "running" && "$EXEC_STATUS" != "in_progress" ]]; then
+  exit 0
+fi
+
+VERIFY_DIR=".codecruise/verification"
+SUMMARY_FILE="$VERIFY_DIR/summary.json"
+
+# Run verification if summary doesn't exist or is stale (> 2 min old)
+if [[ ! -f "$SUMMARY_FILE" ]] || [[ $(find "$SUMMARY_FILE" -mmin +2 2>/dev/null) ]]; then
+  if [[ -f ".claude/hooks/capture-verification.sh" ]]; then
+    bash .claude/hooks/capture-verification.sh 2>/dev/null || true
+  elif [[ -f "$HOME/.claude/hooks/capture-verification.sh" ]]; then
+    bash "$HOME/.claude/hooks/capture-verification.sh" 2>/dev/null || true
+  fi
+fi
+
+# Check verification results
+if [[ -f "$SUMMARY_FILE" ]]; then
+  LINT_EXIT=$(jq -r '.lint.exit_code // -1' "$SUMMARY_FILE")
+  TSC_EXIT=$(jq -r '.typecheck.exit_code // -1' "$SUMMARY_FILE")
+  TEST_EXIT=$(jq -r '.tests.exit_code // -1' "$SUMMARY_FILE")
+  TEST_FAILED=$(jq -r '.tests.failed // 0' "$SUMMARY_FILE")
+
+  FAILURES=""
+
+  # Check lint (skip if -1 meaning not configured)
+  if [[ "$LINT_EXIT" != "-1" && "$LINT_EXIT" != "0" ]]; then
+    FAILURES="$FAILURES lint"
+  fi
+
+  # Check typecheck (skip if -1 meaning not configured)
+  if [[ "$TSC_EXIT" != "-1" && "$TSC_EXIT" != "0" ]]; then
+    FAILURES="$FAILURES typecheck"
+  fi
+
+  # Check tests (skip if -1 meaning not configured)
+  if [[ "$TEST_EXIT" != "-1" && "$TEST_EXIT" != "0" ]]; then
+    FAILURES="$FAILURES tests"
+  fi
+
+  # Check for failed tests even if exit was 0
+  if [[ "$TEST_FAILED" != "0" && "$TEST_FAILED" != "null" ]]; then
+    FAILURES="$FAILURES tests($TEST_FAILED failed)"
+  fi
+
+  if [[ -n "$FAILURES" ]]; then
+    if [[ "$ENFORCE_MODE" == "ask" ]]; then
+      track_enforcement "quality_ask" "Failed:$FAILURES for $CURRENT_TODO" "verify-todo-completion"
+      cat <<EOF
+{
+  "decision": "ask",
+  "reason": "Quality gates failed:$FAILURES. Continue anyway and mark TODO $CURRENT_TODO complete?"
+}
+EOF
+    else
+      track_enforcement "quality_block" "Failed:$FAILURES for $CURRENT_TODO" "verify-todo-completion"
+      cat <<EOF
+{
+  "decision": "block",
+  "reason": "Quality gates failed:$FAILURES. Fix issues before completing TODO $CURRENT_TODO. Run 'pnpm quality' or check .codecruise/verification/ for details."
+}
+EOF
+    fi
+    exit 0
+  fi
+fi
+
+# All gates passed, allow stop
+exit 0

package/config/rules/comments.md

@@ -0,0 +1,25 @@
+# Comments
+
+Document WHY, not WHAT. Code shows what it does; comments explain why it matters.
+
+## JSDoc: When Required
+
+- Exported functions with non-obvious behavior
+- Security/PII/money handling
+- Module entry points (`index.ts`)
+- Complex algorithms, edge cases
+
+## JSDoc: Skip
+
+- Obvious methods (`getUserById`)
+- Types with clear property names
+- Private helpers, simple getters
+
+## Inline Comments
+
+```typescript
+// Design decision D-073: Using optimistic locking
+// TODO(JIRA-123): Remove after v2.0 migration
+```
+
+Avoid: obvious comments, changelog, commented-out code, decorative boxes.