ai-core-framework 0.1.0

package/core/scripts/sync-platforms.sh

@@ -0,0 +1,322 @@
+#!/usr/bin/env bash
+# ============================================================================
+# sync-platforms.sh
+# Sync core/ content sang Claude Code, Cursor, Windsurf format.
+# Usage: bash core/scripts/sync-platforms.sh
+# ============================================================================
+
+set -euo pipefail
+
+AI_CORE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PROJECT_ROOT="$(dirname "$AI_CORE_DIR")"
+
+echo "🔄 Syncing core/ to AI platforms..."
+echo "   Source: $AI_CORE_DIR"
+echo "   Target: $PROJECT_ROOT"
+
+# ============================================================================
+# 1. CLAUDE CODE (.claude/)
+# ============================================================================
+# Claude Code uses:
+#   .claude/agents/<name>.md        — subagents
+#   .claude/commands/<name>.md      — slash commands (flat)
+#   CLAUDE.md                       — project-level instructions
+# ============================================================================
+
+sync_claude_code() {
+    echo ""
+    echo "📦 [1/3] Claude Code..."
+
+    local claude_dir="$PROJECT_ROOT/.claude"
+    mkdir -p "$claude_dir/agents" "$claude_dir/commands" "$claude_dir/skills"
+
+    # --- Sync agents ---
+    for agent_file in "$AI_CORE_DIR"/agents/*.md; do
+        [ -f "$agent_file" ] || continue
+        local basename
+        basename=$(basename "$agent_file")
+        [[ "$basename" == "README.md" ]] && continue
+        cp "$agent_file" "$claude_dir/agents/$basename"
+        echo "   ✓ agent: $basename"
+    done
+
+    # --- Sync commands (flatten from subdirs) ---
+    find "$AI_CORE_DIR/commands" -name "*.md" -type f | while read -r cmd_file; do
+        local basename
+        basename=$(basename "$cmd_file")
+        # Skip README files
+        [[ "$basename" == "README.md" ]] && continue
+        cp "$cmd_file" "$claude_dir/commands/$basename"
+        echo "   ✓ command: $basename"
+    done
+
+    # --- Sync skills ---
+    for skill_file in "$AI_CORE_DIR"/skills/*/SKILL.md; do
+        [ -f "$skill_file" ] || continue
+        local skill_name
+        skill_name=$(basename "$(dirname "$skill_file")")
+        mkdir -p "$claude_dir/skills/$skill_name"
+        cp "$skill_file" "$claude_dir/skills/$skill_name/SKILL.md"
+        echo "   ✓ skill: $skill_name"
+    done
+
+    # --- Generate CLAUDE.md (project-level instructions) ---
+    cat > "$PROJECT_ROOT/CLAUDE.md" <<'EOF'
+# Project Instructions for Claude Code
+
+This project uses `core/` framework for structured Agile/Scrum development.
+
+## 🚨 CRITICAL: Read these first
+
+1. **Rules**: See `core/rules/00-global-rules.md` — **MUST follow**
+2. **Agents**: See `core/agents/` — pick correct agent for task
+3. **Skills**: See `core/skills/using-ai-core/SKILL.md` — chat-first bootstrap
+4. **Commands**: See `core/commands/` — use slash commands for workflows
+5. **Workflows**: See `core/workflows/feature-lifecycle.md`
+
+## Quick reference
+
+### User interface
+The normal user interface is the AI chat window. When the user types `/command ...`,
+`guide /command ...`, or `next TICKET-XXX`, interpret it as an AI Core workflow
+request. Do not ask the user to run `bash core/scripts/ai-core.sh` or set
+`AI_AGENT`; use those executable scripts internally only when helpful.
+
+### Before any code change
+- [ ] There's an active ticket in `project/tickets/` with `status: IN_PROGRESS`
+- [ ] You're on the correct feature branch
+- [ ] You're playing the correct agent role inferred from command metadata
+
+### State machine
+```
+DRAFT → GROOMED → READY → IN_PROGRESS → IN_REVIEW → QA → DONE
+```
+
+### Commit convention
+`<type>(TICKET-XXX): <description>`
+
+### Branch naming
+`feature/TICKET-XXX-slug` | `bugfix/TICKET-XXX-slug` | `hotfix/TICKET-XXX-slug`
+
+## ❌ Absolute prohibitions
+
+See `core/rules/00-global-rules.md` → G-011
+
+## 🎭 Your current role
+
+Before responding, identify which agent you're playing based on the task or command metadata:
+- BA request (analyze requirement) → `business-analyst`
+- Technical design / review → `tech-lead`
+- Coding → `developer`
+- Testing → `qa-tester`
+- Planning / release → `scrum-master`
+
+Read the agent file to understand your boundaries.
+
+## Skill bootstrap
+
+At session start or before any workflow request, read `core/skills/using-ai-core/SKILL.md`.
+For feature discovery use `core/skills/brainstorming/SKILL.md`.
+For implementation plans use `core/skills/writing-implementation-plan/SKILL.md`.
+For completion claims use `core/skills/verification-before-done/SKILL.md`.
+EOF
+    echo "   ✓ CLAUDE.md"
+
+    echo "   ✅ Claude Code sync complete: $claude_dir/"
+}
+
+# ============================================================================
+# 2. CURSOR (.cursor/rules/*.mdc)
+# ============================================================================
+# Cursor uses:
+#   .cursor/rules/<name>.mdc         — rules with YAML frontmatter
+#   Set alwaysApply: true to apply to all requests
+# ============================================================================
+
+sync_cursor() {
+    echo ""
+    echo "📦 [2/3] Cursor..."
+
+    local cursor_dir="$PROJECT_ROOT/.cursor/rules"
+    mkdir -p "$cursor_dir"
+
+    # --- Main project rule (alwaysApply) ---
+    cat > "$cursor_dir/00-project-rules.mdc" <<'EOF'
+---
+description: Global project rules - Agile/Scrum enforcement
+alwaysApply: true
+---
+
+# Project Rules
+
+This project uses `core/` framework. Read these files for full context:
+
+- `core/rules/00-global-rules.md` — Hard rules (MUST follow)
+- `core/agents/` — Agent personas
+- `core/commands/` — Workflow commands
+- `core/workflows/feature-lifecycle.md` — End-to-end process
+
+## Top 10 Rules (summary)
+
+1. **No code without ticket** (G-001): Active ticket in `project/tickets/` with status IN_PROGRESS
+2. **State machine**: DRAFT → GROOMED → READY → IN_PROGRESS → IN_REVIEW → QA → DONE. No skipping.
+3. **TDD mandatory**: Tests before code
+4. **Coverage ≥ 80%** on diff
+5. **Conventional Commits**: `<type>(TICKET-XXX): <description>`
+6. **Branch naming**: `feature/TICKET-XXX-slug`
+7. **No direct push** to main/develop
+8. **No secrets** committed
+9. **No self-approval** of PRs
+10. **Follow agent boundaries** in `core/agents/<agent>.md`
+
+## Before any task
+
+Ask yourself:
+1. Which agent role does the command metadata imply?
+2. Is there an active ticket?
+3. Am I on the right branch?
+4. Does this follow the state machine?
+
+If any answer is unclear → STOP and ask user.
+
+## Chat-first workflow
+
+Users should type workflow commands in chat, for example:
+
+- `/analyze-requirements "User can reset password"`
+- `/groom-ticket TICKET-001 5`
+- `guide /mark-ready TICKET-001`
+- `next TICKET-001`
+
+Do not require users to type shell commands such as `bash core/scripts/ai-core.sh`
+or environment variables such as `AI_AGENT=...`. Shell scripts are internal tools
+for deterministic execution, validation, and CI.
+EOF
+    echo "   ✓ 00-project-rules.mdc (alwaysApply)"
+
+    # --- Per-agent rule (scoped) ---
+    for agent_file in "$AI_CORE_DIR"/agents/*.md; do
+        [ -f "$agent_file" ] || continue
+        local name
+        name=$(basename "$agent_file" .md)
+        [[ "$name" == "README" ]] && continue
+        local mdc_file="$cursor_dir/agent-$name.mdc"
+
+        cat > "$mdc_file" <<EOF
+---
+description: "Agent: $name"
+alwaysApply: false
+---
+
+EOF
+        # Append agent content (skip frontmatter)
+        awk '/^---$/{count++; next} count>=2' "$agent_file" >> "$mdc_file"
+        echo "   ✓ agent-$name.mdc"
+    done
+
+    # --- Rules files ---
+    for rule_file in "$AI_CORE_DIR"/rules/*.md; do
+        [ -f "$rule_file" ] || continue
+        local name
+        name=$(basename "$rule_file" .md)
+        cat > "$cursor_dir/rule-$name.mdc" <<EOF
+---
+description: "Rule: $name"
+alwaysApply: true
+---
+
+EOF
+        cat "$rule_file" >> "$cursor_dir/rule-$name.mdc"
+        echo "   ✓ rule-$name.mdc"
+    done
+
+    # --- Skills files ---
+    for skill_file in "$AI_CORE_DIR"/skills/*/SKILL.md; do
+        [ -f "$skill_file" ] || continue
+        local skill_name
+        skill_name=$(basename "$(dirname "$skill_file")")
+        cat > "$cursor_dir/skill-$skill_name.mdc" <<EOF
+---
+description: "AI Core skill: $skill_name"
+alwaysApply: false
+---
+
+EOF
+        cat "$skill_file" >> "$cursor_dir/skill-$skill_name.mdc"
+        echo "   ✓ skill-$skill_name.mdc"
+    done
+
+    echo "   ✅ Cursor sync complete: $cursor_dir/"
+}
+
+# ============================================================================
+# 3. WINDSURF (.windsurfrules)
+# ============================================================================
+# Windsurf uses a single .windsurfrules file (flat markdown)
+# ============================================================================
+
+sync_windsurf() {
+    echo ""
+    echo "📦 [3/3] Windsurf..."
+
+    local windsurf_file="$PROJECT_ROOT/.windsurfrules"
+
+    cat > "$windsurf_file" <<'EOF'
+# Windsurf Project Rules
+
+This project uses core/ framework for Agile/Scrum enforcement.
+
+## Required Reading
+
+Before ANY task, read:
+1. `core/rules/00-global-rules.md` — hard rules
+2. `core/agents/` — role definitions
+3. `core/skills/using-ai-core/SKILL.md` — chat-first bootstrap
+4. `core/workflows/feature-lifecycle.md` — process
+
+## Non-negotiable rules
+
+EOF
+
+    # Append global rules content
+    cat "$AI_CORE_DIR/rules/00-global-rules.md" >> "$windsurf_file"
+
+    echo "" >> "$windsurf_file"
+    echo "## Available commands" >> "$windsurf_file"
+    echo "" >> "$windsurf_file"
+    find "$AI_CORE_DIR/commands" -name "*.md" -type f | while read -r cmd_file; do
+        local basename
+        basename=$(basename "$cmd_file" .md)
+        [[ "$basename" == "README" ]] && continue
+        echo "- /$basename" >> "$windsurf_file"
+    done
+
+    echo "" >> "$windsurf_file"
+    echo "## Available skills" >> "$windsurf_file"
+    echo "" >> "$windsurf_file"
+    find "$AI_CORE_DIR/skills" -name "SKILL.md" -type f | while read -r skill_file; do
+        local skill_name
+        skill_name=$(basename "$(dirname "$skill_file")")
+        echo "- $skill_name: core/skills/$skill_name/SKILL.md" >> "$windsurf_file"
+    done
+
+    echo "   ✓ .windsurfrules generated"
+    echo "   ✅ Windsurf sync complete"
+}
+
+# ============================================================================
+# RUN
+# ============================================================================
+
+sync_claude_code
+sync_cursor
+sync_windsurf
+
+echo ""
+echo "✅ All platforms synced!"
+echo ""
+echo "📋 Next steps:"
+echo "   1. Review generated files"
+echo "   2. Commit: git add .claude/ .cursor/ .windsurfrules CLAUDE.md"
+echo "   3. Test in Claude Code: try /setup-project"
+echo "   4. Test in Cursor: open composer and check rules applied"

