ai-core-framework 0.1.0

package/core/scripts/ai-core.sh

@@ -0,0 +1,456 @@
+#!/usr/bin/env bash
+# core/scripts/ai-core.sh
+#
+# Lightweight command runner for executable AI Core commands.
+#
+# User-facing usage is chat-first: type `/command ...` in the AI chat.
+# This script is the internal executable runner used by AI tools and CI.
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+AGENT_OVERRIDE=""
+
+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"; }
+
+AI_CORE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PROJECT_ROOT="$(dirname "$AI_CORE_DIR")"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  In AI chat:
+    /command [args...]
+    guide /command [args...]
+    next TICKET-XXX
+
+  Internal runner form:
+  bash core/scripts/ai-core.sh [--agent role] run /command [args...]
+  bash core/scripts/ai-core.sh [--agent role] guide /command [args...]
+  bash core/scripts/ai-core.sh [--agent role] next TICKET-XXX
+  bash core/scripts/ai-core.sh list
+
+Environment:
+  AI_AGENT=<agent-role>   Optional internal override. Runner auto-selects owner_agent by default.
+
+Chat examples:
+  /validate-state
+  guide /groom-ticket TICKET-001 5
+  next TICKET-001
+  /validate-docs --base origin/main
+EOF
+}
+
+normalize_agent() {
+  printf '%s' "$1" | sed 's/-agent$//'
+}
+
+command_name() {
+  printf '%s' "$1" | sed 's#^/##'
+}
+
+command_file_for() {
+  local command="$1"
+  local name
+  name=$(command_name "$command")
+  find "$AI_CORE_DIR/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
+}
+
+owner_agent_for_command() {
+  local file="$1"
+  awk '/^owner_agent:/ { gsub(/"/, "", $2); print $2; exit }' "$file"
+}
+
+assert_permission() {
+  local command="$1"
+  local file="$2"
+  local agent="${AGENT_OVERRIDE:-${AI_AGENT:-}}"
+
+  if [ -z "$agent" ]; then
+    agent=$(owner_agent_for_command "$file")
+  fi
+
+  if [ -z "$agent" ]; then
+    local first_allowed
+    first_allowed=$(allowed_agents_for_command "$file" | head -1)
+    agent="$first_allowed"
+  fi
+
+  if [ -z "$agent" ]; then
+    log_fail "Could not determine agent for $command"
+    log_warn "Check owner_agent/requires_agents metadata for $command"
+    exit 1
+  fi
+
+  local role allowed
+  role=$(normalize_agent "$agent")
+  allowed=$(allowed_agents_for_command "$file")
+
+  if ! printf '%s\n' "$allowed" | grep -qx "$role"; then
+    log_fail "$agent is not allowed to run $command"
+    log_fail "Allowed: $(printf '%s' "$allowed" | tr '\n' ' ')"
+    exit 1
+  fi
+
+  export AI_AGENT="$role"
+}
+
+run_command() {
+  local command="$1"
+  shift || true
+
+  local file
+  file=$(command_file_for "$command")
+  if [ -z "$file" ]; then
+    log_fail "Unknown command: $command"
+    exit 1
+  fi
+
+  assert_permission "$command" "$file"
+
+  cd "$PROJECT_ROOT"
+
+  case "$(command_name "$command")" in
+    setup-project)
+      bash "$AI_CORE_DIR/scripts/setup-project.sh" "$@"
+      ;;
+    sync-platforms)
+      bash "$AI_CORE_DIR/scripts/sync-platforms.sh" "$@"
+      ;;
+    validate-state)
+      bash "$AI_CORE_DIR/scripts/validate-state.sh" "$@"
+      ;;
+    validate-docs)
+      bash "$AI_CORE_DIR/scripts/validate-docs.sh" "$@"
+      ;;
+    validate-permissions)
+      bash "$AI_CORE_DIR/scripts/validate-permissions.sh" "$@"
+      ;;
+    validate-audit-log)
+      bash "$AI_CORE_DIR/scripts/validate-audit-log.sh" "$@"
+      ;;
+    generate-views)
+      bash "$AI_CORE_DIR/scripts/generate-views.sh" "$@"
+      ;;
+    analyze-requirements|groom-ticket|write-plan|mark-ready|implement-task|create-pr|merge-pr|smoke-test|release)
+      bash "$AI_CORE_DIR/scripts/workflow.sh" "$(command_name "$command")" "$@"
+      ;;
+    *)
+      log_pass "Permission granted for $command"
+      log_warn "No executable handler exists yet. Follow command spec: $file"
+      ;;
+  esac
+}
+
+ticket_file() {
+  printf '%s/project/tickets/%s.json' "$PROJECT_ROOT" "$1"
+}
+
+latest_audit_field() {
+  local field="$1"
+  local audit_file="$PROJECT_ROOT/project/audit-log.jsonl"
+  if [ ! -s "$audit_file" ]; then
+    printf ''
+    return 0
+  fi
+  tail -1 "$audit_file" | jq -r ".$field // empty" 2>/dev/null || true
+}
+
+ticket_from_args_or_audit() {
+  for arg in "$@"; do
+    if [[ "$arg" =~ ^TICKET-[0-9]{3,}$ ]]; then
+      printf '%s' "$arg"
+      return 0
+    fi
+  done
+  latest_audit_field "ticket_id"
+}
+
+next_step_for_status() {
+  local ticket_id="$1"
+  local file status
+  file=$(ticket_file "$ticket_id")
+
+  if [ ! -f "$file" ]; then
+    log_fail "Ticket not found: $ticket_id"
+    return 1
+  fi
+
+  status=$(jq -r '.status // empty' "$file")
+  case "$status" in
+    DRAFT)
+      printf 'tech-lead|/groom-ticket %s <story_points>|DRAFT -> GROOMED' "$ticket_id"
+      ;;
+    GROOMED)
+      if jq -e '.implementation_plan_path // empty' "$file" >/dev/null 2>&1; then
+        printf 'scrum-master|/mark-ready %s|GROOMED -> READY' "$ticket_id"
+      else
+        printf 'tech-lead|/write-plan %s|Create implementation plan before READY' "$ticket_id"
+      fi
+      ;;
+    READY)
+      if jq -e '.implementation_plan_path // empty' "$file" >/dev/null 2>&1; then
+        printf 'developer|/implement-task %s|READY -> IN_PROGRESS' "$ticket_id"
+      else
+        printf 'tech-lead|/write-plan %s|Create implementation plan before implementation' "$ticket_id"
+      fi
+      ;;
+    IN_PROGRESS)
+      printf 'developer|/create-pr %s <pr_url>|IN_PROGRESS -> IN_REVIEW' "$ticket_id"
+      ;;
+    IN_REVIEW)
+      printf 'tech-lead|/merge-pr %s|IN_REVIEW -> QA' "$ticket_id"
+      ;;
+    QA)
+      printf 'qa-tester|/smoke-test %s|QA -> DONE' "$ticket_id"
+      ;;
+    DONE)
+      printf 'scrum-master|/generate-views|DONE -> views/release readiness'
+      ;;
+    BLOCKED)
+      printf 'scrum-master|/ticket-health %s|BLOCKED -> review blocker' "$ticket_id"
+      ;;
+    CANCELLED)
+      printf 'none|stop|CANCELLED -> stop'
+      ;;
+    *)
+      printf 'none|stop|Unknown status: %s' "$status"
+      ;;
+  esac
+}
+
+print_next_step() {
+  local ticket_id="$1"
+  local next agent command description
+  next=$(next_step_for_status "$ticket_id") || return 1
+  IFS='|' read -r agent command description <<< "$next"
+
+  echo ""
+  echo "Suggested next step:"
+  if [ "$agent" = "none" ] || [ "$command" = "stop" ]; then
+    echo "  $description"
+  else
+    echo "  Chat: $command"
+    echo "  # $description"
+  fi
+}
+
+run_validation_quiet() {
+  local label="$1"
+  shift
+
+  if "$@" >/tmp/ai-core-guide-validation.log 2>&1; then
+    echo "- $label: pass"
+  else
+    echo "- $label: fail"
+    sed 's/^/  /' /tmp/ai-core-guide-validation.log | tail -20
+  fi
+}
+
+guide_command() {
+  local command="$1"
+  shift || true
+
+  local before_status="" after_status="" ticket_id="" before_audit_hash="" after_audit_hash=""
+  local before_file="" after_file=""
+
+  cd "$PROJECT_ROOT"
+  ticket_id=$(ticket_from_args_or_audit "$@")
+  if [ -n "$ticket_id" ]; then
+    before_file=$(ticket_file "$ticket_id")
+    if [ -f "$before_file" ]; then
+      before_status=$(jq -r '.status // empty' "$before_file")
+    fi
+  fi
+  before_audit_hash=$(latest_audit_field "hash")
+
+  run_command "$command" "$@"
+
+  ticket_id=$(ticket_from_args_or_audit "$@")
+  after_audit_hash=$(latest_audit_field "hash")
+  if [ -n "$ticket_id" ]; then
+    after_file=$(ticket_file "$ticket_id")
+    if [ -f "$after_file" ]; then
+      after_status=$(jq -r '.status // empty' "$after_file")
+    fi
+  fi
+
+  echo ""
+  echo "========================================================"
+  echo "  Guided workflow report"
+  echo "========================================================"
+  echo ""
+  echo "Completed: $command $*"
+
+  if [ -n "$ticket_id" ]; then
+    echo "Ticket: $ticket_id"
+    if [ -n "$before_status" ] || [ -n "$after_status" ]; then
+      echo "State: ${before_status:-new} -> ${after_status:-unknown}"
+    fi
+  fi
+
+  echo ""
+  echo "Updated:"
+  if [ -n "$ticket_id" ] && [ -f "$(ticket_file "$ticket_id")" ]; then
+    echo "- project/tickets/$ticket_id.json"
+  fi
+  if [ "$before_audit_hash" != "$after_audit_hash" ] && [ -s "project/audit-log.jsonl" ]; then
+    echo "- project/audit-log.jsonl"
+  fi
+  case "$(command_name "$command")" in
+    generate-views)
+      echo "- project/views/*.md"
+      ;;
+    smoke-test)
+      echo "- project/test-runs/${ticket_id}-*.md"
+      ;;
+    release)
+      echo "- project/releases/*.json"
+      ;;
+  esac
+
+  echo ""
+  echo "Validation:"
+  run_validation_quiet "state" bash "$AI_CORE_DIR/scripts/validate-state.sh"
+  run_validation_quiet "permissions" bash "$AI_CORE_DIR/scripts/validate-permissions.sh"
+  run_validation_quiet "docs" bash "$AI_CORE_DIR/scripts/validate-docs.sh"
+  run_validation_quiet "audit-log" bash "$AI_CORE_DIR/scripts/validate-audit-log.sh"
+
+  if [ -n "$ticket_id" ] && [ -f "$(ticket_file "$ticket_id")" ]; then
+    print_next_step "$ticket_id"
+
+    local next agent next_command description answer
+    next=$(next_step_for_status "$ticket_id")
+    IFS='|' read -r agent next_command description <<< "$next"
+    if [ "$agent" != "none" ] && [ "$next_command" != "stop" ]; then
+      echo ""
+      if [[ "$next_command" == *"<"* ]]; then
+        log_info "Next step needs user-provided argument(s); not auto-running."
+        return 0
+      fi
+      if [ -t 0 ]; then
+        printf 'Proceed with next step now? [y/N] '
+        read -r answer
+        case "$answer" in
+          y|Y|yes|YES)
+            bash "$AI_CORE_DIR/scripts/ai-core.sh" --agent "$agent" run $next_command
+            ;;
+          *)
+            log_info "Stopped after guided report."
+            ;;
+        esac
+      else
+        log_info "Non-interactive shell detected; not auto-running next step."
+      fi
+    fi
+  fi
+}
+
+next_command() {
+  local ticket_id="${1:-}"
+  if [ -z "$ticket_id" ]; then
+    log_fail "Usage in chat: next TICKET-XXX"
+    exit 2
+  fi
+  cd "$PROJECT_ROOT"
+  print_next_step "$ticket_id"
+}
+
+list_commands() {
+  find "$AI_CORE_DIR/commands" -name '*.md' -type f |
+    grep -v '/README.md$' |
+    sed "s#^$AI_CORE_DIR/commands/##" |
+    sed 's#/# #g; s#\.md$##' |
+    awk '{ print "/" $NF }' |
+    sort
+}
+
+main() {
+  while [ $# -gt 0 ]; do
+    case "${1:-}" in
+      --agent)
+        AGENT_OVERRIDE="${2:-}"
+        if [ -z "$AGENT_OVERRIDE" ]; then
+          log_fail "--agent requires a role"
+          exit 2
+        fi
+        shift 2
+        ;;
+      --agent=*)
+        AGENT_OVERRIDE="${1#--agent=}"
+        shift
+        ;;
+      *)
+        break
+        ;;
+    esac
+  done
+
+  local subcommand="${1:-}"
+  case "$subcommand" in
+    run)
+      shift
+      if [ $# -lt 1 ]; then
+        usage
+        exit 2
+      fi
+      run_command "$@"
+      ;;
+    guide)
+      shift
+      if [ $# -lt 1 ]; then
+        usage
+        exit 2
+      fi
+      guide_command "$@"
+      ;;
+    next)
+      shift
+      next_command "$@"
+      ;;
+    list)
+      list_commands
+      ;;
+    -h|--help|help|"")
+      usage
+      ;;
+    *)
+      log_fail "Unknown subcommand: $subcommand"
+      usage
+      exit 2
+      ;;
+  esac
+}
+
+main "$@"

