diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 41ae14debf..d57e89bfaa 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -45,7 +45,7 @@ The installer writes this automatically during `npx aiox-core install`. No langu O Synkra AIOX segue uma hierarquia clara de prioridades que deve guiar **TODAS** as decisões: -``` +```text CLI First → Observability Second → UI Third ``` @@ -70,7 +70,7 @@ CLI First → Observability Second → UI Third ## Estrutura do Projeto -``` +```text aiox-core/ ├── .aiox-core/ # Core do framework │ ├── core/ # Módulos principais (orchestration, memory, etc.) @@ -154,7 +154,7 @@ Use prefixo `*` para comandos: 4. **Siga critérios** - Implemente exatamente o que os acceptance criteria especificam ### Workflow de Story -``` +```text @po *create-story → @dev implementa → @qa testa → @devops push ``` diff --git a/.claude/commands/AIOX/stories/story-7.1.1.md b/.claude/commands/AIOX/stories/story-7.1.1.md new file mode 100644 index 0000000000..875d67aea4 --- /dev/null +++ b/.claude/commands/AIOX/stories/story-7.1.1.md @@ -0,0 +1,78 @@ +# Story 7.1.1: Bootstrap /dev Workspace — aiox-dashboard Clone + +**Story ID:** 7.1.1 +**Epic:** Epic-7 - Dashboard Workspace Integration +**Wave:** Wave 1 (Foundation) +**Status:** ⌛ In Progress +**Priority:** 🔴 High +**Owner:** Architect (Aria) → Dev (Dex) +**Created:** 2026-05-05 +**Updated:** 2026-05-05 + +--- + +## 📋 Objective + +Configurar `/dev` como monorepo pai com `aiox-core` e `aiox-dashboard` como projetos irmãos. +O dashboard observa dados do aiox-core via Supabase (read-only). Sem workspace hoisting — projetos independentes. + +--- + +## 🎯 Story + +**As a** desenvolvedor AIOX, +**I want** o `aiox-dashboard` clonado em `C:\dev\aiox-dashboard` com um root `package.json` de conveniência em `C:\dev\`, +**So that** posso rodar e desenvolver CLI + Dashboard em paralelo no mesmo workspace. + +--- + +## ✅ Acceptance Criteria + +- [x] `C:\dev\aiox-dashboard\` existe com clone do repositório `SynkraAI/aiox-dashboard` +- [x] `C:\dev\package.json` existe com scripts de conveniência (`dev`, `dev:core`, `dev:dashboard`, `lint`, `test`) +- [x] `C:\dev\.gitignore` existe cobrindo `node_modules`, `.env`, lock files dos dois projetos +- [x] `C:\dev\aiox-dashboard\.env.local` criado a partir do `.env.example` do dashboard +- [ ] Variáveis Supabase alinhadas entre `aiox-core` e `aiox-dashboard` — **pendente: preencher credenciais** +- [x] `cd C:\dev\aiox-dashboard && npm install` completa sem erros (bun não instalado, npm usado como fallback) +- [ ] Dashboard roda localmente (`npm run dev`) com acesso ao Supabase configurado — **pendente: credenciais Supabase** + +--- + +## 📐 Scope + +**IN:** +- Clone do repositório aiox-dashboard +- Root `package.json` com scripts only (sem workspace hoisting) +- Alinhamento de variáveis de ambiente Supabase +- `.gitignore` raiz + +**OUT:** +- Unificação de workspaces npm (risco CJS/ESM) +- Rename de namespace `@aios/` → `@aiox/` (Story 7.1.2) +- Integração de dados Supabase (Story 7.1.3) +- CI/CD para o dashboard (Story 7.1.4) + +--- + +## 🔗 Dependencies + +- `aiox-core` já configurado em `C:\dev\aiox-core\` +- Bun não instalado; npm usado como fallback +- Credenciais Supabase disponíveis em `C:\dev\aiox-core\.env` + +--- + +## 📁 File List + +- [x] `C:\dev\package.json` — root workspace scripts +- [x] `C:\dev\.gitignore` — root gitignore +- [x] `C:\dev\aiox-dashboard\` — clone do repositório (1358 arquivos) +- [x] `C:\dev\aiox-dashboard\.env.local` — env local do dashboard (Supabase vars aguardando preenchimento) + +--- + +## 📝 Change Log + +| Date | Author | Change | +|------|--------|--------| +| 2026-05-05 | Aria (@architect) | Story criada em YOLO mode | diff --git a/.claude/rules/handoff-consolidation.md b/.claude/rules/handoff-consolidation.md new file mode 100644 index 0000000000..b167913b33 --- /dev/null +++ b/.claude/rules/handoff-consolidation.md @@ -0,0 +1,140 @@ +# Handoff Consolidation — Rule + +## Purpose + +Prevent proliferation of individual handoff YAMLs in long-running pipelines (epics that span 5+ sessions). Consolidate older handoffs into a single `RUN-LOG.md` per epic/pipeline to maintain readability while preserving full history. + +## When This Applies + +- Any pipeline (epic, multi-wave initiative) accumulating handoffs in `.aiox/handoffs/` +- Triggered when **5 or more** handoff YAMLs exist for the same pipeline +- Applies regardless of agent (any agent generating handoffs must observe) + +## Trigger Threshold + +| Handoff count for pipeline | Action | +|---|---| +| 1-4 | Keep as individual YAMLs | +| **5+** | **MUST consolidate** older handoffs into `RUN-LOG.md` | +| 5+ recurrente | Reconsolidar a cada 5 novos handoffs | + +## Consolidation Procedure + +### Step 1 — Identify pipeline handoffs + +Pipelines are grouped by: +- `pipeline_id` field in handoff YAML, OR +- Filename pattern `handoff-{date}-{pipeline-slug}-{wave}.yaml`, OR +- `INDEX-{pipeline-slug}.md` file referencing them + +### Step 2 — Create RUN-LOG.md (if not exists) + +Location options (in priority order): +1. `business-ai-first/docs/stories/epics/{epic-folder}/RUN-LOG.md` (preferred for epic-bound pipelines) +2. `business-ai-first/docs/runlogs/{pipeline-slug}-RUN-LOG.md` (for cross-epic pipelines) +3. `.aiox/run-logs/{pipeline-slug}-RUN-LOG.md` (for framework-level pipelines) + +### Step 3 — Append summarized waves + +For each handoff being consolidated, append a section to `RUN-LOG.md`: + +```markdown +## Wave {N}: {wave_goal} — {date} + +**Status:** ✅ DONE | ⚠️ BLOCKED | 🔄 PARTIAL +**Session:** {session_id or hash} +**Agent:** {primary agent} +**Effort:** {actual hours} + +### Delivered +- {bullet list of files created/modified} +- {ACs completed with IDs} + +### Decisions +- {key architectural/process decisions, link to ADR if applicable} + +### Blockers Resolved +- {what got unblocked this wave} + +### Carry-forward to next wave +- {open items, not blockers} + +### Original handoff +Archived: `.aiox/handoffs/_archive/{filename}.yaml` (or deleted if redundant) +``` + +### Step 4 — Archive or delete originals + +Two options: +- **Archive** (safer): move YAMLs to `.aiox/handoffs/_archive/{pipeline-slug}/` — preserves audit trail +- **Delete** (cleaner): only if RUN-LOG.md captures everything materially relevant — reduces clutter + +**Default: archive**, unless pipeline owner explicitly authorizes deletion. + +### Step 5 — Update INDEX + +Update the pipeline's `INDEX-*.md` (or epic README) to reference RUN-LOG.md instead of individual handoffs. + +## What MUST be Preserved + +In RUN-LOG.md, never lose: +- ❗ Strategic context (why this pipeline exists) +- ❗ Architectural decisions (link to ADRs) +- ❗ Resolved blockers (so they don't get re-investigated) +- ❗ Schema/migration changes applied to prod +- ❗ Open items that next session must address +- ❗ Files created/modified per wave (path list, not content) + +## What CAN be Discarded + +In consolidation, drop: +- Verbose investigation steps (kept the conclusion, not the search) +- Rejected alternatives that were already decided +- Tool call sequences (kept the outcome, not the recipe) +- Repeated context that lives in the master plan or ADRs + +## Latest Handoff Stays Individual + +The **most recent** handoff for an active pipeline stays as `handoff-{latest}.yaml` even after consolidation. RUN-LOG.md is for closed waves. The active handoff is what the next session reads first. + +## Example Structure (after consolidation) + +```text +.aiox/handoffs/ +├── INDEX-meta-messaging-pipeline.md (refs RUN-LOG) +├── handoff-2026-05-15-wave6-current.yaml (latest, active) +└── _archive/ + └── meta-messaging/ + ├── handoff-2026-05-06-wave1.yaml + ├── handoff-2026-05-08-wave2.yaml + ├── handoff-2026-05-10-wave3.yaml + ├── handoff-2026-05-12-wave4.yaml + └── handoff-2026-05-14-wave5.yaml + +business-ai-first/docs/stories/epics/epic-013-portal-replacement/ +└── RUN-LOG.md (waves 1-5 consolidated, narrative form) +``` + +## Authority + +- **Any agent** can consolidate when threshold hit +- **No agent** may delete originals without explicit pipeline owner authorization +- **@devops** owns enforcement during git push reviews + +## Anti-patterns (DO NOT) + +- ❌ Consolidate active handoff (the one next session must read) +- ❌ Lose blocker resolutions in summarization +- ❌ Skip ADR cross-references +- ❌ Consolidate before threshold (premature) +- ❌ Mix multiple pipelines in one RUN-LOG (each pipeline = own log) + +## Migration of Existing Handoffs + +Existing handoff YAMLs that predate this rule should be consolidated retroactively when they cross the 5+ threshold for their pipeline. No need to consolidate orphaned/standalone handoffs. + +--- + +**Established:** 2026-05-06 (during meta-messaging pipeline Wave 1 → Wave 2 transition) +**Owner:** @aiox-master (Orion) +**Enforced by:** all agents during handoff generation; @devops during PR review diff --git a/.claude/settings.json b/.claude/settings.json index e90f019a4c..a0e17ae0f8 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -34,5 +34,6 @@ ] } ] - } + }, + "language": "portuguese" } diff --git a/.env.example b/.env.example index 79c69828ef..7432994a9f 100644 --- a/.env.example +++ b/.env.example @@ -1,53 +1,101 @@ -# AIOX Framework Environment Variables -# Copy this file to .env and fill in your values -# NEVER commit .env files to version control +# ============================================ +# Synkra AIOX Environment Configuration +# ============================================ +# Copy this file to .env and fill in your actual values +# DO NOT commit .env with real credentials +# ============================================ -# ============================================================================= -# AI Provider Configuration -# ============================================================================= +# -------------------------------------------- +# LLM Providers +# -------------------------------------------- -# Anthropic API (Claude) -# Get your key from: https://console.anthropic.com/ -ANTHROPIC_API_KEY=your_anthropic_api_key_here +# DeepSeek API (for claude-free command) +# Get your key at: https://platform.deepseek.com/api_keys +# Cost: ~$0.14/M tokens with tool calling support +DEEPSEEK_API_KEY= -# OpenAI API (optional, for GPT models) -# Get your key from: https://platform.openai.com/api-keys -OPENAI_API_KEY=your_openai_api_key_here +# OpenRouter API (for multi-model routing) +# Get your key at: https://openrouter.ai/keys +OPENROUTER_API_KEY= -# ============================================================================= -# GitHub Integration -# ============================================================================= +# Anthropic API (direct, if not using Claude Max subscription) +# Get your key at: https://console.anthropic.com/ +ANTHROPIC_API_KEY= -# GitHub Personal Access Token (for API operations) +# OpenAI API Key - Get yours at: https://platform.openai.com/api-keys +OPENAI_API_KEY= + +# -------------------------------------------- +# Search & Research Tools +# -------------------------------------------- + +# Exa Search API (web search for agents) +# Get your key at: https://exa.ai/ +EXA_API_KEY= + +# Context7 (library documentation lookup) +# Usually free, no key required for basic usage +CONTEXT7_API_KEY= + +# -------------------------------------------- +# Database & Backend +# -------------------------------------------- + +# Supabase (database, auth, storage) +# Get from your Supabase project settings +SUPABASE_ANON_KEY= +SUPABASE_SERVICE_ROLE_KEY= +SUPABASE_URL= + +# -------------------------------------------- +# Version Control & CI/CD +# -------------------------------------------- + +# GitHub Token (for GitHub CLI and API access) # Create at: https://github.com/settings/tokens -GITHUB_TOKEN=your_github_token_here +GITHUB_TOKEN= -# ============================================================================= -# AIOX Framework Settings -# ============================================================================= +# -------------------------------------------- +# Project Management +# -------------------------------------------- -# Enable debug mode for verbose logging -AIOX_DEBUG=false +# ClickUp API (if using ClickUp integration) +# Get from: ClickUp Settings > Apps > API Token +CLICKUP_API_KEY= -# Default AI model to use -AIOX_DEFAULT_MODEL=claude-3-5-sonnet-20241022 +# -------------------------------------------- +# Automation & Workflows +# -------------------------------------------- -# MCP Server settings -AIOX_MCP_ENABLED=true +# N8N (workflow automation) +# From your N8N instance settings +N8N_API_KEY= +N8N_WEBHOOK_URL= -# ============================================================================= -# Development Settings (Optional) -# ============================================================================= +# -------------------------------------------- +# Monitoring & Analytics +# -------------------------------------------- -# Node environment -NODE_ENV=development +# Sentry (error tracking) +SENTRY_DSN= + +# -------------------------------------------- +# Cloud Providers +# -------------------------------------------- -# Log level (debug, info, warn, error) -LOG_LEVEL=info +# Railway (deployment) +RAILWAY_TOKEN= -# ============================================================================= -# Testing (CI/CD) -# ============================================================================= +# Vercel (deployment) +VERCEL_TOKEN= + +# -------------------------------------------- +# AIOX Core Configuration +# -------------------------------------------- +AIOX_VERSION=2.2.0 +NODE_ENV=development -# CI environment flag (set by GitHub Actions) -# CI=true +# -------------------------------------------- +# Custom Configuration +# -------------------------------------------- +# Add your custom API keys below diff --git a/audits/README.md b/audits/README.md new file mode 100644 index 0000000000..3159702301 --- /dev/null +++ b/audits/README.md @@ -0,0 +1,31 @@ +# aiox-core/audits/ + +Cross-project audit reports and AuditFinding artifacts. Part of the AIOX Framework Evolution Pipeline. + +See [`../governance/evolution-pipeline.md`](../governance/evolution-pipeline.md) for the full pipeline spec. + +## Layout + +```text +audits/ +├── README.md # this file +├── .md # human-readable audit reports (e.g., c-dev-organization-2026-05-07.md) +├── promoted/ # AuditFindings flagged framework_candidate: true +│ └── AF--.yaml +└── archived/ # AuditFindings that stayed scope-bound (project-only) + └── AF--.yaml +``` + +## When to write an audit here + +Write a narrative `.md` audit report at this folder root when: +- Scope crosses 2+ projects, or +- Topic is workspace-level (e.g., `C:/dev/` organization, cross-cutting tooling) + +Write a structured AuditFinding YAML in `promoted/` when: +- A specific finding may evolve into framework changes +- See template at `../governance/templates/audit-finding-tmpl.yaml` + +## Authority + +Any agent may author an audit. Promotion to a framework proposal requires Eliel's approval (see pipeline doc). diff --git a/audits/c-dev-organization-2026-05-07.md b/audits/c-dev-organization-2026-05-07.md new file mode 100644 index 0000000000..051698dcb1 --- /dev/null +++ b/audits/c-dev-organization-2026-05-07.md @@ -0,0 +1,195 @@ +# Audit — `C:/dev` Workspace Organization + +**Date:** 2026-05-07 +**Auditor:** @aiox-master (Orion) +**Triggered by:** Eliel sinalizou desorganização durante sessão de correção Wave 1.A +**Scope:** all of `C:/dev/` — projects, worktrees, loose files, asset directories +**Status:** Audit complete — proposal awaiting Eliel approval before any move/delete + +--- + +## Inventory snapshot (2026-05-07T18:35Z) + +`C:/dev/` has **84 entries**. Counts by type: + +| Category | Count | +|---|---| +| Project repositories | 6 | +| Active git worktrees | 5 (under `business-ai-first`) | +| Audit/data assets | 1 (`db-inventory`) | +| Loose `.md` documents | 5 | +| Loose `.png` images | 51 | +| Loose `.csv` files | 2 | +| Mystery directories | 5 (`.agents`, `agents`, `architecture`, `docker`, `kommo-sync`) | +| Other | misc | + +### Disk usage by project + +| Path | Size | Status | +|---|---:|---| +| `business-ai-first/` | 1.5 GB | ✅ Active project | +| `aiox-dashboard/` | 1.1 GB | ⚠️ Status unknown — needs review | +| `aiox-core/` | 303 MB | ✅ Framework (this repo) | +| `cadastro-rapido/` | 300 MB | ⚠️ Active or legacy? Confirm with Eliel | +| `kommo-sync/` | 160 MB | ⚠️ Likely legacy ETL | +| `db-inventory/` | 2.2 MB | ✅ Cross-project audit asset | +| `cdm-portal/` | 7 KB | ⚠️ Empty stub — worktree leftover or new project | + +--- + +## Classification + +### A. Active projects (KEEP, current location) + +| Path | Role | Owner | +|---|---|---| +| `aiox-core/` | Framework canonical source | @aiox-master maintainers | +| `business-ai-first/` | Project consumer of AIOX (CDM operations) | Eliel | + +### B. Cross-project assets (KEEP, possibly elevate) + +| Path | Role | Recommendation | +|---|---|---| +| `db-inventory/` | DB schema dictionary, snapshots, audit reports across projects | Keep at root. Add `OWNERSHIP.md` declaring it's framework-aligned shared asset, owned by `@data-engineer`. Consumed by all DB-touching projects. | + +### C. Worktrees (REVIEW + cleanup recommended) + +5 worktrees registered to `business-ai-first`: + +| Worktree | Branch | State | Recommendation | +|---|---|---|---| +| `bai-dbops-v1-exam-purposes` | `feat/dbops-v1-exam-purposes` | V1 reverted (PR #68 merged then logically reverted in #72). Worktree obsolete. | **REMOVE** — `git worktree remove` + `git push origin --delete feat/dbops-v1-exam-purposes` | +| `bai-dbops-v5-audit-triggers` | `feat/dbops-v5-audit-triggers` | V5 merged + applied to prod | **REMOVE** | +| `bai-dbops-v7-financial-view` | `feat/dbops-v7-financial-view` | V7 merged + applied to prod (uncommitted `supabase/.temp/cli-latest`) | **REMOVE** after stashing the temp file | +| `bai-strategy-drafting` | `docs/cdm-strategy-stories-conrado` | EPIC-014 Conrado strategy (paused) | **PRESERVE** until EPIC-014 unpauses; document in EPIC-014 RUN-LOG | +| `bai-w0-foundation` | `feat/cdm-ui-010-foundation` | EPIC-014 W0 foundation (paused) | **PRESERVE** until EPIC-014 unpauses | + +Cleanup blocker: each worktree may have an active Claude Code session — Eliel must close those terminals before `git worktree remove` succeeds. + +### D. Possibly active or legacy (CONFIRM) + +| Path | Hint | Action | +|---|---|---| +| `aiox-dashboard/` | Listed in `C:/dev/CLAUDE.md` as "AIOS Platform UI — Vite + React" | Likely active. Keep. Check if part of current epic. | +| `cadastro-rapido/` | Vercel-deployed Next.js portal `cadastro-rapido-gamma.vercel.app` referenced in EPIC-MVP-CDM-CADASTRO | **Likely active**. EPIC-MVP-CDM-CADASTRO Wave 4 expects this repo to receive form changes. Confirm with Eliel. | +| `kommo-sync/` | Legacy ETL scripts (Kommo CRM → Supabase). 160 MB. | If ETL pipeline migrated to n8n: **archive** to `aiox-core/archive/legacy-etl/` or external backup. If still in use: keep + add `OWNERSHIP.md`. | +| `cdm-portal/` | 7 KB — empty stub. Has `CLAUDE.md` and `README.md` and empty `core/`. | Either: (a) WIP project to be developed → keep, document; (b) abandoned scaffold → **delete**. **Confirm with Eliel.** | + +### E. Mystery directories (INVESTIGATE) + +| Path | Contents | Initial assessment | +|---|---|---| +| `.agents/` | Hidden dotdir — likely tool config or backup | Inspect content. Likely safe to relocate inside `aiox-core/` if framework-bound. | +| `agents/` | Contains `skills/` subdirectory | Probably stale duplicate of `aiox-core/skills` or independent agent definitions. **Investigate before action.** | +| `architecture/` | 2 markdown files: `cadastro-rapido-schema-alignment.md`, `data-pipeline-architecture.md` | Cross-project architecture docs. **Move to `aiox-core/docs/architecture/cross-project/` or to the relevant project repo.** | +| `docker/` | Contains `docker/` subdirectory (nested) | Likely Docker compose/setup for development. **Move to `aiox-core/infrastructure/docker/`** if framework-shared, or document as required local toolchain. | +| `kommo-sync/` | (already classified above as D) | Same | + +### F. Loose files (RELOCATE) + +#### Loose `.md` (5 files — at root level) + +| File | Likely destination | +|---|---| +| `AIOX-NOTEBOOK-FINDINGS.md` (17 KB) | `aiox-core/docs/research/notebooklm/` — these are research artifacts | +| `AIOX-NOTEBOOK-QUESTIONS.md` (20 KB) | `aiox-core/docs/research/notebooklm/` | +| `AIOX-PHASES-COMPLETED.md` (10 KB) | `aiox-core/docs/history/` or `aiox-core/CHANGELOG.md` excerpt | +| `CLAUDE.md` (1.5 KB) | **KEEP** at root — it's the workspace root CLAUDE.md, used by Claude Code | +| `GUIA-AUTONOMIA-ECONOMIA-TOKENS.md` (68 KB) | `aiox-core/docs/guides/token-economy/` | + +#### Loose `.png` (51 files — at root level) + +51 images of forms screenshots, message templates, agent OS diagrams, profile picture. Suggested: + +| Pattern | Count | Destination | +|---|---:|---| +| `Forms_Cadastro_*.png` | 3 | `business-ai-first/docs/research/kommo-forms-pre-deactivation/` | +| `msg-template-*.png` | 43 | `business-ai-first/db-inventory/wa-templates-screenshots/` (already part of EPIC-013.10 wave9 seed source) | +| `all-msg-template-kommo-crm-meta-whatsapp.png` | 1 | Same as above | +| `agents_os-1.png`, `agents_os-2.png` | 2 | `aiox-core/docs/diagrams/` | +| `[CM] Perfil 512x512 px.png` | 1 | Personal asset — **move to `C:/Users/eliel/`** or business-ai-first/assets/brand/ | +| `whatsapp_business_screenshots*.png` | varies | `business-ai-first/db-inventory/wa-business/` | + +#### Loose `.csv` (2 files) + +| File | Destination | +|---|---| +| `[CM] Dados CRM.csv` | `business-ai-first/db-inventory/exports/2026-05-07/` | +| `[CM] Dados CRM_v2.csv` | Same | + +--- + +## Proposed target structure + +```text +C:/dev/ +├── CLAUDE.md # workspace root config (keep) +├── .gitignore # workspace gitignore (keep) +├── aiox-core/ # framework canonical +│ ├── audits/ # cross-project audit reports (NEW — this file lives here) +│ ├── governance/ # evolution pipeline + handoff types (NEW) +│ ├── docs/ +│ │ ├── architecture/cross-project/ # moved from C:/dev/architecture +│ │ ├── research/notebooklm/ # moved from C:/dev/AIOX-*.md +│ │ └── guides/token-economy/ # moved from C:/dev/GUIA-*.md +│ ├── infrastructure/docker/ # moved from C:/dev/docker (if framework-shared) +│ └── archive/ # for legacy assets that we don't want to delete +│ └── legacy-etl/ # if kommo-sync becomes legacy +├── business-ai-first/ # project (active epic CDM) +│ ├── docs/research/kommo-forms-pre-deactivation/ # moved from loose Forms_*.png +│ └── db-inventory/exports/ # moved from loose [CM] *.csv +├── aiox-dashboard/ # AIOS Platform UI (confirm active) +├── cadastro-rapido/ # Next.js portal (confirm active) +├── cdm-portal/ # confirm if active or delete +├── db-inventory/ # cross-project DB asset (keep at root, add OWNERSHIP.md) +└── archive/ # workspace-level archive for things we want to keep but not active + └── kommo-sync/ # if legacy +``` + +**Worktrees** (`bai-*`) live next to the parent project after cleanup of the 3 done ones. + +**Loose images and CSVs** all relocate to relevant project subdirectories or framework docs. + +--- + +## Decision matrix for Eliel + +| Action | Risk | Reversibility | Recommendation | +|---|---|---|---| +| Remove 3 done worktrees (V1/V5/V7) | Low | High (just delete) | **APPROVE** | +| Preserve 2 EPIC-014 worktrees | None | N/A | **APPROVE** | +| Move 5 loose `.md` to framework docs | Low | High (git mv) | **APPROVE pending project assignments** | +| Move 51 `.png` to project subdirs | Low | High | **APPROVE pending classification** | +| Investigate `.agents/`, `agents/`, `docker/` | Low (read-only) | N/A | **APPROVE** — I do this in next session | +| Confirm `cadastro-rapido` active | None (informational) | N/A | **Eliel must answer** | +| Confirm `cdm-portal` active or stub | None | N/A | **Eliel must answer** | +| Confirm `kommo-sync` legacy or active | None | N/A | **Eliel must answer** | +| Confirm `aiox-dashboard` active | None | N/A | **Eliel must answer** | +| Create `aiox-core/governance/` and `audits/` | Low | High | **APPROVE** — already creating in this session | +| Add `OWNERSHIP.md` to `db-inventory/` | Low | High | **APPROVE** | + +--- + +## Open questions for Eliel (before any move) + +1. **`cadastro-rapido/`** — repo onde EPIC-MVP-CDM-CADASTRO Wave 4 vai entregar os 3 forms. Manter ativo? Promover a primary project? +2. **`aiox-dashboard/`** — qual é o status real desse projeto? Ativo, paused, archived? +3. **`cdm-portal/` (7 KB stub)** — projeto futuro, abandonado, ou worktree órfã? +4. **`kommo-sync/`** — ETL ainda em uso ou pode arquivar (está marcado como pausado em B4 do handoff Wave 0)? +5. **Loose images** — pode usar regex de padrão para mover em batch ou prefere classificar manualmente para evitar perda? + +Sem respostas, audit fica com recomendação. Não vou mover nada sem aprovação explícita. + +--- + +## Linked artifacts + +- `aiox-core/governance/evolution-pipeline.md` (Entrega 3, sister artifact) — defines how this audit gets promoted into framework convention +- `aiox-core/governance/squad-activation-strategy.md` (Entrega 4) — how `@aiox-master` should consult this kind of cross-cutting audit before delegating + +--- + +## Author signature + +— Orion (`@aiox-master`), conduzindo audit estrutural por solicitação de Eliel após sessão de correção Wave 1.A. +Padrão de output: this file (audit narrative) + machine-readable accompanying YAML if Eliel approves promotion to actionable runbook. diff --git a/audits/promoted/AF-20260507-aiox-master-routing-gap.yaml b/audits/promoted/AF-20260507-aiox-master-routing-gap.yaml new file mode 100644 index 0000000000..b1fd0bd3f4 --- /dev/null +++ b/audits/promoted/AF-20260507-aiox-master-routing-gap.yaml @@ -0,0 +1,60 @@ +audit_finding: + version: "1.0" + id: "AF-20260507-aiox-master-routing-gap" + date: "2026-05-07T18:30:00Z" + auditor: "@aiox-master (Orion)" + source_session: "Eliel diagnostic during Wave 1.A correction: 'sentimos falta do uso ativo dos squads como opção específica, sinto que ficamos preso ao framework'" + + context: + project: "framework-level (cross-project)" + epic: "n/a" + triggered_by: | + Eliel observed that during Wave 1.A correction session: + - voice-clones squad was never auto-consulted (had to explicitly invoke) + - claude-code-mastery squad never invoked + - audience-engine squad never invoked despite 9 Públicos doctrine relevance + - db-inventory cross-project asset never consulted before migration writes + - sessions burning tokens re-discovering knowledge that exists in dedicated squads + + finding: + summary: "@aiox-master agent has no triage.routing_matrix; never consults squads first even when topic matches their domain." + evidence: + - "aiox-core/.aiox-core/development/agents/aiox-master.md contains zero references to 'squad' or 'triage' or 'routing_matrix'" + - "claude-mastery-chief in aiox-core/squads/claude-code-mastery/ HAS triage.routing_matrix (proves the pattern is known but not adopted at framework root)" + - "Wave 1.A YOLO terminals wrote migration without consulting db-inventory because no triage suggested it" + - "Kira's parecer formal stated: 'vocês perderam tokens descobrindo o que já existia em db-inventory'" + - "Eliel quote: 'todos os plans criados cogitaram em nenhum momento a perfeita integração desses squads'" + impact_observed: + blast_radius: "critical" + affected_artifacts: + - "Every multi-domain task across every AIOX project" + - "Token economy of every Eliel session" + - "Voice-clones squad utilization (~0% auto-invocation rate)" + - "claude-code-mastery squad utilization (~0% from outside the squad itself)" + cost: | + Estimated 30-50% token waste per session due to context redundancy + and missed consultations. Compounds with every new epic. + + framework_candidate: true + framework_candidate_rationale: | + This is THE framework-level concern. @aiox-master is the entry orchestrator + used by every project. Adding triage.routing_matrix at the framework root + propagates the fix to all consumers automatically. + + The pattern is already proven in claude-mastery-chief (squad-internal + triage). Generalizing to cross-squad consultation is a natural extension. + + references: + - kind: governance-doc + path: "aiox-core/governance/squad-activation-strategy.md" + - kind: existing-pattern-source + path: "aiox-core/squads/claude-code-mastery/agents/claude-mastery-chief.md" + - kind: voice-clone-finding + path: "business-ai-first/docs/decisions/ADR-DBOPS-V1-vocabulary-contract-failure.md (Kira section)" + + proposed_disposition: + - "Add triage.routing_matrix block to all aiox-master.md instances (.aiox-core, .antigravity, .claude/commands, .codex, .cursor)" + - "Create aiox-core/.claude/rules/squad-activation.md with conditional consultation rules" + - "Create aiox-core/hooks/squad-suggestion-advisor.cjs (advisory, UserPromptSubmit hook)" + - "Document this pattern at aiox-core/governance/patterns/squad-activation.md" + - "Cross-pollination flow: project agents → squad masters via Evolution Pipeline" diff --git a/audits/promoted/AF-20260507-vocabulary-contract-failure.yaml b/audits/promoted/AF-20260507-vocabulary-contract-failure.yaml new file mode 100644 index 0000000000..515dd8549f --- /dev/null +++ b/audits/promoted/AF-20260507-vocabulary-contract-failure.yaml @@ -0,0 +1,58 @@ +audit_finding: + version: "1.0" + id: "AF-20260507-vocabulary-contract-failure" + date: "2026-05-07T17:00:00Z" + auditor: "@aiox-master (Orion)" + source_session: "Wave 1.A correction in business-ai-first; voice-clone consultation with @fabio-akita, @lucas-montano, @context-engineer" + + context: + project: "business-ai-first" + epic: "EPIC-MVP-CDM-CADASTRO" + triggered_by: | + DBOPS-V1 prod apply failed SQLSTATE 23514 against ~17,354 legacy rows + after PR was merged to master with green static CI but no pgTAP runtime + validation. + + finding: + summary: "YOLO terminal can write a migration with invented vocabulary because no pre-flight forces dictionary lookup; framework lacks Vocabulary Contract pattern." + evidence: + - "DBOPS-V1 used humanized PT-BR vocabulary ('CNH - Primeira Habilitação') invented in YOLO session, never present in db-inventory or any source of truth" + - "5 vocabularies coexist in tox_exams domain: legacy slug, tx_* prefix, humanized invented, English drift, target English" + - "db-inventory/dictionary/ existed but was never read by the YOLO terminal that wrote V1" + - "Static CI (CodeRabbit + Vercel build) passed; runtime pgTAP never executed before PR merge (Docker Desktop off + cm_staff missing migration debt)" + - "Voice-clone parecer formal converged: root cause is missing data contract, not migration syntax" + impact_observed: + blast_radius: "high" + affected_artifacts: + - "DBOPS-V1 migration (REVERTED)" + - "Wave 1.A gate G0 (incorrectly marked passed)" + - "EPIC-MVP-CDM-CADASTRO timeline (Phase 2 + Phase 3 added)" + cost: | + ~80 minutes audit + correction session. + 1 reverted migration + companion pgTAP test. + 4 new deliverables to address root cause: ADR + 6 stories Phase 2 + framework proposals + this finding. + + framework_candidate: true + framework_candidate_rationale: | + Any AIOX-based project that touches a database faces this risk. The fix is + structural and applies framework-wide: + 1. Pre-flight hook forcing db-inventory consult before migration edits + 2. Vocabulary Contract pattern (single YAML source generating SQL CHECK + Zod + TS + LLM context) + 3. @aiox-master triage routing matrix to suggest db-inventory consult + 4. Constitution amendment: Article VII (Vocabulary Contract) + + references: + - kind: ADR + path: "business-ai-first/docs/decisions/ADR-DBOPS-V1-vocabulary-contract-failure.md" + - kind: hook + path: "business-ai-first/.claude/hooks/migration-dictionary-guard.cjs" + - kind: voice-clone-personas + path: "business-ai-first/squads/voice-clones/agents/{fabio-akita,lucas-montano}.md" + - kind: handoff-contract + path: "business-ai-first/.aiox/handoffs/handoff-2026-05-07-phase1-to-phase2-data-contract.yaml" + + proposed_disposition: + - "Promote business-ai-first/.claude/hooks/migration-dictionary-guard.cjs → aiox-core/hooks/ as framework hook" + - "Add Article VII (Vocabulary Contract) to .aiox-core/constitution.md" + - "Document Vocabulary Contract pattern in aiox-core/governance/patterns/vocabulary-store.md" + - "Sister proposal: PROP-20260507-squad-routing-strategy" diff --git a/governance/README.md b/governance/README.md new file mode 100644 index 0000000000..0f0088ceb2 --- /dev/null +++ b/governance/README.md @@ -0,0 +1,36 @@ +# aiox-core/governance/ + +Governance documents for the AIOX framework. This is where the framework's **own evolution rules** live. + +## Documents + +| Document | Purpose | +|---|---| +| [`evolution-pipeline.md`](evolution-pipeline.md) | Defines how the framework evolves: audit → proposal → approval → PR → distribution | +| [`squad-activation-strategy.md`](squad-activation-strategy.md) | Conditional consult-squad-first routing for `@aiox-master` | +| `handoff-types.md` (TBD) | Distinguishes contract handoffs vs micro-handoffs vs phase handoffs | + +## Layout + +```text +governance/ +├── README.md # this file +├── evolution-pipeline.md # core pipeline spec +├── squad-activation-strategy.md # squad routing for @aiox-master +├── proposals/ # FrameworkProposal YAMLs awaiting/processed by Eliel +│ ├── README.md +│ ├── PROP--.yaml +│ └── archive/ # rejected or superseded proposals +├── patterns/ # approved framework patterns +│ ├── README.md # catalog of patterns +│ └── .md +└── templates/ # YAML templates for finding + proposal + ├── audit-finding-tmpl.yaml + └── framework-proposal-tmpl.yaml +``` + +## Authority + +- **Authors of governance docs:** any agent or Eliel +- **Approver of governance changes:** Eliel (sole orchestrator approver) +- **Implementers:** @aiox-master + relevant specialist agents diff --git a/governance/evolution-pipeline.md b/governance/evolution-pipeline.md new file mode 100644 index 0000000000..0fbbc181b8 --- /dev/null +++ b/governance/evolution-pipeline.md @@ -0,0 +1,406 @@ +# AIOX Framework Evolution Pipeline + +**Status:** Draft v1.0 +**Date:** 2026-05-07 +**Author:** @aiox-master (Orion) +**Approval gate:** Eliel M. Alencar (sole orchestrator approver) +**Triggered by:** Sessão de correção Wave 1.A revelou que descobertas de auditoria em projetos consumidores não retornavam ao framework como evolução formal + +--- + +## Purpose + +Define how the AIOX framework (`aiox-core`) evolves from real-world findings discovered in consumer projects (e.g., `business-ai-first`). The framework is not static — it grows via **audited evidence** from production usage. This document specifies the formal pipeline: + +```text +Project audit → Finding → Proposal → Eliel approval → aiox-core PR → Distribution +``` + +Without this pipeline: +- Findings die in project RUN-LOGs +- The same lessons get re-learned in every new epic +- Framework conventions drift as each project re-invents +- Tokens are spent re-discovering what was already discovered + +With this pipeline: +- Every audit finding is a candidate framework evolution +- Eliel as orchestrator decides what is generic enough to promote +- Approved findings ship as framework PRs (rules, agents, hooks, tasks, templates) +- Consumer projects pull the evolved framework on next sync + +--- + +## Roles + +### Auditor (any agent or Eliel) +- Identifies a finding during project work that may have framework-wide implications +- Writes the finding using the AuditFinding template (below) +- Submits to the Proposal Gate + +### Proposer (typically @aiox-master or domain specialist) +- Receives an AuditFinding +- Decides: scope-bound (project-only) vs framework-candidate +- If framework-candidate: drafts a FrameworkProposal using template (below) +- Includes: pattern generalization, target framework artifact, migration path, deprecation plan + +### Approver (Eliel — sole authority) +- Reviews FrameworkProposal +- Decides: APPROVED / REJECTED / NEEDS_REVISION +- If APPROVED: signs the proposal with `eliel_approval` field + timestamp +- Approval triggers PR creation against `aiox-core` + +### Implementer (@aiox-master + relevant specialist) +- Opens PR in `aiox-core` with the changes specified in approved proposal +- Updates: agent definitions, rules, hooks, tasks, templates, governance docs +- Cross-references the source AuditFinding and FrameworkProposal in PR description + +### Distributor (the consumer projects, on demand) +- Consumer project pulls latest `aiox-core` (via npm install / git submodule / vendored copy) +- Existing project conventions evolve to match new framework + +--- + +## Triggers + +A finding becomes a candidate for framework evolution when **at least one** of these is true: + +| Trigger | Example (from Wave 1.A audit) | +|---|---| +| Same problem appears in 2+ projects | (none yet for Wave 1.A — N=1 currently) | +| Same problem could affect any future project of similar type | YOLO terminal inventing vocabulary without dictionary lookup → **could happen in any DB-touching project** | +| Existing framework rule was violated and the violation was undetectable | Rule `prompt-language.md` (English-only for LLM prompts) was violated in `create_nova_coleta`; no enforcement existed | +| Existing framework artifact is missing or insufficient | `@aiox-master` lacks `triage.routing_matrix` for squad consultation | +| Audit reveals architectural convention drift | 5 vocabularies coexist in same domain — needs canonical store pattern | +| Workflow gate is missing or asymmetric | Gate G0 marked passed based on static CI; no runtime validation | + +**Auditor flag:** when writing a finding, the auditor MUST mark `framework_candidate: true|false` with rationale. + +--- + +## Templates + +### AuditFinding (YAML) + +Lives in: `/docs/audits/.yaml` initially. If approved as framework-candidate, copy to `aiox-core/audits/promoted/.yaml`. + +```yaml +audit_finding: + version: "1.0" + id: "AF--" # e.g., AF-20260507-vocabulary-contract-failure + date: "" + auditor: "" + source_session: "" + + context: + project: "" + epic: "" + triggered_by: "" + + finding: + summary: "" + evidence: + - "" + - "" + impact_observed: + blast_radius: "low|medium|high|critical" + affected_artifacts: [""] + cost: "" + + framework_candidate: true|false + framework_candidate_rationale: | + + + references: + - kind: ADR + path: "" + - kind: code + path: "" + + proposed_disposition: + - "" +``` + +### FrameworkProposal (YAML) + +Lives in: `aiox-core/governance/proposals/PROP--.yaml`. + +```yaml +framework_proposal: + version: "1.0" + id: "PROP--" + date: "" + proposer: "" + source_finding: "AF--" + + target: + layer: "L1|L2|L3" # framework boundary layers (see boundary docs) + artifact_type: "agent|rule|hook|task|template|governance|workflow" + artifact_path: "" + operation: "create|modify|deprecate" + + generalization: + pattern_name: "" + when_to_apply: | + + examples_from_other_domains: [""] + + migration_path: + breaking_change: true|false + affected_consumers: [""] + rollout_plan: | + + + deprecation_plan: + deprecates: [""] + sunset_window: "" + + cost_benefit: + cost: "" + benefit: "" + risk: "" + + approval: + eliel_decision: "PENDING|APPROVED|REJECTED|NEEDS_REVISION" + eliel_decision_at: "" + eliel_decision_rationale: | + + revision_request: [""] # filled if NEEDS_REVISION + + implementation: + pr_url: "" + merged_at: "" + distributed_to: [""] +``` + +--- + +## Decision flow + +```text +┌─────────────────────────────────────────────────────────────┐ +│ 1. Project session discovers issue │ +│ (auditor agent or Eliel) │ +└────────────────────────────┬────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 2. Auditor writes AuditFinding YAML │ +│ Lives in /docs/audits/ │ +│ Marks framework_candidate: true|false │ +└────────────────────────────┬────────────────────────────────┘ + │ + ┌──────────────┴──────────────┐ + │ │ + false (scope-bound) true (framework candidate) + │ │ + ▼ ▼ + Project handles it ┌─────────────────────┐ + internally; finding │ 3. @aiox-master or │ + archived in project. │ domain specialist │ + │ drafts │ + │ FrameworkProposal │ + └──────────┬──────────┘ + │ + ▼ + ┌─────────────────────┐ + │ 4. Eliel reviews │ + │ APPROVED / REJECTED │ + │ / NEEDS_REVISION │ + └──────────┬──────────┘ + │ + ┌──────────────────────┼──────────────────────┐ + │ │ │ + APPROVED NEEDS_REVISION REJECTED + │ │ │ + ▼ ▼ ▼ + ┌──────────────────┐ Loop back to Document why, + │ 5. PR opens in │ proposer archive proposal, + │ aiox-core with │ with revision close finding. + │ changes │ notes + └────────┬─────────┘ + │ + ▼ + ┌──────────────────┐ + │ 6. CI + review + │ + │ merge │ + └────────┬─────────┘ + │ + ▼ + ┌──────────────────┐ + │ 7. Consumer │ + │ projects pull │ + │ on next sync │ + └──────────────────┘ +``` + +--- + +## Worked example (retrofit of Wave 1.A) + +This is what the pipeline would look like for the Wave 1.A vocabulary contract failure. + +### AuditFinding `AF-20260507-vocabulary-contract-failure.yaml` + +```yaml +audit_finding: + version: "1.0" + id: "AF-20260507-vocabulary-contract-failure" + date: "2026-05-07T17:00:00Z" + auditor: "@aiox-master (Orion)" + source_session: "Wave 1.A correction session in business-ai-first; voice-clone consultation with Akita/Montano/Kira" + + context: + project: "business-ai-first" + epic: "EPIC-MVP-CDM-CADASTRO" + triggered_by: "DBOPS-V1 prod apply failed SQLSTATE 23514 against 17,354 legacy rows" + + finding: + summary: "YOLO terminal can write a migration with invented vocabulary because no pre-flight forces dictionary lookup." + evidence: + - "DBOPS-V1 used humanized PT-BR ('CNH - Primeira Habilitação') invented in YOLO session" + - "5 vocabularies coexist in tox_exams domain (legacy slug, tx_* prefix, humanized, English drift, target English)" + - "db-inventory/dictionary/ existed but was never consulted" + - "Static CI passed; runtime pgTAP never ran" + impact_observed: + blast_radius: "high" + affected_artifacts: ["DBOPS-V1 migration", "Wave 1.A gate G0", "EPIC-MVP-CDM-CADASTRO timeline"] + cost: "1 reverted migration, ~80 minutes audit + correction session, 1 ADR + 4 deliverables to address root cause" + + framework_candidate: true + framework_candidate_rationale: | + Any DB-touching project under AIOX faces this risk. The fix is not project-specific: + 1. Pre-flight hook on Edit/Write of supabase/migrations/*.sql + 2. Vocabulary contract pattern as framework convention + 3. aiox-master triage matrix to consult db-inventory before delegating + + references: + - kind: ADR + path: "business-ai-first/docs/decisions/ADR-DBOPS-V1-vocabulary-contract-failure.md" + - kind: hook + path: "business-ai-first/.claude/hooks/migration-dictionary-guard.cjs" + - kind: voice-clone-opinions + path: "business-ai-first/squads/voice-clones/agents/{fabio-akita,lucas-montano}.md" + + proposed_disposition: + - "Promote migration-dictionary-guard.cjs to aiox-core/hooks/ as framework hook" + - "Add Article VII (Vocabulary Contract) to .aiox-core/constitution.md" + - "Extend @aiox-master with triage.routing_matrix consulting db-inventory before migration tasks" + - "Document Vocabulary Contract pattern in aiox-core/governance/patterns/" +``` + +### FrameworkProposal `PROP-20260507-vocabulary-contract.yaml` + +```yaml +framework_proposal: + version: "1.0" + id: "PROP-20260507-vocabulary-contract" + date: "2026-05-07T18:30:00Z" + proposer: "@aiox-master (Orion)" + source_finding: "AF-20260507-vocabulary-contract-failure" + + target: + layer: "L1+L2" + artifact_type: "rule|hook|agent|governance" + artifact_path: | + Multiple: + - aiox-core/.claude/rules/vocabulary-contract.md (NEW) + - aiox-core/hooks/migration-dictionary-guard.cjs (NEW, copied + generalized) + - aiox-core/.aiox-core/development/agents/aiox-master.md (MODIFY: add triage.routing_matrix) + - aiox-core/governance/patterns/vocabulary-store.md (NEW pattern doc) + operation: "create|modify" + + generalization: + pattern_name: "Vocabulary Contract Store" + when_to_apply: | + Whenever a project has a domain enum or text[] column that: + 1. Has multiple writers (UI form + RPC + scraper + manual SQL) + 2. Has multiple consumer surfaces (DB CHECK + Zod + UI labels + LLM context) + 3. Has historical drift (legacy values that don't match current convention) + examples_from_other_domains: + - "Marketing: campaign_status (lead, qualified, converted, churned) needs same treatment" + - "Finance: payment_method, billing_responsible enums similar" + - "HR: employee_status, exit_reason if HR squad gets activated" + + migration_path: + breaking_change: false + affected_consumers: ["business-ai-first"] + rollout_plan: | + 1. PR adds files to aiox-core (no existing files broken) + 2. business-ai-first pulls aiox-core update on next sync + 3. business-ai-first migration-dictionary-guard.cjs (project-local) is replaced by aiox-core version (vendor or symlink) + 4. Documentation cross-references updated + + deprecation_plan: + deprecates: ["business-ai-first/.claude/hooks/migration-dictionary-guard.cjs (project-local copy)"] + sunset_window: "Immediate after framework version pulled" + + cost_benefit: + cost: "~3-4 hours engineering to generalize hook + write pattern doc + extend aiox-master" + benefit: "Prevents the same failure mode in any future AIOX project. Akita-quality fundamental." + risk: "low — additive changes; no existing behavior modified" + + approval: + eliel_decision: "PENDING" + eliel_decision_at: null + eliel_decision_rationale: "" + revision_request: [] + + implementation: + pr_url: "" + merged_at: "" + distributed_to: [] +``` + +This is the artifact Eliel reviews. On `APPROVED`, the PR opens in `aiox-core`. + +--- + +## Operational rules + +1. **No framework change without an approved proposal.** Even if @aiox-master spots an opportunity, it MUST go through the pipeline. Eliel is the gate. +2. **Project-bound findings stay project-bound.** Not every audit promotes. The `framework_candidate: false` path is normal and healthy. +3. **Voice-clone opinions are evidence, not authority.** Akita/Montano/Kira are inputs to the proposal but cannot bypass Eliel. +4. **Approval is per-proposal, not per-class.** Approving one vocabulary-contract proposal does not auto-approve future similar ones. +5. **Reverts use the pipeline.** If a framework change shipped and proves harmful, a new proposal `PROP--revert-` opens. Same gate. +6. **All proposals (approved + rejected + revised) archived forever.** They are the institutional memory of the framework's evolution. + +--- + +## Storage layout in aiox-core + +```text +aiox-core/ +├── audits/ +│ ├── README.md # explains this folder +│ ├── promoted/ # findings that became proposals +│ │ └── AF-20260507-vocabulary-contract-failure.yaml +│ └── archived/ # findings that stayed scope-bound (project-only) +│ └── (none yet) +├── governance/ +│ ├── evolution-pipeline.md # this document +│ ├── handoff-types.md # contract handoff vs micro-handoff (TBD) +│ ├── squad-activation-strategy.md # Entrega 4 (TBD) +│ ├── proposals/ +│ │ ├── README.md # explains this folder +│ │ ├── PROP-20260507-vocabulary-contract.yaml +│ │ └── archive/ # rejected or superseded proposals +│ ├── patterns/ +│ │ ├── README.md # catalog of approved patterns +│ │ └── vocabulary-store.md # (created on first APPROVED proposal) +│ └── templates/ +│ ├── audit-finding-tmpl.yaml # YAML template (extracted from this doc) +│ └── framework-proposal-tmpl.yaml +``` + +--- + +## Out of scope (this version) + +- Automated detection of framework-candidate findings (would need ML/heuristic; future work) +- Multi-orchestrator approval (currently Eliel is sole approver; future may add @architect or @qa as co-approvers for non-strategic changes) +- Cross-organization adoption (this is internal to Eliel's projects for now) +- Versioning aiox-core releases (already handled by `CHANGELOG.md` and `package.json` version) + +--- + +— Orion (`@aiox-master`), formalizando o pipeline R&D contínuo do framework AIOX por solicitação de Eliel diff --git a/governance/patterns/README.md b/governance/patterns/README.md new file mode 100644 index 0000000000..5331a34bc4 --- /dev/null +++ b/governance/patterns/README.md @@ -0,0 +1,28 @@ +# aiox-core/governance/patterns/ + +Catalog of approved framework patterns. Each pattern was promoted from an AuditFinding via FrameworkProposal and approved by Eliel. + +See [`../evolution-pipeline.md`](../evolution-pipeline.md) for the promotion flow. + +## Pattern catalog + +| Pattern | Source proposal | Status | Doc | +|---|---|---|---| +| Vocabulary Contract Store | `PROP-20260507-vocabulary-contract.yaml` | APPROVED | (implementation pattern doc pending) | +| Squad Activation Routing | `PROP-20260507-squad-routing-strategy.yaml` | APPROVED | [`../squad-activation-strategy.md`](../squad-activation-strategy.md) | + +## Anatomy of a pattern document + +Each pattern doc includes: + +1. **Problem** — what real-world failure mode this prevents +2. **Pattern** — the convention itself (rules, structure, code shape) +3. **When to apply** — triggers/heuristics for invocation +4. **When NOT to apply** — anti-patterns and exclusions +5. **Implementation** — code/config snippets, file structure +6. **Examples** — minimum 2 from real projects +7. **Source AuditFinding(s)** — institutional memory link + +## Authority + +Patterns become canonical only after Eliel approval. Catalog updates happen as part of the FrameworkProposal merge PR. diff --git a/governance/proposals/PROP-20260507-squad-routing-strategy.yaml b/governance/proposals/PROP-20260507-squad-routing-strategy.yaml new file mode 100644 index 0000000000..54f68101ce --- /dev/null +++ b/governance/proposals/PROP-20260507-squad-routing-strategy.yaml @@ -0,0 +1,76 @@ +framework_proposal: + version: "1.0" + id: "PROP-20260507-squad-routing-strategy" + date: "2026-05-07T19:00:00Z" + proposer: "@aiox-master (Orion)" + source_finding: "AF-20260507-aiox-master-routing-gap" + + target: + layer: "L1" + artifact_type: "agent | rule | hook | governance" + artifact_path: | + Multiple coordinated changes: + - aiox-core/.aiox-core/development/agents/aiox-master.md (MODIFY — add triage.routing_matrix) + - aiox-core/.antigravity/rules/agents/aiox-master.md (MIRROR) + - aiox-core/.claude/commands/AIOX/agents/aiox-master.md (MIRROR) + - aiox-core/.codex/agents/aiox-master.md (MIRROR) + - aiox-core/.cursor/rules/agents/aiox-master.md (MIRROR) + - aiox-core/.claude/rules/squad-activation.md (NEW — operational rule synthesizing strategy) + - aiox-core/hooks/squad-suggestion-advisor.cjs (NEW — UserPromptSubmit hook) + - aiox-core/governance/squad-activation-strategy.md (ALREADY CREATED in this session — formalize via PR) + - aiox-core/governance/patterns/squad-activation.md (NEW pattern doc, created on APPROVED) + operation: "modify + create" + + generalization: + pattern_name: "Squad Activation Routing" + when_to_apply: | + Any orchestrator agent that delegates work across multiple specialized + domains and currently does NOT have a triage matrix. Specifically: + - @aiox-master (root orchestrator) — primary target + - Future project-level orchestrators (if any project wraps @aiox-master) + examples_from_other_domains: + - "claude-mastery-chief already has squad-internal triage.routing_matrix — proves pattern works" + - "OpenAI Swarm pattern: handoff-based routing" + - "LangChain agent executor: tool-selection by description matching" + + migration_path: + breaking_change: false + affected_consumers: + - "All consumers of @aiox-master (every AIOX project)" + rollout_plan: | + 1. PR adds triage block to all 5 aiox-master.md mirror locations + 2. PR adds rule + hook + pattern doc + 3. business-ai-first pulls aiox-core update + 4. First-session validation: invoke @aiox-master with various keywords; confirm correct routing suggestions + 5. Iterate keyword list based on observed misses (additional findings → additional proposals) + + deprecation_plan: + deprecates: [] # nothing to deprecate; purely additive + sunset_window: "n/a" + + cost_benefit: + cost: | + Engineering: ~4-5h to write the routing matrix, hook, rule, and validation + Token: ~25K tokens for full documentation + code + Complexity: medium — requires careful keyword tuning to avoid noise + benefit: | + Estimated 30-50% token reduction per multi-domain session. + Voice-clones squad utilization rises from ~0% to expected 20-30% in relevant sessions. + claude-code-mastery squad becomes useful (currently dormant from outside). + Closes Eliel-stated gap: "todos os plans cogitaram em nenhum momento a perfeita integração desses squads". + Compounds: every new squad created becomes immediately discoverable via routing. + risk: | + medium — wrong keyword matches could route to irrelevant squads. + Mitigation: advisory mode (suggests, doesn't auto-spawn); user can skip; + iterative tuning after rollout. + + approval: + eliel_decision: "APPROVED" + eliel_decision_at: "2026-05-07T19:15:00Z" + eliel_decision_rationale: "Fecha gap declarado de integração de squads (voice-clones, claude-code-mastery, audience-engine, db-inventory). Advisory-only mitiga risco de false-positives. ROI alto: 30-50% token savings em sessões multi-domínio compostam ao longo do tempo. Ordem natural: implementar APÓS vocabulary-contract para que routing matrix referencie a Article VII recém-formalizada." + revision_request: [] + + implementation: + pr_url: "" + merged_at: "" + distributed_to: [] diff --git a/governance/proposals/PROP-20260507-vocabulary-contract.yaml b/governance/proposals/PROP-20260507-vocabulary-contract.yaml new file mode 100644 index 0000000000..38de967767 --- /dev/null +++ b/governance/proposals/PROP-20260507-vocabulary-contract.yaml @@ -0,0 +1,77 @@ +framework_proposal: + version: "1.0" + id: "PROP-20260507-vocabulary-contract" + date: "2026-05-07T18:45:00Z" + proposer: "@aiox-master (Orion)" + source_finding: "AF-20260507-vocabulary-contract-failure" + + target: + layer: "L1+L2" + artifact_type: "rule | hook | governance | constitution" + artifact_path: | + Multiple coordinated changes: + - aiox-core/.claude/rules/vocabulary-contract.md (NEW) + - aiox-core/hooks/migration-dictionary-guard.cjs (NEW — generalized from business-ai-first project copy) + - aiox-core/governance/patterns/vocabulary-store.md (NEW pattern doc, created on APPROVED) + - aiox-core/.aiox-core/constitution.md (MODIFY — add Article VII Vocabulary Contract) + operation: "create + modify" + + generalization: + pattern_name: "Vocabulary Contract Store" + when_to_apply: | + Whenever a project has a domain enum or text[] column that satisfies AT LEAST 2 of: + 1. Has multiple writers (UI form + RPC + scraper + manual SQL) + 2. Has multiple consumer surfaces (DB CHECK + Zod + UI labels + LLM context + analytics) + 3. Has historical drift (legacy values that don't match current convention) + 4. Is consumed by LLMs in any prompt (system or user-facing) + + The pattern: single canonical YAML source generating all consumer surfaces deterministically. + examples_from_other_domains: + - "Marketing: campaign_status (lead, qualified, converted, churned, expired) — same multi-writer, multi-surface profile" + - "Finance: payment_method enum, billing_responsible — analogous" + - "HR: employee_status, exit_reason — when HR squad activates" + - "Audience: 9 Públicos values (recurring, ex-customer, first-purchase, etc) — already has core/publicos/ structure but not formalized" + + migration_path: + breaking_change: false + affected_consumers: + - "business-ai-first (already using project-local hook; will switch to framework version)" + - "any future AIOX project (gets the pattern by default)" + rollout_plan: | + 1. PR to aiox-core adds: rule, hook, pattern doc, constitution amendment + 2. business-ai-first pulls aiox-core update + 3. business-ai-first/.claude/hooks/migration-dictionary-guard.cjs replaced by framework version + (or kept as project-specific override if customization needed) + 4. business-ai-first .claude/settings.json updated to reference framework hook + 5. ADR-DBOPS-V1-vocabulary-contract-failure.md cross-references the now-canonical framework pattern + + deprecation_plan: + deprecates: + - "business-ai-first/.claude/hooks/migration-dictionary-guard.cjs (project-local copy)" + sunset_window: "Immediate after framework version pulled (project hook becomes legacy / removed)" + + cost_benefit: + cost: | + Engineering: ~3-4h to generalize hook, write pattern doc, draft constitution amendment + Token: ~15K tokens for the docs + code + Complexity: low — additive changes only + benefit: | + Prevents the same failure mode in any future AIOX DB-touching project. + Closes Akita's "Article VII" gap (anti-vibecoding control). + Single source of truth for vocabulary = audit-friendly = LLM-friendly. + Estimated savings: 30-60min per future epic that touches a domain enum. + risk: | + low — additive changes; no existing behavior modified. + Adoption risk: projects might ignore the rule. Mitigation: hook is advisory but + visible in stderr + QA gates check PR descriptions for dictionary references. + + approval: + eliel_decision: "APPROVED" + eliel_decision_at: "2026-05-07T19:15:00Z" + eliel_decision_rationale: "Aditivo, baixo risco, fecha gap do Akita (Article VII anti-vibecoding). Previne re-ocorrência da falha Wave 1.A em epics futuros. Custo 3-4h compensado pelo savings recorrente em qualquer projeto AIOX que toque domain enums." + revision_request: [] + + implementation: + pr_url: "" + merged_at: "" + distributed_to: [] diff --git a/governance/proposals/README.md b/governance/proposals/README.md new file mode 100644 index 0000000000..c118c8e3ef --- /dev/null +++ b/governance/proposals/README.md @@ -0,0 +1,26 @@ +# aiox-core/governance/proposals/ + +FrameworkProposals — formal change requests to evolve the AIOX framework based on AuditFindings. + +See [`../evolution-pipeline.md`](../evolution-pipeline.md) for full pipeline. + +## Layout + +```text +proposals/ +├── README.md # this file +├── PROP--.yaml # active proposals (PENDING / APPROVED / NEEDS_REVISION) +└── archive/ # rejected or superseded proposals + └── PROP--.yaml +``` + +## Status of a proposal + +- **PENDING** — awaiting Eliel's review +- **APPROVED** — Eliel signed; implementer can open PR in aiox-core +- **REJECTED** — Eliel declined; proposal moves to `archive/` with rationale +- **NEEDS_REVISION** — Eliel requested changes; proposer addresses and resubmits + +## Authority + +Only Eliel sets `eliel_decision` field. Any agent can write a proposal but cannot self-approve. diff --git a/governance/squad-activation-strategy.md b/governance/squad-activation-strategy.md new file mode 100644 index 0000000000..9410de56dd --- /dev/null +++ b/governance/squad-activation-strategy.md @@ -0,0 +1,306 @@ +# Squad Activation Strategy — Conditional Consult-First Routing + +**Status:** Draft v1.0 +**Date:** 2026-05-07 +**Author:** @aiox-master (Orion) +**Approval gate:** Eliel M. Alencar +**Source finding:** [`AF-20260507-aiox-master-routing-gap`](../audits/promoted/AF-20260507-aiox-master-routing-gap.yaml) + +--- + +## Problem statement + +`@aiox-master` (the framework's primary orchestrator) currently has **no routing logic to consult specialized squads first** before delegating to itself or to YOLO terminals. Concrete consequences observed during EPIC-MVP-CDM-CADASTRO Wave 1.A: + +1. Voice-clone squad (Akita, Montano, Kira) **never auto-consulted** even when their domains were directly relevant. Eliel had to explicitly invoke them. +2. `claude-code-mastery` squad (which exists in `aiox-core/squads/`) **never invoked** despite Claude Code questions arising naturally. +3. `audience-engine` squad **never invoked** even when EPIC-MVP-CDM-CADASTRO required understanding of the 9 Públicos doctrine. +4. `db-inventory` cross-project asset **never consulted** before migration writes (root cause of DBOPS-V1 failure). +5. Sessions consume tokens re-discovering knowledge that already exists in dedicated squads/assets. + +Kira's parecer formal stated this directly: *"vocês perderam tokens descobrindo o que já existia em db-inventory. Isso é problema de retrieval — a info estava lá mas o orquestrador não consultou no momento certo."* + +Eliel's diagnostic: *"todos os plans criados cogitaram em nenhum momento a perfeita integração desses squads, por isso criamos o business-ai-first baseado no aiox e departamentos da minha empresa."* + +--- + +## Design principles (Eliel-stated, Akita-aligned) + +1. **Conditional, not unconditional.** Consult-squad-first is for **thematic** tasks. Routine ops (`*status`, `git status`, file moves) must NOT inflate context with squad personas. +2. **Token discipline.** Squad consultation is opt-in per task category. Bad routing burns tokens; good routing saves them. +3. **Heuristic-driven.** Use keyword/intent matching to suggest a squad. The orchestrator suggests; Eliel can override. +4. **Two-way street.** When a project agent learns something a squad should know, that flows back via the Evolution Pipeline (see `evolution-pipeline.md`). +5. **Backward compatible.** Existing `@aiox-master` invocations keep working. The squad routing is additive. + +--- + +## Squad inventory (current) + +### Framework-bound squads (in `aiox-core/squads/`) + +| Squad | Domain | Entry agent | Use when | +|---|---|---|---| +| `claude-code-mastery` | Claude Code platform: hooks, skills, subagents, MCP, plugins, agent teams | `claude-mastery-chief` | User asks about Claude Code itself, hooks, MCP setup, skill creation, sub-agents, swarm orchestration | + +### Project-bound squads (in `/squads/`) + +| Squad | Project | Domain | Entry agent | Use when | +|---|---|---|---|---| +| `voice-clones` | business-ai-first | 8 personas curadas (Akita, Montano, Kira-aligned, Hormozi, Conrado, Schoger, Alan, Gilberto, Chase) | varies | User wants formal opinion in style of a curated persona; technical critique; second opinion | +| `audience-engine` | business-ai-first | 9 Públicos doctrine (Conrado Adolpho), RFV, segmentation | (entry agent TBD) | Audience strategy, segmentation, KPI design, dashboard tabs | +| `marketing` | business-ai-first | content, ads, growth | varies | Marketing tasks | +| `vendas` | business-ai-first | SDR, closer, sales analytics | varies | Sales pipeline tasks | +| `cs` | business-ai-first | onboarding, retention, support | varies | Customer success tasks | +| `produto` | business-ai-first | product mgmt, content creation | varies | Product tasks | +| `admin` | business-ai-first | finance, HR, legal, compliance | varies | Admin tasks | +| `ops` | business-ai-first | process mapping, automation, architecture | varies | Operational architecture tasks | + +### Cross-project assets (treated as "data squads") + +| Asset | Domain | Use when | +|---|---|---| +| `db-inventory` | DB schema dictionary, snapshots, audit reports | ANY task that writes/reads a DB table, view, function, or RLS policy | + +--- + +## Routing matrix for `@aiox-master` + +The matrix below extends `@aiox-master`'s YAML definition. It mirrors the pattern found in `claude-mastery-chief` (`triage.routing_matrix`) and adapts it for cross-squad orchestration. + +### Conditional triggers (consult squad if at least one keyword matches) + +| Squad | Trigger keywords (any match) | Consultation type | +|---|---|---| +| `claude-code-mastery` (entry: `claude-mastery-chief`) | hook, skill, MCP, slash command, sub-agent, plugin, subagent, swarm, claude code, settings.json, permissions, sandbox, IDE integration | suggest invocation; do NOT auto-spawn | +| `voice-clones` | parecer, opinião formal, akita, montano, kira, hormozi, conrado, schoger, second opinion, critique style of, voice of, persona | suggest specific clone(s) by name | +| `db-inventory` (asset) | migration, schema change, RLS, RPC, trigger, view, enum, table, column, CHECK constraint, FK | **MUST READ** dictionary before tool use; not optional | +| `audience-engine` | público, segmento, RFV, 9 públicos, conrado, classificação de cliente, retention cohort | suggest invocation | +| `marketing` | campanha, ad, copy, growth, content strategy | suggest invocation | +| `vendas` | pipeline de vendas, SDR, closer, qualified lead, oportunidade | suggest invocation | +| `cs` | onboarding, retention, churn, support ticket | suggest invocation | +| `admin` | financeiro, RH, legal, compliance, LGPD operacional | suggest invocation | + +### Direct-answer domains (no squad consultation) + +`@aiox-master` answers directly without invoking squads when the request is: + +- Workflow status (`*status`, `*plan`, `*list-components`) +- Routine git operations (`git status`, `git diff`) +- File reads/writes outside `supabase/migrations/` +- Trivial questions (1-2 sentences) +- Meta-framework operations explicitly within @aiox-master scope (`*create agent`, `*modify task`) + +### Decision tree (pseudocode) + +```text +on user message: + classify intent → category + match keywords → squad_candidates[] + + if user explicitly typed @: + transform to that agent (existing behavior) + HALT + + if category in DIRECT_ANSWER_DOMAINS: + answer directly without squad consultation + HALT + + if "db-inventory" in squad_candidates: + enforce: read corresponding dictionary entry BEFORE first tool call + do NOT block; emit advisory; continue + + if len(squad_candidates) >= 1: + show user: "Suggested squads to consult: ..." + let user pick or skip (numbered options) + + proceed with task; if user picked squad, transform to squad entry agent +``` + +--- + +## Patch for `@aiox-master.md` (proposed extension) + +The following YAML block should be added to `aiox-core/.aiox-core/development/agents/aiox-master.md` after the `core_principles` section. (Mirrored to all `aiox-master.md` instances in `.antigravity/`, `.claude/commands/`, `.codex/`, `.cursor/`.) + +```yaml +# ═══════════════════════════════════════════════════════════════════════════════ +# SQUAD ACTIVATION & TRIAGE (added 2026-05-07 per ADR-PHASE2-squad-routing) +# ═══════════════════════════════════════════════════════════════════════════════ + +triage: + enabled: true + philosophy: | + Consult specialized squads BEFORE delegating to YOLO or executing solo, + when the topic matches their domain. This prevents context loss and + duplicated effort. Heuristic — not blocking. + + routing_matrix: + db_operations: + keywords: [migration, schema, RLS, RPC, trigger, view, enum, table, column, CHECK, FK, supabase/migrations] + consult: db-inventory + consult_type: MUST_READ_DICTIONARY + action: | + Before first Edit/Write to supabase/migrations/*.sql, locate and read the + corresponding db-inventory/dictionary/{tables,views,enums}/.md entry. + If no entry exists, create one BEFORE writing the migration. + + claude_code_platform: + keywords: [hook, skill, MCP, slash command, sub-agent, subagent, swarm, claude code, settings.json, permissions, sandbox, IDE integration, plugin] + consult: claude-code-mastery + consult_type: SUGGEST_INVOCATION + action: "Suggest @claude-mastery-chief and offer to transform" + + formal_opinion: + keywords: [parecer, opinião formal, second opinion, critique, akita, montano, kira, hormozi, conrado, schoger] + consult: voice-clones + consult_type: SUGGEST_SPECIFIC_CLONE + action: "Match keyword to specific clone (e.g., akita → @fabio-akita); offer to consult" + + audience_strategy: + keywords: [público, segmento, RFV, 9 públicos, conrado, classificação cliente, retention cohort] + consult: audience-engine + consult_type: SUGGEST_INVOCATION + + marketing: + keywords: [campanha, ad campaign, copy, growth strategy, content strategy, GTM] + consult: marketing + consult_type: SUGGEST_INVOCATION + + sales: + keywords: [pipeline de vendas, SDR, closer, qualified lead, oportunidade comercial] + consult: vendas + consult_type: SUGGEST_INVOCATION + + customer_success: + keywords: [onboarding cliente, retention plan, churn analysis, support ticket] + consult: cs + consult_type: SUGGEST_INVOCATION + + admin_compliance: + keywords: [financeiro operacional, RH, legal, compliance LGPD, jurídico] + consult: admin + consult_type: SUGGEST_INVOCATION + + direct_answer_domains: + - "Workflow status: *status, *plan, *list-components" + - "Routine git: git status, git diff, git log" + - "File reads outside supabase/migrations" + - "Meta-framework ops within @aiox-master scope" + - "Trivial questions (1-2 sentences)" + + override: + user_explicit_agent_call: | + If user types @ explicitly, transform to that agent immediately. + Squad routing does NOT intercept explicit user calls. + user_skip: | + User can decline a squad suggestion via "skip" or by proceeding with + another command. Suggestion is recorded but not blocking. + + cost_discipline: + rule: | + NEVER load a squad's full agent persona just to "have the option." + Squad consultation is JIT (just-in-time) — load only when transformation + is confirmed. + measure: | + Each squad-routing event MUST be self-aware of token cost. + A 5K-token squad load is justifiable for a 50K-token task; not for a + 500-token clarification. +``` + +--- + +## Cross-pollination: project agent → squad master + +When a project-local agent (e.g., `@aiox-master` in `business-ai-first`) discovers a Claude Code-related improvement (hook pattern, skill convention, settings.json structure), it should propose enhancement to `claude-code-mastery` squad in `aiox-core`. + +### Flow + +```text +[business-ai-first agent learns X about Claude Code] + ↓ + Writes AuditFinding (framework_candidate: true) + ↓ + References claude-code-mastery as target squad + ↓ + Proposer drafts FrameworkProposal + ↓ + Eliel approves + ↓ + PR in aiox-core/squads/claude-code-mastery/ + (e.g., adding new tactic to hooks-architect agent) + ↓ + business-ai-first pulls aiox-core update + ↓ + Knowledge propagated to all consumer projects +``` + +This closes the loop Eliel pointed out: *"o agente deve se juntar ao time do aiox-core para contribuir."* + +In effect: **project agents are research scouts; squad masters are knowledge curators.** + +--- + +## Hook proposal: `squad-suggestion-advisor` + +Companion to `migration-dictionary-guard.cjs` (already shipping). Lives at `aiox-core/hooks/squad-suggestion-advisor.cjs`. + +```javascript +// PreToolUse hook +// Trigger: any user message that contains squad-routing keywords +// Action: emit stderr advisory listing relevant squads +// Mode: advisory (does not block) +// Cost: ~1ms per check; runs only on UserPromptSubmit (not every tool call) +``` + +(Skeleton in the actual implementation PR; spec only here.) + +--- + +## Migration plan (rollout to consumer projects) + +| Step | Owner | When | +|---|---|---| +| 1. PR in aiox-core with: rule + agent patch + hook + this strategy doc | @aiox-master | After Eliel approves | +| 2. business-ai-first pulls aiox-core | Eliel (manual git pull or npm update) | Next session of business-ai-first | +| 3. Verify @aiox-master in business-ai-first now exhibits squad-suggesting behavior | Eliel + @aiox-master | First task of next session | +| 4. Iterate keyword list based on observed misses | @aiox-master (audit findings → proposals) | Continuous | + +--- + +## Anti-patterns (do not do) + +| Anti-pattern | Why it's wrong | +|---|---| +| Auto-spawn squad on every keyword | Token waste; user loses agency | +| Block tool execution if squad not consulted | Creates friction in routine work | +| Hardcode squad list in `@aiox-master` (no extensibility) | Squads come and go; matrix must be data-driven | +| Recommend a squad that doesn't exist in current project | Embarrassing; matrix must filter by available squads | +| Squad routing applied to agent-switch handoffs (`@dev` → `@qa`) | That's a different concern — `agent-handoff.md` rule covers it | + +--- + +## Definition of done (for this strategy) + +- [ ] FrameworkProposal `PROP-20260507-squad-routing-strategy.yaml` written and approved by Eliel +- [ ] PR in aiox-core merging: + - [ ] `aiox-core/.claude/rules/squad-activation.md` (synthesizes this doc as rule) + - [ ] `aiox-core/hooks/squad-suggestion-advisor.cjs` (advisory implementation) + - [ ] Patch to all `aiox-master.md` instances adding `triage` block + - [ ] This strategy doc at `aiox-core/governance/squad-activation-strategy.md` +- [ ] business-ai-first pulls aiox-core update +- [ ] First-session validation: @aiox-master suggests `db-inventory` consult before next migration +- [ ] First-session validation: @aiox-master suggests voice-clone when "parecer" keyword appears +- [ ] First-session validation: routine ops do NOT trigger squad suggestions (token discipline check) + +--- + +## Linked artifacts + +- [`evolution-pipeline.md`](evolution-pipeline.md) — defines how this strategy itself was promoted to framework +- [`../audits/c-dev-organization-2026-05-07.md`](../audits/c-dev-organization-2026-05-07.md) — workspace audit informing this work +- `business-ai-first/docs/decisions/ADR-DBOPS-V1-vocabulary-contract-failure.md` — original triggering ADR +- `business-ai-first/.aiox/handoffs/handoff-2026-05-07-phase1-to-phase2-data-contract.yaml` — Phase 2 contract referencing this strategy + +--- + +— Orion (`@aiox-master`), respondendo ao gap arquitetural sinalizado por Eliel: o orquestrador principal precisa consultar o squad certo antes de delegar diff --git a/governance/templates/audit-finding-tmpl.yaml b/governance/templates/audit-finding-tmpl.yaml new file mode 100644 index 0000000000..d9246946d3 --- /dev/null +++ b/governance/templates/audit-finding-tmpl.yaml @@ -0,0 +1,46 @@ +# AIOX AuditFinding Template +# See: aiox-core/governance/evolution-pipeline.md +# +# Usage: +# 1. Copy this file to /docs/audits/AF--.yaml +# 2. Fill all fields. Mark framework_candidate honestly. +# 3. If framework_candidate: true → after triage, copy to aiox-core/audits/promoted/ +# 4. If framework_candidate: false → leave in project; archive when scope-bound work completes + +audit_finding: + version: "1.0" + id: "" # AF-- e.g., AF-20260507-vocabulary-contract-failure + date: "" # ISO 8601, e.g., 2026-05-07T18:30:00Z + auditor: "" # agent id or "eliel" + source_session: "" # one-line summary of the session that discovered + + context: + project: "" # e.g., business-ai-first + epic: "" # e.g., EPIC-MVP-CDM-CADASTRO + triggered_by: "" # event that exposed the finding + + finding: + summary: "" # one-sentence finding + evidence: + - "" # concrete evidence 1 + # - "" # concrete evidence 2 + impact_observed: + blast_radius: "" # low | medium | high | critical + affected_artifacts: [] # [""] + cost: "" # tokens, time, prod incidents, etc. + + framework_candidate: false # true if this finding could affect any future AIOX project + framework_candidate_rationale: | + Explain why this is or isn't a framework concern. Be honest — not every + finding belongs in the framework. False is healthy when scope-bound. + + references: + # Allowed kind values: ADR | code | hook | governance-doc | existing-pattern-source | + # voice-clone-finding | voice-clone-personas | handoff-contract | audit | proposal + - kind: ADR + path: "" # e.g., docs/decisions/ADR-...md + # - kind: code + # path: "" + + proposed_disposition: + - "" # short disposition, e.g., "add hook", "extend agent triage", "create rule" diff --git a/governance/templates/framework-proposal-tmpl.yaml b/governance/templates/framework-proposal-tmpl.yaml new file mode 100644 index 0000000000..51a54c21c9 --- /dev/null +++ b/governance/templates/framework-proposal-tmpl.yaml @@ -0,0 +1,56 @@ +# AIOX FrameworkProposal Template +# See: aiox-core/governance/evolution-pipeline.md +# +# Usage: +# 1. Copy this file to aiox-core/governance/proposals/PROP--.yaml +# 2. Fill all fields. Reference source AuditFinding by ID. +# 3. Submit to Eliel for approval. +# 4. On APPROVED: implementer opens PR in aiox-core; fill implementation.* fields. +# 5. On REJECTED: move to proposals/archive/. +# 6. On NEEDS_REVISION: address revision_request, resubmit. + +framework_proposal: + version: "1.0" + id: "" # PROP-- + date: "" # ISO 8601 + proposer: "" # agent id + source_finding: "" # AF-- + + target: + layer: "" # L1 (Core) | L2 (Templates) | L3 (Project Config) + artifact_type: "" # agent | rule | hook | task | template | governance | workflow + artifact_path: "" # intended path in aiox-core + operation: "" # create | modify | deprecate + + generalization: + pattern_name: "" # e.g., "Vocabulary Contract Store" + when_to_apply: | + + examples_from_other_domains: + - "" # demonstrate generalizability beyond source project + + migration_path: + breaking_change: false + affected_consumers: [] # [""] + rollout_plan: | + + + deprecation_plan: + deprecates: [] # artifacts being replaced + sunset_window: "" # e.g., "2 weeks after merge" + + cost_benefit: + cost: "" # engineering effort, token cost, complexity added + benefit: "" # problems prevented, tokens saved, audit improved + risk: "" # low | medium | high — what could go wrong + + approval: + eliel_decision: "PENDING" # PENDING | APPROVED | REJECTED | NEEDS_REVISION + eliel_decision_at: null # ISO 8601 timestamp when decided + eliel_decision_rationale: "" # reasoning, especially if reject or needs-revision + revision_request: [] # filled if NEEDS_REVISION + + implementation: + pr_url: "" # filled when PR opens against aiox-core + merged_at: "" # ISO 8601 when shipped + distributed_to: [] # projects that pulled the change after release