ai-core-framework 0.1.0

package/core/scripts/validate-state.sh

@@ -0,0 +1,611 @@
+#!/usr/bin/env bash
+# scripts/validate-state.sh
+#
+# Validates ticket state machine integrity per RULE 06 (Approval Gates).
+#
+# Checks:
+# 1. JSON validity
+# 2. Required fields present
+# 3. State value valid
+# 4. State transitions follow allowed matrix
+# 5. State history complete (no gaps)
+# 6. State history entries valid (have command + agent)
+# 7. No zombie tickets (alerts only)
+#
+# Usage:
+#   bash scripts/validate-state.sh           # Validate all tickets
+#   bash scripts/validate-state.sh TICKET-042  # Validate one
+#
+# Exit codes:
+#   0: All valid
+#   1: Validation failures
+#   2: Script error
+#
+# Last updated: 2026-04-18
+
+set -euo pipefail
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# ============================================================
+# Config
+# ============================================================
+TICKETS_DIR="project/tickets"
+BUGS_DIR="project/bugs"
+BACKLOG_FILE="project/backlog/backlog.json"
+SCHEMA_FILE="core/config/ticket.schema.json"
+
+# ============================================================
+# Allowed state transitions matrix (per RULE 06)
+# Format: "FROM_STATE TO_STATE"
+# ============================================================
+declare -a ALLOWED_TRANSITIONS=(
+  "null DRAFT"
+  "DRAFT GROOMED"
+  "DRAFT BLOCKED"
+  "DRAFT CANCELLED"
+  "GROOMED READY"
+  "GROOMED DRAFT"
+  "GROOMED BLOCKED"
+  "GROOMED CANCELLED"
+  "READY IN_PROGRESS"
+  "READY BLOCKED"
+  "READY GROOMED"
+  "READY CANCELLED"
+  "IN_PROGRESS IN_REVIEW"
+  "IN_PROGRESS BLOCKED"
+  "IN_PROGRESS CANCELLED"
+  "IN_REVIEW IN_PROGRESS"
+  "IN_REVIEW QA"
+  "IN_REVIEW BLOCKED"
+  "QA DONE"
+  "QA IN_PROGRESS"
+  "QA BLOCKED"
+  "BLOCKED DRAFT"
+  "BLOCKED GROOMED"
+  "BLOCKED READY"
+  "BLOCKED IN_PROGRESS"
+  "BLOCKED IN_REVIEW"
+  "BLOCKED QA"
+  "BLOCKED CANCELLED"
+)
+
+VALID_STATES=("DRAFT" "GROOMED" "READY" "IN_PROGRESS" "IN_REVIEW" "QA" "DONE" "BLOCKED" "CANCELLED")
+
+# ============================================================
+# Helpers
+# ============================================================
+log_info()    { echo -e "${BLUE}ℹ${NC}  $1"; }
+log_pass()    { echo -e "${GREEN}✓${NC}  $1"; }
+log_warn()    { echo -e "${YELLOW}⚠${NC}  $1"; }
+log_fail()    { echo -e "${RED}✗${NC}  $1"; }
+
+is_valid_state() {
+  local state="$1"
+  for s in "${VALID_STATES[@]}"; do
+    [ "$s" = "$state" ] && return 0
+  done
+  return 1
+}
+
+is_valid_transition() {
+  local from="$1"
+  local to="$2"
+  local pair="$from $to"
+
+  for allowed in "${ALLOWED_TRANSITIONS[@]}"; do
+    [ "$allowed" = "$pair" ] && return 0
+  done
+  return 1
+}
+
+parse_rfc3339_epoch() {
+  local timestamp="$1"
+
+  # GNU date, Linux
+  if date -d "$timestamp" +%s >/dev/null 2>&1; then
+    date -d "$timestamp" +%s
+    return 0
+  fi
+
+  # BSD date, macOS, normalize trailing Z
+  local normalized
+  normalized=$(printf '%s' "$timestamp" | sed 's/Z$/+0000/' | sed -E 's/([+-][0-9]{2}):([0-9]{2})$/\1\2/')
+  if date -j -f "%Y-%m-%dT%H:%M:%S%z" "$normalized" +%s >/dev/null 2>&1; then
+    date -j -f "%Y-%m-%dT%H:%M:%S%z" "$normalized" +%s
+    return 0
+  fi
+
+  return 1
+}
+
+# ============================================================
+# Validate single ticket
+# ============================================================
+validate_ticket() {
+  local ticket_file="$1"
+  local ticket_id
+  ticket_id=$(basename "$ticket_file" .json)
+
+  local errors=0
+  local warnings=0
+
+  # Check 1: Valid JSON
+  if ! jq empty "$ticket_file" 2>/dev/null; then
+    log_fail "$ticket_id: Invalid JSON"
+    return 1
+  fi
+
+  # Check 2: Required fields
+  local required_fields=("id" "title" "type" "status" "created_at" "state_history")
+  for field in "${required_fields[@]}"; do
+    if ! jq -e ".$field" "$ticket_file" > /dev/null 2>&1; then
+      log_fail "$ticket_id: Missing required field '$field'"
+      errors=$((errors + 1))
+    fi
+  done
+
+  if [ "$errors" -gt 0 ]; then
+    return 1
+  fi
+
+  # Check 3: ID matches filename
+  local id_in_file
+  id_in_file=$(jq -r '.id' "$ticket_file")
+  if [ "$id_in_file" != "$ticket_id" ]; then
+    log_fail "$ticket_id: ID mismatch ('$id_in_file' in file, '$ticket_id' in filename)"
+    errors=$((errors + 1))
+  fi
+
+  # Check 4: Status is valid
+  local status
+  status=$(jq -r '.status' "$ticket_file")
+  if ! is_valid_state "$status"; then
+    log_fail "$ticket_id: Invalid status '$status'"
+    log_fail "  Valid: ${VALID_STATES[*]}"
+    errors=$((errors + 1))
+  fi
+
+  # Check 5: State history not empty
+  local history_count
+  history_count=$(jq '.state_history | length' "$ticket_file")
+  if [ "$history_count" -eq 0 ]; then
+    log_fail "$ticket_id: Empty state_history (RULE AG-008)"
+    errors=$((errors + 1))
+    return 1
+  fi
+
+  # Check 6: Each state history entry has required fields
+  local entry_errors=0
+  for i in $(seq 0 $((history_count - 1))); do
+    local entry
+    entry=$(jq ".state_history[$i]" "$ticket_file")
+
+    for field in "to_state" "at" "by_agent"; do
+      if ! echo "$entry" | jq -e ".$field" > /dev/null 2>&1; then
+        log_fail "$ticket_id: state_history[$i] missing '$field'"
+        entry_errors=$((entry_errors + 1))
+      fi
+    done
+
+    # by_command optional only for first entry
+    if [ "$i" -gt 0 ]; then
+      if ! echo "$entry" | jq -e ".by_command" > /dev/null 2>&1; then
+        log_warn "$ticket_id: state_history[$i] missing 'by_command' (recommended per RULE AG-002)"
+        warnings=$((warnings + 1))
+      fi
+    fi
+  done
+
+  if [ "$entry_errors" -gt 0 ]; then
+    errors=$((errors + entry_errors))
+  fi
+
+  # Check 7: All transitions valid (per matrix)
+  local transition_errors=0
+  for i in $(seq 0 $((history_count - 1))); do
+    local from_state to_state
+    from_state=$(jq -r ".state_history[$i].from_state // \"null\"" "$ticket_file")
+    to_state=$(jq -r ".state_history[$i].to_state" "$ticket_file")
+
+    if ! is_valid_transition "$from_state" "$to_state"; then
+      log_fail "$ticket_id: Invalid transition #$i: $from_state → $to_state (RULE AG-001)"
+      transition_errors=$((transition_errors + 1))
+    fi
+  done
+
+  if [ "$transition_errors" -gt 0 ]; then
+    errors=$((errors + transition_errors))
+  fi
+
+  # Check 8: Current status matches last history entry
+  local last_state
+  last_state=$(jq -r '.state_history[-1].to_state' "$ticket_file")
+  if [ "$status" != "$last_state" ]; then
+    log_fail "$ticket_id: Current status '$status' doesn't match last history entry '$last_state' (RULE AG-008)"
+    errors=$((errors + 1))
+  fi
+
+  # Check 9: Estimate present if past GROOMED
+  local non_estimate_states=("DRAFT" "BLOCKED" "CANCELLED")
+  local needs_estimate=true
+  for s in "${non_estimate_states[@]}"; do
+    [ "$s" = "$status" ] && needs_estimate=false
+  done
+
+  if [ "$needs_estimate" = true ]; then
+    if ! jq -e '.estimate.story_points' "$ticket_file" > /dev/null 2>&1; then
+      log_warn "$ticket_id: No estimate (status=$status, expected per RULE GR-001)"
+      warnings=$((warnings + 1))
+    fi
+  fi
+
+  # Check 10: Zombie detection
+  local updated_at
+  updated_at=$(jq -r '.updated_at // .created_at' "$ticket_file")
+  if [ -n "$updated_at" ] && [ "$updated_at" != "null" ]; then
+    local now_epoch updated_epoch days_old
+    now_epoch=$(date +%s)
+    updated_epoch=$(parse_rfc3339_epoch "$updated_at" 2>/dev/null || echo "$now_epoch")
+    days_old=$(( (now_epoch - updated_epoch) / 86400 ))
+
+    local threshold
+    case "$status" in
+      DRAFT) threshold=14 ;;
+      GROOMED) threshold=30 ;;
+      READY) threshold=21 ;;
+      IN_PROGRESS) threshold=10 ;;
+      IN_REVIEW) threshold=5 ;;
+      QA) threshold=7 ;;
+      BLOCKED) threshold=30 ;;
+      *) threshold=9999 ;;
+    esac
+
+    if [ "$days_old" -gt "$threshold" ]; then
+      log_warn "$ticket_id: Zombie ticket, status=$status, idle ${days_old}d (threshold: ${threshold}d, RULE AG-007)"
+      warnings=$((warnings + 1))
+    fi
+  fi
+
+  # Check 11: Machine-readable DoD gates for DONE tickets
+  if [ "$status" = "DONE" ]; then
+    for field in code_complete tests_passed docs_updated review_approved qa_verified release_notes_updated security_checked; do
+      if [ "$(jq -r ".dod_checklist.$field // false" "$ticket_file")" != "true" ]; then
+        log_fail "$ticket_id: DONE requires dod_checklist.$field=true (RULE DOD-002)"
+        errors=$((errors + 1))
+      fi
+    done
+
+    if ! jq -e '.completed_at' "$ticket_file" >/dev/null 2>&1 || [ "$(jq -r '.completed_at // empty' "$ticket_file")" = "" ]; then
+      log_fail "$ticket_id: DONE requires completed_at"
+      errors=$((errors + 1))
+    fi
+
+    if ! jq -e '.pr_url' "$ticket_file" >/dev/null 2>&1 || [ "$(jq -r '.pr_url // empty' "$ticket_file")" = "" ]; then
+      log_fail "$ticket_id: DONE requires pr_url"
+      errors=$((errors + 1))
+    fi
+
+    if [ "$(jq -r '.qa_evidence.required // true' "$ticket_file")" = "true" ]; then
+      local qa_path
+      qa_path=$(jq -r '.qa_evidence.path // empty' "$ticket_file")
+      if [ -z "$qa_path" ] || [ ! -e "$qa_path" ]; then
+        log_fail "$ticket_id: DONE requires qa_evidence.path pointing to an existing file"
+        errors=$((errors + 1))
+      fi
+    fi
+  fi
+
+  # Check 12: Documentation evidence paths are real when declared
+  while IFS= read -r doc_path; do
+    [ -z "$doc_path" ] && continue
+    if [ ! -e "$doc_path" ]; then
+      log_fail "$ticket_id: documentation path does not exist: $doc_path"
+      errors=$((errors + 1))
+    fi
+  done < <(jq -r '.documentation.paths[]? // empty' "$ticket_file")
+
+  if [ "$(jq -r '.adr.required // false' "$ticket_file")" = "true" ]; then
+    local adr_path
+    adr_path=$(jq -r '.adr.path // empty' "$ticket_file")
+    if [ -z "$adr_path" ] || [ ! -e "$adr_path" ]; then
+      log_fail "$ticket_id: ADR required but adr.path is missing or does not exist"
+      errors=$((errors + 1))
+    fi
+  fi
+
+  if [ "$(jq -r '.runbook.required // false' "$ticket_file")" = "true" ]; then
+    local runbook_path
+    runbook_path=$(jq -r '.runbook.path // empty' "$ticket_file")
+    if [ -z "$runbook_path" ] || [ ! -e "$runbook_path" ]; then
+      log_fail "$ticket_id: runbook required but runbook.path is missing or does not exist"
+      errors=$((errors + 1))
+    fi
+  fi
+
+  # Result
+  if [ "$errors" -eq 0 ]; then
+    if [ "$warnings" -gt 0 ]; then
+      log_pass "$ticket_id ($warnings warning$([ $warnings -eq 1 ] || echo s))"
+    else
+      log_pass "$ticket_id"
+    fi
+    return 0
+  else
+    return 1
+  fi
+}
+
+# ============================================================
+# Validate backlog references
+# ============================================================
+validate_backlog() {
+  if [ ! -f "$BACKLOG_FILE" ]; then
+    log_warn "No backlog file: $BACKLOG_FILE"
+    return 0
+  fi
+
+  if ! jq empty "$BACKLOG_FILE" 2>/dev/null; then
+    log_fail "Backlog: Invalid JSON"
+    return 1
+  fi
+
+  local errors=0
+
+  for field in "version" "updated_at" "updated_by" "items"; do
+    if ! jq -e ".$field" "$BACKLOG_FILE" > /dev/null 2>&1; then
+      log_fail "Backlog: Missing required field '$field'"
+      errors=$((errors + 1))
+    fi
+  done
+
+  local duplicate_ids
+  duplicate_ids=$(jq -r '.items[].ticket_id' "$BACKLOG_FILE" | sort | uniq -d | tr '\n' ' ')
+  if [ -n "$duplicate_ids" ]; then
+    log_fail "Backlog: Duplicate ticket IDs: $duplicate_ids"
+    errors=$((errors + 1))
+  fi
+
+  local duplicate_ranks
+  duplicate_ranks=$(jq -r '.items[].rank' "$BACKLOG_FILE" | sort -n | uniq -d | tr '\n' ' ')
+  if [ -n "$duplicate_ranks" ]; then
+    log_fail "Backlog: Duplicate ranks: $duplicate_ranks"
+    errors=$((errors + 1))
+  fi
+
+  local item_count
+  item_count=$(jq '.items | length' "$BACKLOG_FILE")
+
+  if [ "$item_count" -gt 0 ]; then
+    local expected=1
+    while IFS= read -r rank; do
+      if [ "$rank" -ne "$expected" ]; then
+        log_fail "Backlog: ranks must be continuous starting at 1 (expected $expected, got $rank)"
+        errors=$((errors + 1))
+        break
+      fi
+      expected=$((expected + 1))
+    done < <(jq -r '.items[].rank' "$BACKLOG_FILE" | sort -n)
+  fi
+
+  while IFS= read -r ticket_id; do
+    if [ ! -f "$TICKETS_DIR/$ticket_id.json" ]; then
+      log_fail "Backlog: References missing ticket $ticket_id"
+      errors=$((errors + 1))
+      continue
+    fi
+
+    local backlog_priority ticket_priority status rank
+    backlog_priority=$(jq -r --arg id "$ticket_id" '.items[] | select(.ticket_id == $id) | .priority // empty' "$BACKLOG_FILE")
+    ticket_priority=$(jq -r '.priority // empty' "$TICKETS_DIR/$ticket_id.json")
+    status=$(jq -r '.status // empty' "$TICKETS_DIR/$ticket_id.json")
+    rank=$(jq -r --arg id "$ticket_id" '.items[] | select(.ticket_id == $id) | .rank' "$BACKLOG_FILE")
+
+    if [ -n "$backlog_priority" ] && [ -n "$ticket_priority" ] && [ "$backlog_priority" != "$ticket_priority" ]; then
+      log_fail "Backlog: $ticket_id priority mismatch (backlog=$backlog_priority, ticket=$ticket_priority)"
+      errors=$((errors + 1))
+    fi
+
+    if { [ "$status" = "DONE" ] || [ "$status" = "CANCELLED" ]; } && [ "$rank" -le 10 ]; then
+      log_fail "Backlog: $ticket_id is $status but still ranked in top 10"
+      errors=$((errors + 1))
+    fi
+
+    if [ "$status" = "BLOCKED" ] && ! jq -e '.unblock_plan // .blocker.unblock_plan // .comments[]? | select((.text // "") | test("unblock|blocked|dependency"; "i"))' "$TICKETS_DIR/$ticket_id.json" >/dev/null 2>&1; then
+      log_fail "Backlog: $ticket_id is BLOCKED without machine-readable unblock_plan or blocker comment"
+      errors=$((errors + 1))
+    fi
+
+    while IFS= read -r dependency_id; do
+      [ -z "$dependency_id" ] && continue
+      local dependency_rank
+      dependency_rank=$(jq -r --arg id "$dependency_id" '.items[]? | select(.ticket_id == $id) | .rank // empty' "$BACKLOG_FILE")
+      if [ -n "$dependency_rank" ] && [ "$dependency_rank" -gt "$rank" ]; then
+        log_fail "Backlog: $ticket_id rank $rank depends on $dependency_id rank $dependency_rank; dependency must be ranked first"
+        errors=$((errors + 1))
+      fi
+    done < <(jq -r '.dependencies.blocked_by[]? // empty' "$TICKETS_DIR/$ticket_id.json")
+  done < <(jq -r '.items[].ticket_id' "$BACKLOG_FILE")
+
+  if [ "$errors" -eq 0 ]; then
+    log_pass "Backlog"
+    return 0
+  fi
+
+  return 1
+}
+
+# ============================================================
+# Validate release governance records
+# ============================================================
+validate_releases() {
+  local releases_dir="project/releases"
+
+  if [ ! -d "$releases_dir" ]; then
+    return 0
+  fi
+
+  local errors=0
+  local checked=0
+
+  while IFS= read -r -d '' release_file; do
+    checked=$((checked + 1))
+    local release_id
+    release_id=$(basename "$release_file" .json)
+
+    if ! jq empty "$release_file" 2>/dev/null; then
+      log_fail "Release $release_id: Invalid JSON"
+      errors=$((errors + 1))
+      continue
+    fi
+
+    for field in version status created_at created_by scope approvals rollback_plan qa security known_issues; do
+      if ! jq -e ".$field" "$release_file" >/dev/null 2>&1; then
+        log_fail "Release $release_id: Missing required field '$field'"
+        errors=$((errors + 1))
+      fi
+    done
+
+    local release_status
+    release_status=$(jq -r '.status // empty' "$release_file")
+
+    if [ "$release_status" = "READY" ] || [ "$release_status" = "RELEASED" ]; then
+      for approval in tech_lead qa release_owner; do
+        if [ "$(jq -r ".approvals.$approval.approved // false" "$release_file")" != "true" ]; then
+          log_fail "Release $release_id: approvals.$approval.approved must be true when status=$release_status"
+          errors=$((errors + 1))
+        fi
+      done
+
+      if [ "$(jq -r '.rollback_plan.verified // false' "$release_file")" != "true" ]; then
+        log_fail "Release $release_id: rollback_plan.verified must be true when status=$release_status"
+        errors=$((errors + 1))
+      fi
+
+      if [ "$(jq -r '.security.dependency_audit_passed // false' "$release_file")" != "true" ] ||
+         [ "$(jq -r '.security.sast_passed // false' "$release_file")" != "true" ]; then
+        log_fail "Release $release_id: security dependency audit and SAST must pass when status=$release_status"
+        errors=$((errors + 1))
+      fi
+    fi
+
+    if [ "$release_status" = "RELEASED" ] &&
+       [ "$(jq -r '.qa.post_release_smoke_required // true' "$release_file")" = "true" ] &&
+       [ "$(jq -r '.qa.post_release_smoke_passed // false' "$release_file")" != "true" ]; then
+      log_fail "Release $release_id: RELEASED requires post-release smoke test evidence"
+      errors=$((errors + 1))
+    fi
+
+    while IFS= read -r ticket_id; do
+      [ -z "$ticket_id" ] && continue
+      if [ ! -f "$TICKETS_DIR/$ticket_id.json" ]; then
+        log_fail "Release $release_id: references missing ticket $ticket_id"
+        errors=$((errors + 1))
+      elif [ "$(jq -r '.status' "$TICKETS_DIR/$ticket_id.json")" != "DONE" ]; then
+        log_fail "Release $release_id: includes $ticket_id but ticket is not DONE"
+        errors=$((errors + 1))
+      fi
+    done < <(jq -r '.scope.tickets[]? // empty' "$release_file")
+
+    local high_known_without_approval
+    high_known_without_approval=$(jq -r '.known_issues[]? | select((.severity == "SEV-1" or .severity == "SEV-2") and ((.approver // "") == "")) | .id' "$release_file" | tr '\n' ' ')
+    if [ -n "$high_known_without_approval" ]; then
+      log_fail "Release $release_id: high severity known issues require approver: $high_known_without_approval"
+      errors=$((errors + 1))
+    fi
+  done < <(find "$releases_dir" -name '*.json' -type f -print0)
+
+  if [ "$checked" -gt 0 ] && [ "$errors" -eq 0 ]; then
+    log_pass "Releases"
+  fi
+
+  return "$errors"
+}
+
+# ============================================================
+# Main
+# ============================================================
+echo ""
+echo "════════════════════════════════════════════════════════"
+echo "  🔍 Validating ticket state machine"
+echo "════════════════════════════════════════════════════════"
+echo ""
+
+# Verify dependencies
+if ! command -v jq &> /dev/null; then
+  log_fail "jq not installed. Install: apt-get install jq | brew install jq"
+  exit 2
+fi
+
+# Verify directories
+if [ ! -d "$TICKETS_DIR" ]; then
+  log_warn "No tickets directory: $TICKETS_DIR"
+  exit 0
+fi
+
+# Determine which tickets to validate
+TICKETS_TO_CHECK=()
+if [ $# -gt 0 ]; then
+  for arg in "$@"; do
+    file="$TICKETS_DIR/$arg.json"
+    if [ -f "$file" ]; then
+      TICKETS_TO_CHECK+=("$file")
+    else
+      log_fail "Ticket not found: $arg"
+      exit 1
+    fi
+  done
+else
+  while IFS= read -r -d '' file; do
+    TICKETS_TO_CHECK+=("$file")
+  done < <(find "$TICKETS_DIR" -name '*.json' -print0)
+fi
+
+if [ ${#TICKETS_TO_CHECK[@]} -eq 0 ]; then
+  log_warn "No tickets to validate"
+  exit 0
+fi
+
+log_info "Validating ${#TICKETS_TO_CHECK[@]} ticket(s)..."
+echo ""
+
+# Run validation
+PASSED=0
+FAILED=0
+for ticket in "${TICKETS_TO_CHECK[@]}"; do
+  if validate_ticket "$ticket"; then
+    PASSED=$((PASSED + 1))
+  else
+    FAILED=$((FAILED + 1))
+  fi
+done
+
+if [ $# -eq 0 ]; then
+  if ! validate_backlog; then
+    FAILED=$((FAILED + 1))
+  fi
+  if ! validate_releases; then
+    FAILED=$((FAILED + 1))
+  fi
+fi
+
+# Summary
+echo ""
+echo "════════════════════════════════════════════════════════"
+if [ "$FAILED" -eq 0 ]; then
+  echo -e "  ${GREEN}✅ All $PASSED ticket(s) valid${NC}"
+  echo "════════════════════════════════════════════════════════"
+  exit 0
+else
+  echo -e "  ${RED}❌ $FAILED of $((PASSED + FAILED)) ticket(s) failed validation${NC}"
+  echo "════════════════════════════════════════════════════════"
+  echo ""
+  echo "Per RULE 06 (Approval Gates), all tickets must follow state machine."
+  echo "See: core/rules/06-approval-gates.md"
+  exit 1
+fi