package/core/scripts/generate-views.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# scripts/generate-views.sh
+#
+# Generates human-readable views from project without changing canonical state.
+# Canonical sources:
+# - project/backlog/backlog.json for backlog order
+# - project/tickets/*.json for ticket details and state history
+
+set -euo pipefail
+
+STATE_DIR="project"
+BACKLOG_FILE="$STATE_DIR/backlog/backlog.json"
+TICKETS_DIR="$STATE_DIR/tickets"
+VIEWS_DIR="$STATE_DIR/views"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+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"; }
+
+require_jq() {
+  if ! command -v jq >/dev/null 2>&1; then
+    log_fail "jq not installed. Install with: brew install jq"
+    exit 2
+  fi
+}
+
+get_ticket_field() {
+  local ticket_id="$1"
+  local field="$2"
+  local file="$TICKETS_DIR/$ticket_id.json"
+
+  if [ ! -f "$file" ]; then
+    printf '%s' "MISSING"
+    return 0
+  fi
+
+  jq -r "$field // \"\"" "$file"
+}
+
+ticket_count_by_status() {
+  local status="$1"
+  find "$TICKETS_DIR" -name 'TICKET-*.json' -type f -print0 2>/dev/null |
+  while IFS= read -r -d '' file; do
+    if [ "$(jq -r '.status' "$file")" = "$status" ]; then
+      echo 1
+    fi
+  done | wc -l | tr -d ' '
+}
+
+write_header() {
+  local file="$1"
+  local title="$2"
+  {
+    echo "# $title"
+    echo ""
+    echo "Generated from project. Do not edit this file as source of truth."
+    echo ""
+    echo "Generated at: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    echo ""
+  } > "$file"
+}
+
+main() {
+  require_jq
+
+  if [ ! -d "$STATE_DIR" ]; then
+    log_fail "Missing $STATE_DIR. Run /setup-project first."
+    exit 1
+  fi
+
+  if [ ! -f "$BACKLOG_FILE" ]; then
+    log_fail "Missing $BACKLOG_FILE"
+    exit 1
+  fi
+
+  mkdir -p "$VIEWS_DIR"
+
+  log_info "Generating views into $VIEWS_DIR"
+
+  local backlog_view="$VIEWS_DIR/backlog.md"
+  write_header "$backlog_view" "Backlog View"
+  {
+    echo "| Rank | Ticket | Priority | Status | Title | Epic |"
+    echo "|------|--------|----------|--------|-------|------|"
+    jq -r '.items[] | [.rank, .ticket_id, (.priority // ""), (.epic // "")] | @tsv' "$BACKLOG_FILE" |
+    while IFS=$'\t' read -r rank ticket_id priority epic; do
+      status=$(get_ticket_field "$ticket_id" '.status')
+      title=$(get_ticket_field "$ticket_id" '.title')
+      echo "| $rank | $ticket_id | $priority | $status | $title | $epic |"
+    done
+  } >> "$backlog_view"
+  log_pass "$backlog_view"
+
+  for status in READY IN_PROGRESS IN_REVIEW QA BLOCKED; do
+    local lower
+    lower=$(printf '%s' "$status" | tr '[:upper:]' '[:lower:]' | tr '_' '-')
+    local view="$VIEWS_DIR/$lower.md"
+    write_header "$view" "$status Tickets"
+    {
+      echo "| Ticket | Priority | Title | Assignee | Sprint |"
+      echo "|--------|----------|-------|----------|--------|"
+      find "$TICKETS_DIR" -name 'TICKET-*.json' -type f -print0 2>/dev/null |
+      while IFS= read -r -d '' file; do
+        if [ "$(jq -r '.status' "$file")" = "$status" ]; then
+          ticket_id=$(jq -r '.id' "$file")
+          priority=$(jq -r '.priority // ""' "$file")
+          title=$(jq -r '.title // ""' "$file")
+          assignee=$(jq -r '.assignee // ""' "$file")
+          sprint_id=$(jq -r '.sprint_id // ""' "$file")
+          echo "| $ticket_id | $priority | $title | $assignee | $sprint_id |"
+        fi
+      done
+    } >> "$view"
+    log_pass "$view"
+  done
+
+  local dashboard_view="$VIEWS_DIR/dashboard.md"
+  write_header "$dashboard_view" "Project Dashboard"
+  {
+    echo "## Flow Summary"
+    echo ""
+    echo "| State | Count |"
+    echo "|-------|-------|"
+    for status in DRAFT GROOMED READY IN_PROGRESS IN_REVIEW QA DONE BLOCKED CANCELLED; do
+      echo "| $status | $(ticket_count_by_status "$status") |"
+    done
+    echo ""
+    echo "## WIP"
+    echo ""
+    echo "| Ticket | Status | Priority | Assignee | Sprint | Title |"
+    echo "|--------|--------|----------|----------|--------|-------|"
+    find "$TICKETS_DIR" -name 'TICKET-*.json' -type f -print0 2>/dev/null |
+    while IFS= read -r -d '' file; do
+      status=$(jq -r '.status' "$file")
+      if [[ "$status" =~ ^(IN_PROGRESS|IN_REVIEW|QA|BLOCKED)$ ]]; then
+        ticket_id=$(jq -r '.id' "$file")
+        priority=$(jq -r '.priority // ""' "$file")
+        assignee=$(jq -r '.assignee // ""' "$file")
+        sprint_id=$(jq -r '.sprint_id // ""' "$file")
+        title=$(jq -r '.title // ""' "$file")
+        echo "| $ticket_id | $status | $priority | $assignee | $sprint_id | $title |"
+      fi
+    done
+    echo ""
+    echo "## Epic Progress"
+    echo ""
+    echo "| Epic | Total | Done | In Progress | Blocked |"
+    echo "|------|-------|------|-------------|---------|"
+    jq -sr '
+      group_by(.epic // "NO_EPIC")[] |
+      {
+        epic: (.[0].epic // "NO_EPIC"),
+        total: length,
+        done: map(select(.status == "DONE")) | length,
+        wip: map(select(.status == "IN_PROGRESS" or .status == "IN_REVIEW" or .status == "QA")) | length,
+        blocked: map(select(.status == "BLOCKED")) | length
+      } |
+      [.epic, .total, .done, .wip, .blocked] | @tsv
+    ' "$TICKETS_DIR"/TICKET-*.json 2>/dev/null |
+    while IFS=$'\t' read -r epic total done wip blocked; do
+      echo "| $epic | $total | $done | $wip | $blocked |"
+    done
+  } >> "$dashboard_view"
+  log_pass "$dashboard_view"
+
+  local release_view="$VIEWS_DIR/release-readiness.md"
+  write_header "$release_view" "Release Readiness"
+  {
+    echo "| Gate | Status |"
+    echo "|------|--------|"
+    blocked_count=$(ticket_count_by_status BLOCKED)
+    qa_count=$(ticket_count_by_status QA)
+    in_review_count=$(ticket_count_by_status IN_REVIEW)
+    missing_pr_count=$(find "$TICKETS_DIR" -name 'TICKET-*.json' -type f -print0 2>/dev/null |
+      while IFS= read -r -d '' file; do
+        if [ "$(jq -r '.status' "$file")" = "DONE" ] && [ "$(jq -r '.pr_url // empty' "$file")" = "" ]; then
+          echo 1
+        fi
+      done | wc -l | tr -d ' ')
+    echo "| Blocked tickets | $blocked_count |"
+    echo "| Tickets still in QA | $qa_count |"
+    echo "| Tickets still in review | $in_review_count |"
+    echo "| DONE tickets missing PR link | $missing_pr_count |"
+    echo ""
+    echo "## Latest Release Records"
+    echo ""
+    echo "| Version | Status | Created At | Released At |"
+    echo "|---------|--------|------------|-------------|"
+    find "$STATE_DIR/releases" -name '*.json' -type f -print0 2>/dev/null |
+    while IFS= read -r -d '' file; do
+      version=$(jq -r '.version // ""' "$file")
+      status=$(jq -r '.status // ""' "$file")
+      created_at=$(jq -r '.created_at // ""' "$file")
+      released_at=$(jq -r '.released_at // ""' "$file")
+      echo "| $version | $status | $created_at | $released_at |"
+    done
+  } >> "$release_view"
+  log_pass "$release_view"
+
+  log_pass "All views generated"
+}
+
+main "$@"