From 4f88041e6e855d19203b0b670ba2b4570739540b Mon Sep 17 00:00:00 2001 From: leandrospycer-gif <223170502+leandrospycer-gif@users.noreply.github.com> Date: Wed, 19 Aug 2026 01:09:01 -0300 Subject: [PATCH 1/2] docs(claude): correct import alias and document this checkout's real state - Fix Imports example: real alias here is aiox-core/* (tsconfig/jest), not @/* (that belongs to apps/dashboard/, which doesn't exist in this checkout) - Add single-test-run command plus jest quarantine/coverage caveats - Add contributor notes: frameworkProtection is currently false here, .aiox-core/core/ module map, bin/ entry points, actual packages/apps/squads/pro state, real docs/stories/ layout, and additional untracked .claude/rules files Co-Authored-By: Claude Sonnet 5 --- .claude/CLAUDE.md | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index d57e89bfaa..b459270185 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -106,6 +106,38 @@ O AIOX usa um modelo de 4 camadas (L1-L4) para separar artefatos do framework e --- + +## Notas do Contribuidor (estado real deste checkout) + +**Boundary L1-L4 está OFF neste repo agora.** `.aiox-core/core-config.yaml` → `boundary.frameworkProtection: false` (comentário no arquivo: "TEMPORARY: TOK-3 contributor mode"). Ou seja, as deny rules do L1/L2 acima (nunca editar `.aiox-core/core/`, `bin/aiox.js`) **não estão ativas neste checkout** — faz sentido, já que este É o repo fonte do framework, não um projeto que o instalou. `protected`/`exceptions` (fonte de verdade do boundary) vivem no mesmo `core-config.yaml`; mudar o valor sozinho não adiciona/remove deny rules em `.claude/settings.json` — isso exige reexecutar o installer. + +**Mapa de `.aiox-core/core/`** (26 subpastas — o "motor" do framework): +- `orchestration/` — invoca agentes, coordena builds (`bob-orchestrator`, `brownfield-handler`) +- `execution/` — motor de execução (`autonomous-build-loop`, `parallel-executor`), chamado por `orchestration/` +- `synapse/` — engine de contexto de sessão (context/diagnostics/domain/memory layers) +- `memory/` — persistência de `MEMORY.md` por agente (`gotchas-memory.js`) +- `resilience/` — Agent Immortality Protocol (recuperação após falha fatal de agente) +- `health-check/` + `doctor/` — checks + healers de autodiagnóstico/reparo (cobertos por `test:health-check`, não pelo jest) +- `quality-gates/` — layer1-precommit, layer2-pr-automation, human-review-orchestrator +- `registry/` — Service Registry (catálogo de workers/tasks/templates/scripts) +- `ids/` — Entity Registry do Incremental Development System +- `mcp/` — config/symlink de servidores MCP +- `code-intel/`, `permissions/`, `manifest/`, `errors/` — client de code intel; operation-guard/permission-mode; gerador/validador do install manifest; aiox-error/error-registry +- `elicitation/` + `session/` — prompting interativo + detecção de contexto (ver `.aiox-core/core/README.md` para detalhe completo) +- `graph-dashboard/` e `external-executors/` — CLIs por trás de `bin/aiox-graph.js` e `bin/aiox-delegate.js` + +**CLI entry points (`bin/`):** `aiox.js` é o roteador principal (lê versão do `package.json`, despacha para `packages/installer/src/wizard/index.js`). `aiox-init.js` e `aiox-minimal.js` estão **deprecated** (fallback legado, remoção prevista v5.0.0) — não construir sobre eles. + +**Monorepo `packages/*` (npm workspaces):** `aiox-install` (instalador NPX), `aiox-pro-cli` (CLI do AIOX Pro), `installer` (wizard greenfield/brownfield), `gemini-aiox-extension` (sem package.json — arquivos de extensão crus). `apps/dashboard/`, citado no README, **não existe neste checkout**. `squads/` só tem `_example` e `claude-code-mastery` localmente (catálogo completo é distribuído via package publicado). `pro/` é git submodule (`SynkraAI/aiox-pro.git`) **não inicializado** aqui. + +**`docs/stories/` na prática:** não há split `active/`/`completed/` como o README sugere — é um diretório por epic (`epic--/`), cada um com `EPIC--.md` + `STORY-.-.md`. Stories não iniciadas ficam em `docs/stories/backlog` (`core-config.yaml` → `storyBacklog.location`). + +**`.claude/rules/*.md` além de `agent-authority.md`, `mcp-usage.md`, `tool-examples.md`, `agent-handoff.md`:** `agent-memory-imports.md`, `coderabbit-integration.md`, `handoff-consolidation.md`, `ids-principles.md`, `story-lifecycle.md`, `tool-response-filtering.md`, `workflow-execution.md` — maioria usa frontmatter `paths:` e só carrega ao tocar nos arquivos correspondentes. + +**`.cursor/rules/agents/*.mdc` são artefatos gerados** por `npm run sync:ide:cursor` a partir de `.aiox-core/development/agents/` — não editar à mão. + +--- + ## Sistema de Agentes @@ -174,13 +206,13 @@ Use prefixo `*` para comandos: | Interfaces | PascalCase + sufixo | `WorkflowListProps` | ### Imports -**Sempre use imports absolutos.** Nunca use imports relativos. +**Sempre use imports absolutos, nunca relativos.** Neste repo o alias real é `aiox-core/*` (ou `@aiox-core/*`), definido em `tsconfig.json` (`paths`) e espelhado em `jest.config.js` (`moduleNameMapper`) — **não** `@/*` (esse é o alias de `apps/dashboard/`, que não existe neste checkout). Não há regra ESLint (`no-restricted-imports` ou similar) que force isso — é convenção, não gate automático. ```typescript // ✓ Correto -import { useStore } from '@/stores/feature/store' +import { AgentInvoker } from 'aiox-core/orchestration/agent-invoker' // ✗ Errado -import { useStore } from '../../../stores/feature/store' +import { AgentInvoker } from '../../../.aiox-core/core/orchestration/agent-invoker' ``` **Ordem de imports:** @@ -221,6 +253,12 @@ npm run lint # ESLint npm run typecheck # TypeScript ``` +### Rodando um teste único +```bash +npx jest caminho/para/arquivo.test.js -t "nome do teste" +``` +`jest.config.js` é single-project. `testPathIgnorePatterns` exclui deliberadamente testes legados em quarentena (`tests/tools/*`, `tests/installer/*` — débito técnico OSR-10/migração v2.1); thresholds de cobertura estão temporariamente baixos (`global: 22%`, `.aiox-core/core/: 38%`, marcados "TEMPORARY" no config). `npm run test:health-check` roda **mocha** (não jest) sobre `tests/health-check/**` — cobre o engine/healers/reporters de `.aiox-core/core/health-check/`, mantido separado porque o próprio `jest.config.js` exclui `.aiox-core/core/health-check/checks/**` da cobertura como "candidatos a teste de integração". + ### Quality Gates (Pre-Push) Antes de push, todos os checks devem passar: ```bash From 7e6f3aed1c940829173a49ca1dc92055758d8d38 Mon Sep 17 00:00:00 2001 From: leandrospycer-gif <223170502+leandrospycer-gif@users.noreply.github.com> Date: Wed, 19 Aug 2026 01:20:52 -0300 Subject: [PATCH 2/2] docs(claude): fix coverage thresholds, ignore-pattern scope, and core/ subfolder count Addresses CodeRabbit review on PR #834: - Coverage thresholds were wrong: global is 19% branches / 22% functions, lines, statements (not a flat 22%) - testPathIgnorePatterns excludes specific quarantined files, not entire tests/tools/* and tests/installer/* directories - .aiox-core/core/ has 27 immediate subfolders, not 26 - Tightened the import-alias wording to avoid ambiguity (content was already correct: aiox-core/* is the only valid alias here) Co-Authored-By: Claude Sonnet 5 --- .claude/CLAUDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index b459270185..469c29502d 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -111,7 +111,7 @@ O AIOX usa um modelo de 4 camadas (L1-L4) para separar artefatos do framework e **Boundary L1-L4 está OFF neste repo agora.** `.aiox-core/core-config.yaml` → `boundary.frameworkProtection: false` (comentário no arquivo: "TEMPORARY: TOK-3 contributor mode"). Ou seja, as deny rules do L1/L2 acima (nunca editar `.aiox-core/core/`, `bin/aiox.js`) **não estão ativas neste checkout** — faz sentido, já que este É o repo fonte do framework, não um projeto que o instalou. `protected`/`exceptions` (fonte de verdade do boundary) vivem no mesmo `core-config.yaml`; mudar o valor sozinho não adiciona/remove deny rules em `.claude/settings.json` — isso exige reexecutar o installer. -**Mapa de `.aiox-core/core/`** (26 subpastas — o "motor" do framework): +**Mapa de `.aiox-core/core/`** (27 subpastas — o "motor" do framework): - `orchestration/` — invoca agentes, coordena builds (`bob-orchestrator`, `brownfield-handler`) - `execution/` — motor de execução (`autonomous-build-loop`, `parallel-executor`), chamado por `orchestration/` - `synapse/` — engine de contexto de sessão (context/diagnostics/domain/memory layers) @@ -206,7 +206,7 @@ Use prefixo `*` para comandos: | Interfaces | PascalCase + sufixo | `WorkflowListProps` | ### Imports -**Sempre use imports absolutos, nunca relativos.** Neste repo o alias real é `aiox-core/*` (ou `@aiox-core/*`), definido em `tsconfig.json` (`paths`) e espelhado em `jest.config.js` (`moduleNameMapper`) — **não** `@/*` (esse é o alias de `apps/dashboard/`, que não existe neste checkout). Não há regra ESLint (`no-restricted-imports` ou similar) que force isso — é convenção, não gate automático. +**Sempre use imports absolutos, nunca relativos.** O único alias válido neste repo é `aiox-core/*` (também espelhado como `@aiox-core/*` em `jest.config.js` `moduleNameMapper`, embora só `aiox-core`/`aiox-core/*` estejam declarados em `tsconfig.json` `paths`). O alias `@/*` citado em templates genéricos de React **não existe neste checkout** — pertence a `apps/dashboard/`, que não está presente aqui. Não há regra ESLint (`no-restricted-imports` ou similar) que force o uso de imports absolutos — é convenção, não gate automático. ```typescript // ✓ Correto import { AgentInvoker } from 'aiox-core/orchestration/agent-invoker' @@ -257,7 +257,7 @@ npm run typecheck # TypeScript ```bash npx jest caminho/para/arquivo.test.js -t "nome do teste" ``` -`jest.config.js` é single-project. `testPathIgnorePatterns` exclui deliberadamente testes legados em quarentena (`tests/tools/*`, `tests/installer/*` — débito técnico OSR-10/migração v2.1); thresholds de cobertura estão temporariamente baixos (`global: 22%`, `.aiox-core/core/: 38%`, marcados "TEMPORARY" no config). `npm run test:health-check` roda **mocha** (não jest) sobre `tests/health-check/**` — cobre o engine/healers/reporters de `.aiox-core/core/health-check/`, mantido separado porque o próprio `jest.config.js` exclui `.aiox-core/core/health-check/checks/**` da cobertura como "candidatos a teste de integração". +`jest.config.js` é single-project. `testPathIgnorePatterns` exclui deliberadamente arquivos específicos de testes legados em quarentena (não os diretórios inteiros) — ex.: `tests/tools/backward-compatibility.test.js`, `tests/tools/clickup-helpers.test.js` (débito técnico OSR-10/migração v2.1 → v4.31.0), além de `pro/` (roda via CI `pro-integration.yml`, não localmente) e testes Windows-only. Thresholds de cobertura: `global` = 19% branches / 22% functions, lines, statements; `.aiox-core/core/` = 38% lines — comentários no config marcam esses valores como "TEMPORARY". `npm run test:health-check` roda **mocha** (não jest) sobre `tests/health-check/**` — cobre o engine/healers/reporters de `.aiox-core/core/health-check/`, mantido separado porque o próprio `jest.config.js` exclui `.aiox-core/core/health-check/checks/**` da cobertura como candidato a teste de integração. ### Quality Gates (Pre-Push) Antes de push, todos os checks devem passar: