aios-core 4.2.15 → 4.4.0

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

@@ -0,0 +1,101 @@
+---
+paths:
+  - ".aios-core/**"
+  - "tests/**"
+  - "packages/**"
+  - "bin/**"
+---
+
+# 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,119 @@
+---
+paths:
+  - ".aios-core/**"
+  - "packages/**"
+  - "bin/**"
+---
+
+# 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,145 @@
+---
+paths:
+  - "docs/stories/**"
+  - ".aios-core/development/**"
+---
+
+# 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) |

package/.claude/rules/tool-examples.md

@@ -0,0 +1,64 @@
+# Tool Input Examples — Selection Guidance
+
+## Purpose
+
+Improve tool selection accuracy by providing concrete input examples for the most-used tools. When choosing which tool to use, reference these examples to match the current task to the correct tool.
+
+## ADR-5 Compliance
+
+These examples apply ONLY to always-loaded (Tier 1/2) and essential Tier 3 tools. Non-essential Tier 3 tools are discovered via tool search — do NOT reference examples for them.
+
+## Tool Examples
+
+### context7 — Library Documentation Lookup
+Use when you need up-to-date documentation for a library or framework.
+- **React docs:** `resolve-library-id("react")` then `get-library-docs` with topic "server components"
+- **Supabase RLS:** `resolve-library-id("supabase")` then `get-library-docs` with topic "row level security"
+- **Jest mocks:** `resolve-library-id("jest")` then `get-library-docs` with topic "mock functions"
+
+### git — Version Control
+Use for repository state, history, and branch management.
+- **Check changes:** `git diff --stat` — file-level summary of uncommitted changes
+- **Recent history:** `git log --oneline -10` — last 10 commits with conventional messages
+- **Branch comparison:** `git diff main...HEAD --stat` — all changes since branching from main
+
+### coderabbit — Automated Code Review
+Use before commits and PRs for quality validation. Runs in WSL.
+- **Pre-commit:** `wsl bash -c 'cd /mnt/c/.../aios-core && ~/.local/bin/coderabbit --prompt-only -t uncommitted'`
+- **Pre-PR:** `wsl bash -c 'cd /mnt/c/.../aios-core && ~/.local/bin/coderabbit --prompt-only --base main'`
+
+### browser — Web Testing
+Use for UI validation, console checks, and web interaction.
+- **Navigate:** Open `http://localhost:3000` to inspect the running app
+- **Console check:** Navigate to a page and check for JavaScript errors/warnings
+
+### supabase — Database Operations
+Use for migrations and database management.
+- **Apply migrations:** `supabase db push`
+- **Check status:** `supabase migration list`
+
+### github-cli — GitHub Operations
+Use for PRs, issues, and repository management. `@devops` exclusive for push/PR.
+- **Create PR:** `gh pr create --title 'feat: ...' --body '## Summary...'`
+- **List issues:** `gh issue list --state open --label bug`
+- **PR status:** `gh pr view 123 --json reviews,statusCheckRollup`
+
+### nogic — Code Intelligence (Essential)
+Use for code analysis, dependency tracking, and usage patterns.
+- **Dependencies:** Analyze import chain for a specific module
+- **Usages:** Find all locations where a function is called
+
+### code-graph — Dependency Analysis (Essential)
+Use for dependency graphs and circular dependency detection.
+- **Dependency tree:** Generate graph for a package with configurable depth
+- **Circular check:** Detect circular dependency chains in the project
+
+### docker-gateway — MCP Infrastructure
+Use for managing Docker-based MCP servers. `@devops` manages infrastructure.
+- **Health check:** `curl http://localhost:8080/health`
+- **List servers:** `docker mcp server ls`
+
+## Reference
+
+Full examples registry: `.aios-core/data/mcp-tool-examples.yaml`
+Tool registry: `.aios-core/data/tool-registry.yaml`

package/.claude/rules/tool-response-filtering.md

