ai-core-framework 0.1.0

package/core/scripts/validate-docs.sh

@@ -0,0 +1,365 @@
+#!/usr/bin/env bash
+# scripts/validate-docs.sh
+#
+# Enforces documentation and DoD evidence gates from RULE 04 and RULE 08.
+#
+# Usage:
+#   bash scripts/validate-docs.sh
+#   bash scripts/validate-docs.sh --base origin/main
+#   bash scripts/validate-docs.sh --staged
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo -e "${BLUE}i${NC}  $1"; }
+log_pass() { echo -e "${GREEN}+${NC}  $1"; }
+log_warn() { echo -e "${YELLOW}!${NC}  $1"; }
+log_fail() { echo -e "${RED}x${NC}  $1"; }
+
+BASE_REF=""
+MODE="auto"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --base)
+      BASE_REF="${2:-}"
+      shift 2
+      ;;
+    --staged)
+      MODE="staged"
+      shift
+      ;;
+    *)
+      log_fail "Unknown argument: $1"
+      exit 2
+      ;;
+  esac
+done
+
+require_git() {
+  if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    log_fail "Not in a git repository"
+    exit 2
+  fi
+}
+
+get_changed_files() {
+  if [ "$MODE" = "staged" ]; then
+    git diff --cached --name-only --diff-filter=ACMR
+    return 0
+  fi
+
+  if [ -n "$BASE_REF" ]; then
+    git diff --name-only --diff-filter=ACMR "$BASE_REF"...HEAD
+    return 0
+  fi
+
+  local staged_count
+  staged_count=$(git diff --cached --name-only --diff-filter=ACMR | grep -c . || true)
+  if [ "$staged_count" -gt 0 ]; then
+    git diff --cached --name-only --diff-filter=ACMR
+    return 0
+  fi
+
+  local working_count
+  working_count=$(git diff --name-only --diff-filter=ACMR | grep -c . || true)
+  if [ "$working_count" -gt 0 ]; then
+    git diff --name-only --diff-filter=ACMR
+    git ls-files --others --exclude-standard
+    return 0
+  fi
+
+  local default_ref=""
+  for ref in origin/main origin/develop main develop HEAD~1; do
+    if git rev-parse --verify "$ref" >/dev/null 2>&1; then
+      default_ref="$ref"
+      break
+    fi
+  done
+
+  if [ -n "$default_ref" ]; then
+    git diff --name-only --diff-filter=ACMR "$default_ref"...HEAD 2>/dev/null || git diff --name-only --diff-filter=ACMR "$default_ref" HEAD
+  else
+    git ls-files
+  fi
+}
+
+contains_any() {
+  local content="$1"
+  local pattern="$2"
+  echo "$content" | grep -Eq "$pattern"
+}
+
+has_changed_path() {
+  local files="$1"
+  local pattern="$2"
+  echo "$files" | grep -Eq "$pattern"
+}
+
+load_docs_policy() {
+  DOCS_POLICY_FILE="config/docs-policy.json"
+
+  if [ -f "$DOCS_POLICY_FILE" ]; then
+    local extends
+    extends=$(jq -r '.extends // empty' "$DOCS_POLICY_FILE")
+    if [ -n "$extends" ] && [ -f "$extends" ]; then
+      DOCS_POLICY_JSON=$(jq -s '.[0] * .[1]' "$extends" "$DOCS_POLICY_FILE")
+      return 0
+    fi
+
+    DOCS_POLICY_JSON=$(jq '.' "$DOCS_POLICY_FILE")
+    return 0
+  fi
+
+  DOCS_POLICY_FILE="core/config/docs-policy.default.json"
+  DOCS_POLICY_JSON=$(jq '.' "$DOCS_POLICY_FILE")
+}
+
+policy_prefix_regex() {
+  local key="$1"
+  local fallback="$2"
+  local values
+  values=$(printf '%s' "$DOCS_POLICY_JSON" | jq -r --arg key "$key" '.[$key][]? // empty' | sed 's/[.[\*^$()+?{}|]/\\&/g' | tr '\n' '|' | sed 's/|$//')
+
+  if [ -z "$values" ]; then
+    printf '%s' "$fallback"
+    return 0
+  fi
+
+  printf '(^|/)(%s)(/|$)' "$values"
+}
+
+policy_file_regex() {
+  local key="$1"
+  local fallback="$2"
+  local values
+  values=$(printf '%s' "$DOCS_POLICY_JSON" | jq -r --arg key "$key" '.[$key][]? // empty' | sed 's/[.[\*^$()+?{}|]/\\&/g' | tr '\n' '|' | sed 's/|$//')
+
+  if [ -z "$values" ]; then
+    printf '%s' "$fallback"
+    return 0
+  fi
+
+  printf '(^|/)(%s)(/|$)' "$values"
+}
+
+current_ticket_id() {
+  local branch
+  branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+  if [[ "$branch" =~ (TICKET-[0-9]{3,}) ]]; then
+    printf '%s\n' "${BASH_REMATCH[1]}"
+    return 0
+  fi
+
+  echo "$CHANGED_FILES" | grep -Eo 'TICKET-[0-9]{3,}' | head -1 || true
+}
+
+validate_ticket_doc_paths() {
+  local errors=0
+
+  if [ ! -d "project/tickets" ]; then
+    return 0
+  fi
+
+  while IFS= read -r -d '' ticket; do
+    local ticket_id
+    ticket_id=$(jq -r '.id // empty' "$ticket")
+
+    local spec_path plan_path
+    spec_path=$(jq -r '.spec_path // empty' "$ticket")
+    if [ -n "$spec_path" ] && [ ! -e "$spec_path" ]; then
+      log_fail "$ticket_id: spec_path does not exist: $spec_path"
+      errors=$((errors + 1))
+    fi
+
+    plan_path=$(jq -r '.implementation_plan_path // empty' "$ticket")
+    if [ -n "$plan_path" ] && [ ! -e "$plan_path" ]; then
+      log_fail "$ticket_id: implementation_plan_path does not exist: $plan_path"
+      errors=$((errors + 1))
+    fi
+
+    while IFS= read -r path; do
+      [ -z "$path" ] && continue
+      if [ ! -e "$path" ]; then
+        log_fail "$ticket_id: documentation path does not exist: $path"
+        errors=$((errors + 1))
+      fi
+    done < <(jq -r '.documentation.paths[]? // empty' "$ticket")
+
+    local adr_required adr_path
+    adr_required=$(jq -r '.adr.required // false' "$ticket")
+    adr_path=$(jq -r '.adr.path // empty' "$ticket")
+    if [ "$adr_required" = "true" ]; then
+      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
+
+    local runbook_required runbook_path
+    runbook_required=$(jq -r '.runbook.required // false' "$ticket")
+    runbook_path=$(jq -r '.runbook.path // empty' "$ticket")
+    if [ "$runbook_required" = "true" ]; then
+      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
+  done < <(find project/tickets -name '*.json' -type f -print0)
+
+  return "$errors"
+}
+
+validate_done_tickets() {
+  local errors=0
+
+  if [ ! -d "project/tickets" ]; then
+    return 0
+  fi
+
+  while IFS= read -r -d '' ticket; do
+    local status ticket_id
+    status=$(jq -r '.status // empty' "$ticket")
+    [ "$status" = "DONE" ] || continue
+
+    ticket_id=$(jq -r '.id // empty' "$ticket")
+
+    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")" != "true" ]; then
+        log_fail "$ticket_id: DONE requires dod_checklist.$field=true"
+        errors=$((errors + 1))
+      fi
+    done
+
+    if [ "$(jq -r '.documentation.required // false' "$ticket")" = "true" ] &&
+       [ "$(jq -r '.documentation.updated // false' "$ticket")" != "true" ]; then
+      log_fail "$ticket_id: documentation.required=true but documentation.updated is not true"
+      errors=$((errors + 1))
+    fi
+
+    if [ "$(jq -r '.qa_evidence.required // true' "$ticket")" = "true" ]; then
+      local qa_path
+      qa_path=$(jq -r '.qa_evidence.path // empty' "$ticket")
+      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
+  done < <(find project/tickets -name '*.json' -type f -print0)
+
+  return "$errors"
+}
+
+main() {
+  require_git
+
+  if ! command -v jq >/dev/null 2>&1; then
+    log_fail "jq not installed. Install with: brew install jq"
+    exit 2
+  fi
+
+  load_docs_policy
+  CHANGED_FILES="$(get_changed_files || true)"
+
+  echo ""
+  echo "========================================================"
+  echo "  Validating documentation and DoD evidence"
+  echo "========================================================"
+  echo ""
+
+  if [ -z "$CHANGED_FILES" ]; then
+    log_info "No changed files detected; validating ticket evidence only."
+  else
+    log_info "Changed files:"
+    echo "$CHANGED_FILES" | sed 's/^/  - /'
+    echo ""
+  fi
+
+  local errors=0
+  local ticket_id
+  ticket_id=$(current_ticket_id)
+
+  local code_roots_pattern api_paths_pattern migration_paths_pattern setup_paths_pattern architecture_paths_pattern
+  local documentation_paths_pattern api_doc_paths_pattern runbook_paths_pattern setup_doc_paths_pattern adr_paths_pattern
+
+  code_roots_pattern="$(policy_prefix_regex code_roots '(^src/|^lib/|^app/|^pages/|^packages/|^services/|^server/|^api/|^cmd/|^internal/|^pkg/)')"
+  api_paths_pattern="$(policy_prefix_regex api_paths '(^app/api/|^pages/api/|/routes?/|/controllers?/)')|openapi\.(yaml|yml|json)$"
+  migration_paths_pattern="$(policy_prefix_regex migration_paths '(^migrations/|/migrations/|^db/migrate/|^prisma/migrations/)')"
+  setup_paths_pattern="$(policy_file_regex setup_paths '(^package\.json$|^pnpm-lock\.yaml$|^package-lock\.json$|^yarn\.lock$|^Dockerfile$|^docker-compose|^\.env\.example$|^scripts/|^\.github/workflows/)')"
+  architecture_paths_pattern="$(policy_prefix_regex architecture_paths '(^src/(auth|cache|db|database|security)/|^lib/(auth|cache|db|database|security)/|^infra/|^terraform/|^k8s/|^prisma/schema\.prisma$)')"
+  documentation_paths_pattern="$(policy_file_regex documentation_paths '(^docs/|^README\.md$|^CHANGELOG\.md$|^RELEASE-NOTES\.md$|^openapi\.(yaml|yml|json)$|^docs/project/api/)')"
+  api_doc_paths_pattern="$(policy_file_regex api_doc_paths '(^docs/project/api/|^openapi\.(yaml|yml|json)$|^README\.md$)')"
+  runbook_paths_pattern="$(policy_file_regex runbook_paths '(^docs/runtime/runbooks/|^docs/runtime/technical/)')|migration.*\.(md|txt)$"
+  setup_doc_paths_pattern="$(policy_file_regex setup_doc_paths '(^README\.md$|^docs/runtime/technical/|^docs/runtime/runbooks/)')"
+  adr_paths_pattern="$(policy_file_regex adr_paths '^docs/runtime/adr/')"
+
+  local code_pattern="${code_roots_pattern}.*\.(ts|tsx|js|jsx|py|go|java|rb|rs|kt|swift|c|cpp|h)$"
+  local test_pattern='(\.test\.|\.spec\.|/__tests__/|^tests/)'
+
+  if has_changed_path "$CHANGED_FILES" "$code_pattern" && [ -z "$ticket_id" ]; then
+    log_fail "Code changed but no TICKET-XXX found in branch name or changed state files"
+    errors=$((errors + 1))
+  fi
+
+  if has_changed_path "$CHANGED_FILES" "$code_pattern"; then
+    local non_test_code
+    non_test_code=$(echo "$CHANGED_FILES" | grep -E "$code_pattern" | grep -Ev "$test_pattern" || true)
+    if [ -n "$non_test_code" ] &&
+       ! has_changed_path "$CHANGED_FILES" "$documentation_paths_pattern"; then
+      log_fail "Production code changed but no docs/release note path changed"
+      log_fail "Expected one of: docs/, README.md, CHANGELOG.md, RELEASE-NOTES.md, openapi.*, docs/project/api/"
+      errors=$((errors + 1))
+    fi
+  fi
+
+  if has_changed_path "$CHANGED_FILES" "$api_paths_pattern" &&
+     ! has_changed_path "$CHANGED_FILES" "$api_doc_paths_pattern"; then
+    log_fail "API route/interface changed but API docs were not updated"
+    errors=$((errors + 1))
+  fi
+
+  if has_changed_path "$CHANGED_FILES" "$migration_paths_pattern" &&
+     ! has_changed_path "$CHANGED_FILES" "$runbook_paths_pattern"; then
+    log_fail "Migration changed but no runbook or migration notes changed"
+    errors=$((errors + 1))
+  fi
+
+  if has_changed_path "$CHANGED_FILES" "$setup_paths_pattern" &&
+     ! has_changed_path "$CHANGED_FILES" "$setup_doc_paths_pattern"; then
+    log_fail "Setup/workflow/dependency changed but README or technical docs were not updated"
+    errors=$((errors + 1))
+  fi
+
+  if has_changed_path "$CHANGED_FILES" "$architecture_paths_pattern" &&
+     ! has_changed_path "$CHANGED_FILES" "$adr_paths_pattern"; then
+    log_fail "Architecture-sensitive area changed but no ADR changed"
+    errors=$((errors + 1))
+  fi
+
+  if ! validate_ticket_doc_paths; then
+    errors=$((errors + 1))
+  fi
+
+  if ! validate_done_tickets; then
+    errors=$((errors + 1))
+  fi
+
+  echo ""
+  echo "========================================================"
+  if [ "$errors" -eq 0 ]; then
+    echo -e "  ${GREEN}Documentation gates passed${NC}"
+    echo "========================================================"
+    exit 0
+  fi
+
+  echo -e "  ${RED}Documentation gates failed: $errors issue group(s)${NC}"
+  echo "========================================================"
+  exit 1
+}
+
+main "$@"

