aios-core 4.0.2 → 4.0.4

package/.claude/hooks/write-path-validation.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+Hook: Write Path Validation
+
+REGRA: Documentos devem ir para os paths corretos conforme convenções.
+
+Este hook intercepta Write/Edit e AVISA (não bloqueia) quando o path
+parece violar as convenções de organização de documentos.
+
+Exit Codes:
+- 0: Sempre (apenas avisa, nunca bloqueia)
+"""
+
+import json
+import sys
+import os
+import re
+from datetime import datetime
+
+# =============================================================================
+# CONFIGURAÇÃO: Regras de organização de documentos
+# =============================================================================
+
+PATH_RULES = [
+    # (pattern no nome/conteúdo, path esperado, descrição)
+    {
+        "name_patterns": [r"session", r"handoff", r"^2\d{3}-\d{2}-\d{2}"],
+        "expected_path": "docs/sessions/",
+        "description": "Session logs e handoffs → docs/sessions/YYYY-MM/",
+    },
+    {
+        "name_patterns": [r"architecture", r"system-design", r"infra"],
+        "expected_path": "docs/architecture/",
+        "description": "Docs de arquitetura → docs/architecture/",
+        "exclude_patterns": [r"ARCHITECTURE_RULES"],  # Exceção para MMOS
+    },
+    {
+        "name_patterns": [r"guide", r"tutorial", r"how-to"],
+        "expected_path": "docs/guides/",
+        "description": "Guias e tutoriais → docs/guides/",
+    },
+    {
+        "name_patterns": [r"prd\.md$", r"epic.*\.md$", r"story.*\.md$"],
+        "expected_path": "docs/projects/",
+        "description": "PRDs, Epics, Stories → docs/projects/{project}/",
+    },
+    {
+        "name_patterns": [r"mind.*specific", r"mind.*validation"],
+        "expected_path": "outputs/minds/",
+        "description": "Docs específicos de mind → outputs/minds/{slug}/docs/",
+    },
+]
+
+# Paths que são sempre válidos (não avisar)
+ALWAYS_VALID_PATHS = [
+    ".claude/",
+    ".aios-core/",
+    ".aios-upstream/",
+    "squads/",
+    "node_modules/",
+    ".git/",
+    "app/",
+    "supabase/",
+    "outputs/",
+]
+
+# =============================================================================
+# LÓGICA DO HOOK
+# =============================================================================
+
+def get_project_root():
+    """Obtém o root do projeto."""
+    return os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+
+def normalize_path(file_path: str, project_root: str) -> str:
+    """Normaliza path para relativo."""
+    if file_path.startswith(project_root):
+        return file_path[len(project_root):].lstrip("/")
+    return file_path
+
+def is_always_valid(relative_path: str) -> bool:
+    """Verifica se o path está em área sempre válida."""
+    for valid in ALWAYS_VALID_PATHS:
+        if relative_path.startswith(valid):
+            return True
+    return False
+
+def is_documentation_file(relative_path: str) -> bool:
+    """Verifica se é um arquivo de documentação."""
+    doc_extensions = [".md", ".mdx", ".txt", ".rst"]
+    return any(relative_path.endswith(ext) for ext in doc_extensions)
+
+def check_path_rules(relative_path: str) -> list[dict]:
+    """
+    Verifica se o path viola alguma regra.
+
+    Returns:
+        Lista de violações com sugestões
+    """
+    violations = []
+    filename = os.path.basename(relative_path)
+
+    for rule in PATH_RULES:
+        # Verificar se o nome do arquivo corresponde ao pattern
+        matches_name = False
+        for pattern in rule["name_patterns"]:
+            if re.search(pattern, filename, re.IGNORECASE):
+                matches_name = True
+                break
+
+        if not matches_name:
+            continue
+
+        # Verificar exceções
+        if "exclude_patterns" in rule:
+            is_excluded = False
+            for exc_pattern in rule["exclude_patterns"]:
+                if re.search(exc_pattern, filename, re.IGNORECASE):
+                    is_excluded = True
+                    break
+            if is_excluded:
+                continue
+
+        # Verificar se está no path esperado
+        expected = rule["expected_path"]
+        if not relative_path.startswith(expected):
+            violations.append({
+                "current_path": relative_path,
+                "expected_path": expected,
+                "description": rule["description"],
+            })
+
+    return violations
+
+def main():
+    # Ler input do stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # Só processar Write e Edit
+    if tool_name not in ["Write", "Edit"]:
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if not file_path:
+        sys.exit(0)
+
+    # Normalizar path
+    project_root = get_project_root()
+    relative_path = normalize_path(file_path, project_root)
+
+    # Verificar se é área sempre válida
+    if is_always_valid(relative_path):
+        sys.exit(0)
+
+    # Só verificar arquivos de documentação
+    if not is_documentation_file(relative_path):
+        sys.exit(0)
+
+    # Verificar regras
+    violations = check_path_rules(relative_path)
+
+    if not violations:
+        sys.exit(0)
+
+    # AVISAR (não bloquear)
+    violation = violations[0]  # Mostrar primeira violação
+
+    warning_message = f"""
+┌──────────────────────────────────────────────────────────────────────────────┐
+│  ⚠️  PATH WARNING: Documento pode estar no local errado                       │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  Arquivo: {relative_path[:60]:<60} │
+│                                                                              │
+│  Convenção: {violation['description'][:56]:<56} │
+│  Esperado:  {violation['expected_path']:<57} │
+│                                                                              │
+│  NOTA: Este é apenas um AVISO, a operação será executada.                    │
+│        Verifique se o path está correto antes de continuar.                  │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+"""
+    # Imprimir warning mas NÃO bloquear (exit 0)
+    print(warning_message, file=sys.stderr)
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/.claude/rules/agent-authority.md

@@ -0,0 +1,105 @@
+# Agent Authority — Detailed Rules
+
+## Delegation Matrix
+
+### @devops (Gage) — EXCLUSIVE Authority
+
+| Operation | Exclusive? | Other Agents |
+|-----------|-----------|--------------|
+| `git push` / `git push --force` | YES | BLOCKED |
+| `gh pr create` / `gh pr merge` | YES | BLOCKED |
+| MCP add/remove/configure | YES | BLOCKED |
+| CI/CD pipeline management | YES | BLOCKED |
+| Release management | YES | BLOCKED |
+
+### @pm (Morgan) — Epic Orchestration
+
+| Operation | Exclusive? | Delegated From |
+|-----------|-----------|---------------|
+| `*execute-epic` | YES | — |
+| `*create-epic` | YES | — |
+| EPIC-{ID}-EXECUTION.yaml management | YES | — |
+| Requirements gathering | YES | — |
+| Spec writing (spec pipeline) | YES | — |
+
+### @po (Pax) — Story Validation
+
+| Operation | Exclusive? | Details |
+|-----------|-----------|---------|
+| `*validate-story-draft` | YES | 10-point checklist |
+| Story context tracking in epics | YES | — |
+| Epic context management | YES | — |
+| Backlog prioritization | YES | — |
+
+### @sm (River) — Story Creation
+
+| Operation | Exclusive? | Details |
+|-----------|-----------|---------|
+| `*draft` / `*create-story` | YES | From epic/PRD |
+| Story template selection | YES | — |
+
+### @dev (Dex) — Implementation
+
+| Allowed | Blocked |
+|---------|---------|
+| `git add`, `git commit`, `git status` | `git push` (delegate to @devops) |
+| `git branch`, `git checkout`, `git merge` (local) | `gh pr create/merge` (delegate to @devops) |
+| `git stash`, `git diff`, `git log` | MCP management |
+| Story file updates (File List, checkboxes) | Story file updates (AC, scope, title) |
+
+### @architect (Aria) — Design Authority
+
+| Owns | Delegates To |
+|------|-------------|
+| System architecture decisions | — |
+| Technology selection | — |
+| High-level data architecture | @data-engineer (detailed DDL) |
+| Integration patterns | @data-engineer (query optimization) |
+| Complexity assessment | — |
+
+### @data-engineer (Dara) — Database
+
+| Owns (delegated from @architect) | Does NOT Own |
+|----------------------------------|-------------|
+| Schema design (detailed DDL) | System architecture |
+| Query optimization | Application code |
+| RLS policies implementation | Git operations |
+| Index strategy execution | Frontend/UI |
+| Migration planning & execution | — |
+
+### @aios-master — Framework Governance
+
+| Capability | Details |
+|-----------|---------|
+| Execute ANY task directly | No restrictions |
+| Framework governance | Constitutional enforcement |
+| Override agent boundaries | When necessary for framework health |
+
+## Cross-Agent Delegation Patterns
+
+### Git Push Flow
+```
+ANY agent → @devops *push
+```
+
+### Schema Design Flow
+```
+@architect (decides technology) → @data-engineer (implements DDL)
+```
+
+### Story Flow
+```
+@sm *draft → @po *validate → @dev *develop → @qa *qa-gate → @devops *push
+```
+
+### Epic Flow
+```
+@pm *create-epic → @pm *execute-epic → @sm *draft (per story)
+```
+
+## Escalation Rules
+
+1. Agent cannot complete task → Escalate to @aios-master
+2. Quality gate fails → Return to @dev with specific feedback
+3. Constitutional violation detected → BLOCK, require fix before proceed
+4. Agent boundary conflict → @aios-master mediates

package/.claude/rules/coderabbit-integration.md

@@ -0,0 +1,93 @@
+# CodeRabbit Integration — Detailed Rules
+
+## Self-Healing Configuration
+
+### Dev Phase (@dev — Story Development Cycle Phase 3)
+
+```yaml
+mode: light
+max_iterations: 2
+timeout_minutes: 30
+severity_filter: [CRITICAL, HIGH]
+behavior:
+  CRITICAL: auto_fix
+  HIGH: auto_fix (iteration < 2) else document_as_debt
+  MEDIUM: document_as_debt
+  LOW: ignore
+```
+
+**Flow:**
+```
+RUN CodeRabbit → CRITICAL found?
+  YES → auto-fix (iteration < 2) → Re-run
+  NO → Document HIGH as debt, proceed
+After 2 iterations with CRITICAL → HALT, manual intervention
+```
+
+### QA Phase (@qa — QA Loop Pre-Review)
+
+```yaml
+mode: full
+max_iterations: 3
+timeout_minutes: 30
+severity_filter: [CRITICAL, HIGH]
+behavior:
+  CRITICAL: auto_fix
+  HIGH: auto_fix
+  MEDIUM: document_as_debt
+  LOW: ignore
+```
+
+**Flow:**
+1. Pre-commit review scan
+2. Self-healing loop (max 3 iterations)
+3. Manual QA analysis (architectural, traceability, NFR)
+4. Gate decision (verdict)
+
+## Severity Handling Summary
+
+| Severity | Dev Phase | QA Phase |
+|----------|-----------|----------|
+| CRITICAL | auto_fix, block if persists | auto_fix, block if persists |
+| HIGH | auto_fix, document if fails | auto_fix, document if fails |
+| MEDIUM | document_as_tech_debt | document_as_tech_debt |
+| LOW | ignore | ignore |
+
+## WSL Execution (Windows)
+
+```bash
+# Self-healing mode (automatic in dev tasks)
+wsl bash -c 'cd /mnt/c/.../aios-core && ~/.local/bin/coderabbit --severity CRITICAL,HIGH --auto-fix'
+
+# Manual review
+wsl bash -c 'cd /mnt/c/.../aios-core && ~/.local/bin/coderabbit -t uncommitted'
+
+# Prompt-only mode
+wsl bash -c 'cd /mnt/c/.../aios-core && ~/.local/bin/coderabbit --prompt-only -t uncommitted'
+```
+
+## Integration Points
+
+| Workflow | Phase | Trigger | Agent |
+|----------|-------|---------|-------|
+| Story Development Cycle | 3 (Implement) | After task completion | @dev |
+| QA Loop | 1 (Review) | At review start | @qa |
+| Standalone | Any | `*coderabbit-review` command | Any |
+
+## Focus Areas by Story Type
+
+| Story Type | Primary Focus |
+|-----------|--------------|
+| Feature | Code patterns, test coverage, API design |
+| Bug Fix | Regression risk, root cause coverage |
+| Refactor | Breaking changes, interface stability |
+| Documentation | Markdown quality, reference validity |
+| Database | SQL injection, RLS coverage, migration safety |
+
+## Report Location
+
+CodeRabbit reports saved to: `docs/qa/coderabbit-reports/`
+
+## Configuration Reference
+
+Full config in `.aios-core/core-config.yaml` under `coderabbit_integration` section.

package/.claude/rules/ids-principles.md

@@ -0,0 +1,112 @@
+# IDS Principles — Detailed Rules
+
+> Status: Planned (IDS epic is Draft — principles apply as aspirational guidance)
+
+## Decision Hierarchy: REUSE > ADAPT > CREATE
+
+### REUSE (Relevance >= 90%)
+- Use existing artifact directly without modification
+- Import/reference existing entity
+- No justification needed beyond confirming match
+
+### ADAPT (Relevance 60-89%)
+- Adaptability score >= 0.6
+- Changes MUST NOT exceed 30% of original artifact
+- Changes MUST NOT break existing consumers (check usedBy list)
+- Document changes in artifact's change log
+- Update registry relationships
+- Impact analysis required
+
+### CREATE (No suitable match)
+Required justification:
+- `evaluated_patterns`: Existing entities you considered
+- `rejection_reasons`: Why each was rejected (technical reasons)
+- `new_capability`: What unique capability this provides
+- Register in Entity Registry within 24 hours
+- Establish relationships with existing entities
+- Define adaptability constraints for future reuse
+
+## Verification Gates G1-G6
+
+### G1: Epic Creation (@pm)
+- **Type:** Human-in-loop, Advisory
+- **Trigger:** `*create-epic` workflow
+- **Action:** Query registry for related entities, display potentially reusable artifacts
+- **Latency:** < 24h (async)
+- **Blocking:** No
+
+### G2: Story Creation (@sm)
+- **Type:** Human-in-loop, Advisory
+- **Trigger:** `*draft` workflow
+- **Action:** Check existing tasks/templates matching story work
+- **Latency:** < 24h (async)
+- **Blocking:** No
+
+### G3: Story Validation (@po)
+- **Type:** Human-in-loop, Soft Block
+- **Trigger:** `*validate-story-draft` workflow
+- **Action:** Verify referenced artifacts exist, detect potential duplication
+- **Latency:** < 4h (async)
+- **Blocking:** Soft (can override with reason)
+
+### G4: Dev Context (@dev)
+- **Type:** Automated, Informational
+- **Trigger:** Story assignment / `*develop` start
+- **Action:** Display matching patterns as reminder
+- **Latency:** < 2s
+- **Blocking:** NO (logged only for metrics)
+
+### G5: QA Review (@qa)
+- **Type:** Automated, Blocks Merge
+- **Trigger:** PR/merge request
+- **Action:** Check if new artifacts could have reused existing
+- **Latency:** < 30s
+- **Blocking:** YES if new entity without registry entry or justification
+
+### G6: CI/CD (@devops)
+- **Type:** Automated, Blocks Merge
+- **Trigger:** CI pipeline
+- **Action:** Registry integrity check + sync
+- **Latency:** < 60s
+- **Blocking:** YES on CRITICAL, WARN on MEDIUM/LOW
+
+## Override Policy
+
+**Command:** `--override-ids --override-reason "explanation"`
+
+**Permitted when:**
+- Time-critical fix requires immediate creation
+- Adaptation would introduce unacceptable risk
+- Existing artifact is deprecated/frozen
+
+**Requirements:**
+- Logged for audit trail
+- Reviewed within 7 days
+- Include override reason in gate verification log
+
+## Graceful Degradation
+
+All gates implement circuit breaker:
+- **Timeout:** 2s default
+- **On timeout:** warn-and-proceed
+- **On error:** log-and-proceed
+- **Key principle:** Development NEVER blocked by IDS failures
+
+```yaml
+circuit_breaker:
+  failure_threshold: 5
+  success_threshold: 3
+  reset_timeout_ms: 60000
+```
+
+## Article IV-A: Incremental Development (Constitution Amendment)
+
+**Severity:** MUST
+
+**Four Core Rules:**
+1. **Registry Consultation Required** — Query before creating
+2. **Decision Hierarchy** — REUSE > ADAPT > CREATE strictly
+3. **Adaptation Limits** — Changes < 30%, don't break consumers
+4. **Creation Requirements** — Full justification, register within 24h
+
+**Reference:** `docs/stories/epics/epic-ids-incremental-development/`

package/.claude/rules/story-lifecycle.md

@@ -0,0 +1,139 @@
+# Story Lifecycle — Detailed Rules
+
+## Status Progression
+
+```
+Draft → Ready → InProgress → InReview → Done
+```
+
+| Status | Trigger | Agent | Action |
+|--------|---------|-------|--------|
+| Draft | @sm creates story | @sm | Story file created |
+| Ready | @po validates (GO) | @po | **MUST update status field in story file from Draft → Ready** |
+| InProgress | @dev starts implementation | @dev | Update status field |
+| InReview | @dev completes, @qa reviews | @qa | Update status field |
+| Done | @qa PASS, @devops pushes | @devops | Update status field |
+
+**CRITICAL:** The `Draft → Ready` transition is the responsibility of @po during `*validate-story-draft`. When verdict is GO (including conditional GO after fixes are applied), @po MUST update the story's Status field to `Ready` and log the transition in the Change Log. A story left in `Draft` after a GO verdict is a process violation.
+
+## Phase 1: Create (@sm)
+
+**Task:** `create-next-story.md`
+**Inputs:** PRD sharded, epic context
+**Output:** `{epicNum}.{storyNum}.story.md`
+
+## Phase 2: Validate (@po)
+
+**Task:** `validate-next-story.md`
+
+### 10-Point Validation Checklist
+
+1. Clear and objective title
+2. Complete description (problem/need explained)
+3. Testable acceptance criteria (Given/When/Then preferred)
+4. Well-defined scope (IN and OUT clearly listed)
+5. Dependencies mapped (prerequisite stories/resources)
+6. Complexity estimate (points or T-shirt sizing)
+7. Business value (benefit to user/business clear)
+8. Risks documented (potential problems identified)
+9. Criteria of Done (clear definition of complete)
+10. Alignment with PRD/Epic (consistency with source docs)
+
+**Decision:** GO (≥7/10) or NO-GO (<7/10 with required fixes)
+
+## Phase 3: Implement (@dev)
+
+**Task:** `dev-develop-story.md`
+
+### Execution Modes
+
+**YOLO (autonomous):**
+- 0-1 prompts
+- Decisions logged in `decision-log-{story-id}.md`
+- Best for: simple, deterministic tasks
+
+**Interactive (default):**
+- 5-10 prompts with educational checkpoints
+- Confirmations at key decision points
+- Best for: learning, complex decisions
+
+**Pre-Flight (plan-first):**
+- All questions upfront (10-15 prompts)
+- Generates execution plan
+- Then zero-ambiguity execution
+- Best for: ambiguous requirements, critical work
+
+### CodeRabbit Self-Healing in Dev Phase
+
+```
+iteration = 0
+while CRITICAL issues found AND iteration < 2:
+  auto-fix CRITICAL/HIGH
+  iteration++
+if CRITICAL persist after 2 iterations:
+  HALT — manual intervention required
+```
+
+## Phase 4: QA Gate (@qa)
+
+**Task:** `qa-gate.md`
+
+### 7 Quality Checks
+
+1. **Code review** — patterns, readability, maintainability
+2. **Unit tests** — adequate coverage, all passing
+3. **Acceptance criteria** — all met per story AC
+4. **No regressions** — existing functionality preserved
+5. **Performance** — within acceptable limits
+6. **Security** — OWASP basics verified
+7. **Documentation** — updated if necessary
+
+### Gate Decisions
+
+| Decision | Score | Action |
+|----------|-------|--------|
+| PASS | All checks OK | Approve, proceed to @devops push |
+| CONCERNS | Minor issues | Approve with observations documented |
+| FAIL | HIGH/CRITICAL issues | Return to @dev with feedback |
+| WAIVED | Issues accepted | Approve with waiver documented (rare) |
+
+### Gate File Structure
+
+```yaml
+storyId: STORY-42
+verdict: PASS | CONCERNS | FAIL | WAIVED
+issues:
+  - severity: low | medium | high
+    category: code | tests | requirements | performance | security | docs
+    description: "..."
+    recommendation: "..."
+```
+
+## QA Loop (Iterative Review-Fix)
+
+```
+@qa review → verdict → @dev fixes → re-review (max 5 iterations)
+```
+
+**Commands:**
+- `*qa-loop {storyId}` — Start full loop
+- `*stop-qa-loop` — Pause and save state
+- `*resume-qa-loop` — Resume from saved state
+- `*escalate-qa-loop` — Force manual escalation
+
+**Escalation triggers:**
+- max_iterations_reached (default: 5)
+- verdict_blocked
+- fix_failure (after retries)
+- manual_escalate (user command)
+
+**Status:** Tracked in `qa/loop-status.json`
+
+## Story File Update Rules
+
+| Section | Who Can Edit |
+|---------|-------------|
+| Title, Description, AC, Scope | @po only |
+| File List, Dev Notes, checkboxes | @dev |
+| QA Results | @qa only |
+| Change Log | Any agent (append only) |