@@ -0,0 +1,57 @@
+---
+paths:
+  - .aios-core/data/tool-registry.yaml
+  - .mcp.json
+---
+# Tool Response Filtering — Dynamic Token Reduction
+
+When processing responses from MCP tools or large web fetches, apply the filter
+configuration defined in `.aios-core/data/tool-registry.yaml` for the tool that
+produced the response. This reduces context token consumption without losing
+task-relevant information.
+
+## Filter Types
+
+### content
+Extract the main informational content and discard noise (navigation, ads,
+boilerplate, repetitive headers/footers). Limit the extracted output to
+approximately `max_tokens` tokens, truncating at a natural paragraph or
+sentence boundary. If `extract` fields are specified, prioritize those
+fields from the response object.
+
+**Apply to:** WebFetch HTML responses, EXA search results, Context7 docs.
+
+### schema
+From a JSON object or array of objects, select ONLY the fields listed in
+`fields`. Discard all other keys. If `max_tokens` is set, truncate the
+serialized result at that token limit.
+
+**Apply to:** Playwright page data, API responses with known schemas.
+
+### field
+From an array of objects (tabular data), project ONLY the columns listed
+in `fields` and limit the result to `max_rows` rows. This is analogous to
+`SELECT field1, field2 FROM data LIMIT max_rows`.
+
+**Apply to:** Apify scraper results, database query results, CSV-like data.
+
+## How to Apply
+
+1. After receiving a tool response, identify the tool name.
+2. Look up the tool in `tool-registry.yaml` → check for a `filter` key.
+3. If a filter exists, apply the corresponding type rules above.
+4. If NO filter exists for the tool, use the full response as-is.
+5. Present the filtered result in your reasoning — do NOT repeat the raw
+   unfiltered payload.
+
+## Fallback
+
+If the filter would remove ALL content (empty result), fall back to the
+full unfiltered response. Never produce an empty result from filtering.
+
+## Performance Note
+
+This is a zero-overhead optimization. The filter is applied during your
+reasoning step — no external scripts are invoked. The utility scripts at
+`.aios-core/utils/filters/` are available for batch post-processing of
+saved responses but are NOT required during normal tool use.

package/.claude/rules/workflow-execution.md