package/core/scripts/validate-permissions.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# scripts/validate-permissions.sh
+#
+# Validates that state history commands were executed by an allowed agent role.
+#
+# Usage:
+#   bash scripts/validate-permissions.sh
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo -e "${BLUE}i${NC}  $1"; }
+log_pass() { echo -e "${GREEN}+${NC}  $1"; }
+log_fail() { echo -e "${RED}x${NC}  $1"; }
+
+normalize_agent() {
+  printf '%s' "$1" | sed 's/-agent$//'
+}
+
+command_file_for() {
+  local command="$1"
+  local name
+  name=$(printf '%s' "$command" | sed 's#^/##')
+  find core/commands -name "$name.md" -type f | head -1
+}
+
+allowed_agents_for_command() {
+  local file="$1"
+
+  awk '
+    /^owner_agent:/ {
+      gsub(/"/, "", $2);
+      print $2;
+    }
+    /^requires_agents:/ {
+      in_requires=1;
+      next;
+    }
+    in_requires && /^  - / {
+      agent=$2;
+      gsub(/"/, "", agent);
+      print agent;
+      next;
+    }
+    in_requires && /^[^ ]/ {
+      in_requires=0;
+    }
+  ' "$file" | sort -u
+}
+
+main() {
+  if ! command -v jq >/dev/null 2>&1; then
+    log_fail "jq not installed. Install with: brew install jq"
+    exit 2
+  fi
+
+  echo ""
+  echo "========================================================"
+  echo "  Validating agent command permissions"
+  echo "========================================================"
+  echo ""
+
+  if [ ! -d "project/tickets" ]; then
+    log_info "No tickets directory; skipping"
+    exit 0
+  fi
+
+  local errors=0
+
+  while IFS= read -r -d '' ticket; do
+    local ticket_id
+    ticket_id=$(jq -r '.id // empty' "$ticket")
+
+    local history_count
+    history_count=$(jq '.state_history | length' "$ticket")
+    if [ "$history_count" -eq 0 ]; then
+      continue
+    fi
+
+    for i in $(seq 0 $((history_count - 1))); do
+      local command agent role file allowed
+      command=$(jq -r ".state_history[$i].by_command // empty" "$ticket")
+      agent=$(jq -r ".state_history[$i].by_agent // empty" "$ticket")
+      role=$(normalize_agent "$agent")
+
+      [ -n "$command" ] || continue
+
+      file=$(command_file_for "$command")
+      if [ -z "$file" ]; then
+        log_fail "$ticket_id state_history[$i]: unknown command $command"
+        errors=$((errors + 1))
+        continue
+      fi
+
+      allowed=$(allowed_agents_for_command "$file")
+      if ! printf '%s\n' "$allowed" | grep -qx "$role"; then
+        log_fail "$ticket_id state_history[$i]: $agent cannot execute $command"
+        log_fail "  Allowed: $(printf '%s' "$allowed" | tr '\n' ' ')"
+        errors=$((errors + 1))
+      fi
+
+      local from_state to_state assignee
+      from_state=$(jq -r ".state_history[$i].from_state // empty" "$ticket")
+      to_state=$(jq -r ".state_history[$i].to_state // empty" "$ticket")
+      assignee=$(jq -r ".assignee // empty" "$ticket")
+
+      if { [ "$to_state" = "DONE" ] || { [ "$from_state" = "IN_REVIEW" ] && [ "$to_state" = "QA" ]; }; } &&
+         [ -n "$assignee" ] && [ "$agent" = "$assignee" ]; then
+        log_fail "$ticket_id state_history[$i]: self-approval forbidden for $agent"
+        errors=$((errors + 1))
+      fi
+    done
+  done < <(find project/tickets -name '*.json' -type f -print0)
+
+  echo ""
+  echo "========================================================"
+  if [ "$errors" -eq 0 ]; then
+    echo -e "  ${GREEN}Permission gates passed${NC}"
+    echo "========================================================"
+    exit 0
+  fi
+
+  echo -e "  ${RED}Permission gates failed: $errors issue(s)${NC}"
+  echo "========================================================"
+  exit 1
+}
+
+main "$@"