package/core/scripts/validate-audit-log.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# core/scripts/validate-audit-log.sh
+#
+# Validates append-only audit log hash chaining.
+
+set -euo pipefail
+
+AUDIT_FILE="project/audit-log.jsonl"
+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"; }
+
+hash_value() {
+  local value="$1"
+  if command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "$value" | sha256sum | awk '{print $1}'
+  else
+    printf '%s' "$value" | shasum -a 256 | awk '{print $1}'
+  fi
+}
+
+if [ ! -f "$AUDIT_FILE" ]; then
+  log_info "No audit log found; skipping"
+  exit 0
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  log_fail "jq not installed. Install with: brew install jq"
+  exit 2
+fi
+
+previous=""
+line_no=0
+errors=0
+
+while IFS= read -r line; do
+  line_no=$((line_no + 1))
+
+  if ! printf '%s' "$line" | jq empty >/dev/null 2>&1; then
+    log_fail "Audit line $line_no is not valid JSON"
+    errors=$((errors + 1))
+    continue
+  fi
+
+  actual_prev=$(printf '%s' "$line" | jq -r '.prev_hash // empty')
+  actual_hash=$(printf '%s' "$line" | jq -r '.hash // empty')
+  payload=$(printf '%s' "$line" | jq -c 'del(.hash)')
+  expected_hash=$(hash_value "$payload")
+
+  if [ "$actual_prev" != "$previous" ]; then
+    log_fail "Audit line $line_no prev_hash mismatch"
+    errors=$((errors + 1))
+  fi
+
+  if [ "$actual_hash" != "$expected_hash" ]; then
+    log_fail "Audit line $line_no hash mismatch"
+    errors=$((errors + 1))
+  fi
+
+  previous="$actual_hash"
+done < "$AUDIT_FILE"
+
+if [ "$errors" -gt 0 ]; then
+  log_fail "Audit log validation failed: $errors issue(s)"
+  exit 1
+fi
+
+log_pass "Audit log hash chain valid"