@@ -0,0 +1,150 @@
+# Workflow Execution — Detailed Rules
+
+## Task-First Principle
+
+**Workflows são compostos por tasks conectadas, não por agentes conectados.** Cada task define seus inputs, outputs, pre/post-conditions e execution modes. Os agentes listados abaixo são os **executores padrão** de cada task — mas a sequência, as regras e as dependências vêm das definições de tasks em `.aios-core/development/tasks/`.
+
+Uma task validada é lei: deve ser executada conforme configurada, com todas as suas dependências respeitadas, independente de quem a executa (agent, worker, clone ou humano).
+
+---
+
+## 4 Primary Workflows
+
+### 1. Story Development Cycle (SDC) — PRIMARY
+
+**Full 4-phase workflow for all development work.**
+
+#### Phase 1: Create (@sm)
+- **Task:** `create-next-story.md`
+- **Inputs:** PRD sharded, epic context
+- **Output:** `{epicNum}.{storyNum}.story.md`
+- **Status:** Draft
+
+#### Phase 2: Validate (@po)
+- **Task:** `validate-next-story.md`
+- **10-point checklist** (see `story-lifecycle.md`)
+- **Decision:** GO (>=7) or NO-GO (required fixes listed)
+
+#### Phase 3: Implement (@dev)
+- **Task:** `dev-develop-story.md`
+- **Modes:** Interactive / YOLO / Pre-Flight
+- **CodeRabbit:** Self-healing max 2 iterations
+- **Status:** Ready → InProgress
+
+#### Phase 4: QA Gate (@qa)
+- **Task:** `qa-gate.md`
+- **7 quality checks** (see `story-lifecycle.md`)
+- **Decision:** PASS / CONCERNS / FAIL / WAIVED
+- **Status:** InProgress → InReview → Done
+
+---
+
+### 2. QA Loop — ITERATIVE REVIEW
+
+**Automated review-fix cycle after initial QA gate.**
+
+```
+@qa review → verdict → @dev fixes → re-review (max 5)
+```
+
+**Commands:**
+- `*qa-loop {storyId}` — Start loop
+- `*qa-loop-review` — Resume from review
+- `*qa-loop-fix` — Resume from fix
+- `*stop-qa-loop` — Pause, save state
+- `*resume-qa-loop` — Resume from state
+- `*escalate-qa-loop` — Force escalation
+
+**Config:**
+- Max iterations: 5 (`autoClaude.qaLoop.maxIterations`)
+- Status file: `qa/loop-status.json`
+
+**Verdicts:**
+- APPROVE → Complete, mark Done
+- REJECT → @dev fixes, re-review
+- BLOCKED → Escalate immediately
+
+**Escalation triggers:**
+- `max_iterations_reached`
+- `verdict_blocked`
+- `fix_failure`
+- `manual_escalate`
+
+---
+
+### 3. Spec Pipeline — PRE-IMPLEMENTATION
+
+**Transform informal requirements into executable spec.**
+
+| Phase | Agent | Output | Skip If |
+|-------|-------|--------|---------|
+| 1. Gather | @pm | `requirements.json` | Never |
+| 2. Assess | @architect | `complexity.json` | source=simple |
+| 3. Research | @analyst | `research.json` | SIMPLE class |
+| 4. Write Spec | @pm | `spec.md` | Never |
+| 5. Critique | @qa | `critique.json` | Never |
+| 6. Plan | @architect | `implementation.yaml` | If APPROVED |
+
+**Complexity Classes:**
+
+| Score | Class | Phases |
+|-------|-------|--------|
+| <= 8 | SIMPLE | gather → spec → critique (3) |
+| 9-15 | STANDARD | All 6 phases |
+| >= 16 | COMPLEX | 6 phases + revision cycle |
+
+**5 Complexity Dimensions (scored 1-5):**
+- **Scope:** Files affected
+- **Integration:** External APIs
+- **Infrastructure:** Changes needed
+- **Knowledge:** Team familiarity
+- **Risk:** Criticality level
+
+**Critique Verdicts:**
+
+| Verdict | Average Score | Next Step |
+|---------|--------------|-----------|
+| APPROVED | >= 4.0 | Plan (Phase 6) |
+| NEEDS_REVISION | 3.0-3.9 | Revise (Phase 5b) |
+| BLOCKED | < 3.0 | Escalate to @architect |
+
+**Constitutional Gate (Article IV — No Invention):**
+Every statement in spec.md MUST trace to FR-*, NFR-*, CON-*, or research finding. NO invented features.
+
+---
+
+### 4. Brownfield Discovery — LEGACY ASSESSMENT
+
+**10-phase technical debt assessment for existing codebases.**
+
+**Data Collection (Phases 1-3):**
+- Phase 1: @architect → `system-architecture.md`
+- Phase 2: @data-engineer → `SCHEMA.md` + `DB-AUDIT.md` (if DB exists)
+- Phase 3: @ux-design-expert → `frontend-spec.md`
+
+**Draft & Validation (Phases 4-7):**
+- Phase 4: @architect → `technical-debt-DRAFT.md`
+- Phase 5: @data-engineer → `db-specialist-review.md`
+- Phase 6: @ux-design-expert → `ux-specialist-review.md`
+- Phase 7: @qa → `qa-review.md` (QA Gate: APPROVED | NEEDS WORK)
+
+**Finalization (Phases 8-10):**
+- Phase 8: @architect → `technical-debt-assessment.md` (final)
+- Phase 9: @analyst → `TECHNICAL-DEBT-REPORT.md` (executive)
+- Phase 10: @pm → Epic + stories ready for development
+
+**QA Gate (Phase 7):**
+- **APPROVED:** All debits validated, no critical gaps, dependencies mapped
+- **NEEDS WORK:** Gaps not addressed, return to Phase 4
+
+---
+
+## Workflow Selection Guide
+
+| Situation | Workflow |
+|-----------|---------|
+| New story from epic | Story Development Cycle |
+| QA found issues, need iteration | QA Loop |
+| Complex feature needs spec | Spec Pipeline → then SDC |
+| Joining existing project | Brownfield Discovery |
+| Simple bug fix | SDC only (YOLO mode) |