AIOX · Harness Deep Dive · Parte 2/4
• AIOX LAYER v1.3.0 7 ARTIGOS 11 AMENDMENTS 25+ HOOKS 38 RULES 16 SQUADS

O AIOX nao modifica o harness.
Ele instala governanca em cima dele.

Parte 2 de 4. Mapeia como o framework Synkra AIOX usa os mecanismos nativos do harness Claude Code — CLAUDE.md, rules/, agents/, hooks/, skills/, commands/ — para produzir um sistema multi-agente com constituicao, quality gates e lifecycle rules. Evidencia file:line ao lado de cada afirmacao.

Italo Gustavo / 2026-04-16 / Inferencias marcadas
Nesta parte
  1. 01AIOX = sistema operacional editorial sobre o kernel Claude Code
  2. 02Constitution -- 7 artigos, 3 severidades, gates reais
  3. 03Framework Boundary L1--L4: paths, mutabilidade, enforcement
  4. 04Agents registry -- 20+ personas sobre o mecanismo Agent
  5. 05Hooks AIOX -- 25+ guardas computacionais
  6. 06Rules -- 38 arquivos de governanca (3 always-on + 35 on-demand)
  7. 07Skills AIOX -- auto-discovery por frontmatter
  8. 08Commands -- wrappers /Domain:nome por dominio
  9. 09Squads -- unidade organizacional agents+tasks+templates
  10. 10Gates BLOCK / WARN / INFO -- exit code 2 vs 0
  11. 11Amendments -- o due process do framework
  12. 12Memory AIOX vs memory nativo do harness
  13. 13Fechamento -- produtizacao + governance, nada magico
§01 Abertura

AIOX = sistema operacional editorial sobre o kernel Claude Code

O AIOX (framework Synkra) nao e um fork do Claude Code. Nao reimplementa o loop de ferramentas, nao substitui o streaming, nao toca no sistema de compactacao. Ele faz algo mais humilde, e por isso mais interessante: escreve arquivos nos lugares onde o harness ja le por conta propria. CLAUDE.md, .claude/rules/*.md, .claude/agents/*.md, .claude/hooks/*.cjs, .claude/skills/*/SKILL.md, .claude/commands/**/*.md — tudo isso sao pontos de extensao publicos do harness, documentados pela Anthropic. O AIOX preenche cada um com uma camada constitucional, de personas e de quality gates.

A analogia mais direta: se o harness e o kernel que expoe syscalls (tool calls, stream events, compaction hooks), o AIOX e o userland — init, policies, PAM, cgroups e editorial style guide, tudo empacotado num “sistema operacional editorial”. Ha uma constituicao (Art. I--VIII), um due process de amendments, uma matriz de autoridade por agente, hooks que funcionam como seccomp filters (exit 2 = syscall deny), e rules que funcionam como environment variables carregadas sob demanda por path-matching.

Nada aqui e magico. Cada peca e um arquivo que ja esta num path que o harness respeita. A inteligencia e a composicao: quais arquivos, em quais paths, com quais severidades, enforced por quais hooks. Essa parte descasca cada camada.

NOTE -- escopo desta parte

Parte 1 cobre o harness cru (como o Claude Code decide o que ler, como invoca tool calls, como compacta contexto). Parte 3 traz estudos de caso. Parte 4 faz a critica: onde AIOX paga custo, onde repete o harness sem precisar, onde a abstracao vaza. Esta parte (2) so descreve o que o AIOX E, com evidencia no repositorio.

§02 Constitution

Sete artigos, tres severidades, gates de verdade

A Constituicao do AIOX vive em .aiox-core/constitution.md v1.3.0. Sao sete principios numerados em romanos (I, II, III, IV, V, VII, VIII — Art. VI foi removido no passado, explicando o gap), cada um com uma severidade formal e um gate nominal que o enforca. A mesma tabela aparece como contrato no .claude/CLAUDE.md do projeto, o que fecha o loop: o harness ingere CLAUDE.md como memoria permanente; o CLAUDE.md aponta pra constituicao; a constituicao aponta pros gates.

Art.PrincipioSeveridadeGate real?Onde
I CLI First NON-NEGOTIABLE Sim dev-develop-story.md
II Agent Authority NON-NEGOTIABLE Sim agent definitions + l1-boundary-guard.cjs
III Story-Driven Dev MUST Sim dev-develop-story.md + story-completeness-guard.cjs
IV No Invention MUST Sim spec-write-spec.md
V Quality First MUST Sim pre-push.md + pre-commit-verification-gate.cjs
VII Verify Before Report MUST Sim independent-verify.md (SDC Phase 3.5)
VIII Agent Lifecycle MUST Sim agent-lifecycle-guard.cjs (PostToolUse)
MUST -- Art. II, Agent Authority

“Apenas @devops pode executar git push para remote... Nenhum agente pode assumir autoridade de outro.” Esse paragrafo vira configuracao nos arquivos de cada agente (.claude/agents/*.md) e tambem vira check nos hooks de boundary. O harness Claude Code, puro, nao sabe disso. O AIOX adiciona o check.

.aiox-core/constitution.md:30-50
NEVER -- BLOCK severidade

Violar um NON-NEGOTIABLE = hook retorna exit 2 pro harness, que aborta a tool call e mostra o stderr no UI. E o mecanismo nativo do Anthropic (PreToolUse deny), so que o AIOX aponta ele pra regras constitucionais nomeadas.

.aiox-core/constitution.md:174-180

Severidades que viram comportamento

BLOCK
NON-NEGOTIABLE + MUST criticos

Hook exit 2. Tool call abortada. Exemplo: escrita em .aiox-core/core/ sem amendment ratificado.

WARN
MUST nao-criticos

Hook exit 0 + mensagem no stderr. Tool call prossegue, mas o usuario/agente ve o alerta. Exemplo: edicao em L2 sem amendment.

INFO
SHOULD

Reportado em relatorios / logs. Nao toca o fluxo. Exemplo: diminuicao de cobertura de testes sem falhar build.

A constituicao e o documento que traduz “boas praticas” em exit codes.
§03 Framework Boundary

L1-L2-L3-L4 — o filesystem como tabela de mutabilidade

Uma das decisoes de design mais carregadas do AIOX: ele nao trata “codigo do framework” vs “codigo do usuario” como uma distincao social (convencao, review, code review). Trata como tabela de paths em quatro camadas, cada uma com regra de mutabilidade propria. Um hook lê o file_path de cada Write/Edit e decide antes da escrita se e permitido.

Isso e o equivalente a read-only filesystem mounts num container: voce nao precisa convencer ninguem de que nao deveria editar /lib/libc.so; o sistema simplesmente nao deixa.

CamadaMutabilidadePathsEnforcement
L1 Core NEVER .aiox-core/core/ (todos subdirs por padrao),
constitution.md, bin/
l1-boundary-guard.cjs → exit 2
L2 Templates NEVER .aiox-core/development/{tasks,templates,
checklists,workflows}
l1-boundary-guard.cjs → exit 0 + WARN
L3 Config Restricted .aiox-core/data/, core-config.yaml convencoes + amendment
L3 Exception Restricted .aiox-core/core/execution/ AMA-001 + dual approval
L4 Runtime ALWAYS docs/stories/, packages/, squads/,
tests/, .aiox/agent-customizations/
livre

O que o hook faz

l1-boundary-guard.cjs roda como PreToolUse no matcher Write|Edit. Ele normaliza o file_path recebido via stdin (JSON), decide se e L1, L2 ou livre, e checa dinamicamente se algum amendment ratificado cobre o path.

// .claude/hooks/l1-boundary-guard.cjs:124-143  (isL1Protected)
function isL1Protected(filePath) {
  const normalized = filePath.replace(/^\//, "").replace(/^\.\//, "");
  // .aiox-core/core/* is L1 by default
  if (normalized.startsWith(L1_CORE_PREFIX)) return true;
  // constitution.md is L1
  if (normalized === CONSTITUTION_PATH) return true;
  // bin/ is L1
  if (normalized.startsWith(BIN_PREFIX)) return true;
  return false;
}

Quando o arquivo e L1 e nao ha amendment, a saida e um JSON com result: "block" e uma mensagem explicando qual amendment criar:

// :262-267
const msg = JSON.stringify({
  result: "block",
  reason: `[L1-Guard] BLOCKED: ${relativePath} is in L1 Core (NEVER mutability).
    No RATIFIED amendment found for this path. Create an amendment in
    .aiox/amendments/ and get dual approval (@aiox-master + @architect).`,
});
process.stdout.write(msg);
process.exit(0);

Curioso: a saida usa exit 0 + JSON result:"block", nao exit 2 direto. Essa e a forma estruturada que o harness Claude Code recentemente passou a preferir — permite razoes estruturadas ao inves de stderr cru. Parte 1 desta serie explica o protocolo.

§04 Agents Registry

20+ personas sobre o mecanismo Agent do harness

Claude Code expoe um mecanismo primitivo: o Agent tool (tambem chamado Task). Voce chama com subagent_type: "dev" e o harness busca um arquivo com aquele name em .claude/agents/. Ponto. E so isso que o kernel entrega.

O AIOX preenche esse diretorio com 20 personas, cada uma um character envelope fino apontando pra um arquivo “volumoso” em .aiox-core/development/agents/ com tasks, constraints, workflow. A separacao e intencional: o .claude/agents/ fica pequeno (o harness carrega no spawn), e o development/agents/ carrega sob demanda.

Anatomia de um agent

// .claude/agents/dev.md:1-26
---
name: dev
description: |
  Full Stack Developer (Pickle Rick). Use for code
  implementation, debugging, refactoring, and
  development best practices
context: fork
agent: dev
model: opus
---

## Mission: $ARGUMENTS

You are the dev wrapper.

1. Read `.aiox-core/development/agents/dev.md` for
   commands, constraints, and workflow rules.
2. Apply the Character Envelope below as the
   authoritative cosmetic voice layer...
3. Generate and show greeting via
   `node .aiox-core/development/scripts/generate-greeting.js dev`.
4. Execute the mission in character, following
   `.aiox-core/constitution.md`.
5. Do not invent requirements beyond project artifacts.

## Character Envelope (rick-and-morty | cosm)
- Character: Pickle Rick
- Tone: manic-resourceful
- Voice anchor: "I'M PICKLE RIIICK!"

O frontmatter name, description, model, context e consumido pelo harness nativo. O corpo (“You are the dev wrapper“) e o prompt que o harness injeta quando o subagent e spawnado. Tudo depois da primeira linha e AIOX decidindo o que o agent faz, o kernel so entrega o arquivo.

Mapa de personas (CTO: Opus obrigatorio)

PersonaNomeEscopo
@devDex / Pickle RickImplementacao, git local
@qaQuinnTestes, verdicts, qa-gate
@architectAriaDecisoes tecnicas
@pmMorganEpics, PRDs
@poPaxValidacao stories
@smRiverDrafting stories
@analystAtlasPesquisa, research
@data-engineerDaraSchema, migrations, RLS
@ux-design-expertUmaDesign specs
@devopsGage / Rick SanchezEXCLUSIVO git push / PR
@aiox-masterUnityFramework governance
@squad-creatorCriacao de squads
@tech-writerPaigeDocs e knowledge curation
@sop-chiefOrquestracao SOP squad
@copy-chiefOrquestracao copy squad
@design-chiefOrquestracao design squad
@workspace-chiefOrquestracao workspace

Diretiva CTO 2026-04-15: todos os agents AIOX em model: opus. Nao Haiku/Sonnet.

EVIDENCE -- exclusividade real, nao so moral

O arquivo .claude/agents/devops.md:4-7 declara: “ONLY agent authorized to push to remote repository.” Essa frase nao e um aviso social — ela e backed pelo git-safety.md rule (always-on) e pelo agent-authority.md rule (always-on), mais o fluxo documentado na constituicao. Quando @dev tenta um git push, o proprio prompt do agent (carregado de .aiox-core/development/agents/dev.md) instrui a delegar via @devops *push. Essa e a camada comportamental. Em ambientes maduros, ainda ha hooks Bash que interceptam o comando e bloqueiam.

.claude/rules/agent-authority.md:5 · .claude/rules/git-safety.md:18-25
§05 Hooks AIOX

25+ guardas computacionais, exit code 2 vs 0

Hooks sao a parte mais agressiva do AIOX — e tambem a mais importante: e onde “regra” vira policy executavel. O harness Claude Code oferece tres pontos de extensao: UserPromptSubmit, PreToolUse, PostToolUse, mais PreCompact. Cada hook e um processo Node ou Python que recebe um JSON via stdin, decide alguma coisa, e sinaliza via exit code: 0 (ALLOW, com output opcional no stdout/stderr), 2 (BLOCK).

O AIOX empilha 25+ hooks nos subdiretorios de .claude/hooks/. Alguns cobrem constituicao (boundary), alguns cobrem incidentes historicos (parallel-subagent-isolation), alguns sao infraestrutura (langfuse-trace-manager, synapse-engine).

l1-boundary-guard.cjs BLOCK
PreToolUse · Write|Edit

Bloqueia escritas em L1. Le amendments dinamicamente.

parallel-subagent-isolation-guard.cjs BLOCK
PreToolUse · Agent|Task

Exige isolation:"worktree" quando tree dirty ou outro writer ativo.

worktree-base-verifier.cjs BLOCK
PreToolUse · Agent

Bloqueia worktrees pinnados em base stale (INC-2 fix).

worktree-spawn-interceptor.cjs WARN/BLOCK
PreToolUse · Agent

Cobre o caso mega-workflow lock (pre-existente ao INC-1).

worktree-main-guard.cjs BLOCK
PreToolUse · Bash

Impede operacoes git perigosas (reset --hard, push -f) na main.

agent-lifecycle-guard.cjs WARN
PostToolUse · all

Art. VIII. Tracks tool uses, consecutive reads, failures. Thresholds adaptativos.

implementation-boundary-guard.cjs BLOCK
PreToolUse · Write|Edit

Evita escritas de impl fora do escopo de uma story ativa.

maestro-delegation-guard.cjs WARN
PreToolUse

Avisa quando um agent maestro tenta executar “manualmente” algo que deveria delegar.

shared-file-guard.cjs WARN
PreToolUse · Write|Edit

Detecta conflito em arquivos compartilhados entre stories concorrentes.

safe-path-guard.cjs BLOCK
PreToolUse · Bash

Bloqueia rm -rf em paths sensiveis (VPS, master.env).

enforce-tests-before-merge.cjs BLOCK
PreToolUse · Bash (merge)

Art. V. Exige testes verdes antes de qualquer git merge.

pre-commit-verification-gate.cjs BLOCK
PreToolUse · Bash (commit)

Bloqueia commits em zonas de amendment sem aprovacao dupla.

story-completeness-guard.cjs WARN
PostToolUse

Detecta story marcada “Done” com checkboxes nao batidos.

synapse-engine.cjs INFO
UserPromptSubmit

Context engine: injeta contexto relevante no prompt do usuario.

post-compaction-reinject.cjs INFO
PostCompact

Reinjeta contexto critico apos compactacao.

precompact-session-digest.cjs INFO
PreCompact

Captura digest da sessao antes da compactacao destruir contexto.

Exemplo real: parallel-subagent-isolation-guard

Depois do incidente INC-1 2026-04-15 (tres @dev e @sm subagents correndo na mesma working tree, corrompendo branches), o AIOX adicionou um hook que bloqueia spawn de writing subagents concorrentes sem worktree. Nao e regra moral: e exit 2 pro harness.

// .claude/hooks/parallel-subagent-isolation-guard.cjs:168-178
} else if (dirty && isWriting) {
  block = true;
  reason = `working tree is dirty and subagent_type="${subagentType}" can write files. ` +
           `Running without isolation:"worktree" risks data loss from concurrent git operations. ` +
           `Either (a) commit or stash pending changes, or (b) pass isolation:"worktree".`;
} else if (activeWriters >= 1 && isWriting) {
  block = true;
  reason = `${activeWriters} writing subagent(s) already active. ` +
           `Launching another writing subagent without isolation:"worktree" causes branch collision ` +
           `(incident 2026-04-15). Pass isolation:"worktree" to proceed.`;
}

if (block) {
  process.stderr.write(`\n❌ BLOCKED: Parallel Subagent Isolation rule violation\n...`);
  process.exit(2);
}
NOTE -- fail-open, nao fail-closed

Cada hook termina com main().catch(err => process.exit(0)). Se o proprio guard explodir, o AIOX prefere deixar passar — e o unico jeito razoavel de operar: um hook bugado travando todo o trabalho seria pior que a regra nao ser enforced. Tradeoff intencional, com log em stderr pra auditoria.

parallel-subagent-isolation-guard.cjs:205-209
§06 Rules System

38 arquivos — 3 always-on, 35 on-demand

O diretorio .claude/rules/ e a memoria estruturada do projeto. O harness nativo ja le arquivos CLAUDE.md como instrucoes permanentes (user-level e project-level). O AIOX usa esse mecanismo, mas introduz uma convencao: cada rule pode declarar no frontmatter um campo paths: com globs. Se presente, a rule carrega on-demand — so quando o arquivo tocado bate com o glob. Se ausente, a rule e always-on, ingerida em toda sessao.

Sao 38 arquivos. Tres sao always-on (sempre carregados): agent-authority.md, git-safety.md, parallel-subagent-isolation.md. Os outros 35 sao on-demand, carregando quando o path-matching casa.

Always-on (3)

agent-authority.md

Matriz Art. II: quem pode o que. @devops EXCLUSIVO em git push/PR/release.

.claude/rules/agent-authority.md:5
git-safety.md

1 task = 1 worktree = 1 agent. Never force-push to main. Never --no-verify sem pedido explicito.

.claude/rules/git-safety.md:1-42
parallel-subagent-isolation.md

NON-NEGOTIABLE. Concurrent writing subagents MUST pass isolation:"worktree". Backed pelo hook.

.claude/rules/parallel-subagent-isolation.md:1-40

On-demand (amostra de 12)

context-budget.mdLimites de tokens por task
context-sharding.mdSharding de PRD/Architecture
context-reset-discipline.mdQuando dar /clear
scope-discipline.mdArt. III: nao escrever fora do escopo
step-file-execution.mdPipeline stepfile (Maestro)
ids-principles.mdREUSE > ADAPT > CREATE (Art. IV-A)
verification-protocol.mdArt. VII: testes+typecheck antes de report
url-fetching.mdJina Reader para URLs
workflow-execution.mdComo executar workflows AIOX
sau-routing.mdLumos architecture routing
mandatory-tests.mdTestes obrigatorios Art. V
zero-trust-agents.mdVerificar outputs de agents
EVIDENCE -- rule como arquivo vivo

A rule parallel-subagent-isolation.md nao existia antes de 2026-04-15. Ela foi criada como resposta ao incidente INC-1. Frontmatter dela aponta: enforced_by: .claude/hooks/parallel-subagent-isolation-guard.cjs e incident: .aiox/incidents/2026-04-15-.... Isso e a propria rule fazendo rastreabilidade: regra vira hook, hook referencia incidente, incidente referencia amendment. Ciclo de governance formal, nao so markdown literario.

.claude/rules/parallel-subagent-isolation.md:1-8
§07 Skills AIOX

Auto-discovery por frontmatter — o harness faz o resto

Skills sao um mecanismo nativo do harness Claude Code: o Claude le o description do frontmatter de cada .claude/skills/nome/SKILL.md e decide sozinho quando invocar, usando o Skill tool. O AIOX coloca skills pequenos e proprios nesse diretorio — cada uma e uma capacidade auto-descoberta.

A lista atual em .claude/skills/: cli-router, deep-strategic-planning, doc-rot, gowa, tech-research, telegram. Mais o symlink mega-brain apontando pra um repositorio irmao. Skills mais gordas (squad-creator, Mega Brain) moram em squads/ e sao invocadas via comandos /Domain:skill.

cli-router

Roteia tarefa pra persona/agent correto via CLI (Gemini, Claude, Codex).

deep-strategic-planning

“Modo Dr. Estranho” — 7-10 futuros analisados por 12 lentes mentais.

doc-rot

Encontra documentacao podre pra DELETAR. TODOs stale, comentarios mentirosos, @ts-nocheck desnecessario.

gowa

Gerencia GOWA WhatsApp Gateway — API, groups, history, webhook, MCP.

tech-research

Pipeline de deep technical research. Query → Decompose → Search → Synthesize. So pesquisa, nunca codifica.

telegram

Gateway multi-runtime / multi-channel — setup, deploy, logs, webhook.

§08 Commands

Wrappers /Domain:nome por dominio

O diretorio .claude/commands/ contem comandos slash que o usuario invoca tipo /AIOX:help ou /Sop:map-core-sop-backlog. Cada comando e um arquivo .md com um prompt que o harness injeta quando voce digita o slash. O AIOX organiza por dominio: 14 pastas em nivel raiz, mais 4 comandos sueltos (greet, mega-brain, sync-repos, system-architect).

DominioConteudoExemplos
AIOX/agents + workflows/AIOX:help, /AIOX:init, /AIOX:workflows:maestro, /AIOX:agents:dev
Sop/agents + SOP tasks/Sop:map-core-sop-backlog, /Sop:agents:sop-chief
SquadCreator/agents + create-from-sop/SquadCreator:create-from-sop, /SquadCreator:agents:squad-chief
SquadCreatorPro/mind-clone personas/SquadCreatorPro:agents:pedro-valerio, oalanicolas, thiago_finch
MegaBrain/70+ commands (symlink)/MegaBrain:jarvis-full, /MegaBrain:rag-search, /MegaBrain:conclave
Workspace/CIO/COO/CMO/CTO/aiox-workspace:cio-engineer, /aiox-workspace:coo-orchestrator
Copy/copy-chief + copywriters/Copy:agents:copy-chief
Design/design-chief + brand-me/Design:brand-me, /Design:agents:design-chief
Doceng/doceng-chief/Doceng:agents:doceng-chief
ComunidadeIaYolo/community chief/ComunidadeIaYolo:agents:chief
Kb/knowledge base chief/Kb:agents:kb-chief
Support/8 agents de support-squad/Support:agents:support-chief, triage, dna-coach, etc.
aiox-workspace/C-level vision/aiox-workspace:vision-chief, caio-architect
clickup-ops/ClickUp automation/clickup-ops:clickup-chief, api-builder, playwright-ops

O que o arquivo de comando contem

Inferencia: tipicamente um prompt curto ou um wrapper que ativa um agent e carrega uma task. Por exemplo, /AIOX:agents:dev vira o agent dev. /AIOX:workflows:maestro executa o workflow Maestro step-file. /Sop:map-core-sop-backlog e uma task direta do squad SOP.

O harness Claude Code nao entende squad — ele so le .claude/commands/**/*.md e faz a expansao do slash. A organizacao em pastas e puramente AIOX.

§09 Squads

Unidade organizacional: agents + tasks + templates + checklists

Squad e um empacotamento AIOX: cada diretorio squads/nome/ tem a mesma forma — agents/, tasks/, templates/, checklists/, mais data/ (minds, DNA, dossies) e docs/. O squad-registry.yaml agrega metadata de todos os squads: versao, scores, maturity, slash-prefix, contagens.

Sao 16 squads registradas, de operacionais (aiox-ads, clickup-ops) a meta-squads (squad-creator, squad-creator-pro) a C-level (c-level, aiox-workspace).

aiox-ads
13 agents · 3 tiers · trafego pago
aiox-copy
24 agents · 87 tasks · 16 workflows
aiox-design
design system + brand
aiox-discovery
brownfield discovery
aiox-doceng
documentation eng
aiox-kb
knowledge base
aiox-sag-executor
SAG executor
aiox-slack-concierge
slack ops
aiox-sop
SOP creation
aiox-support-squad
8 agents: triage, dna-coach, ...
aiox-system-architect
system design
aiox-workspace
C-level (CIO/COO/CMO/CTO/CAIO)
c-level
executivos consolidados
claude-code-mastery
meta (esta serie)
clickup-ops
ClickUp automation
comunidade-ia-yolo
community ops
runner-ops
runner automation
squad-creator
meta-squad (cria squads)
squad-creator-pro
mind-clones Pro
NOTE -- squads vs agents/hooks/rules

Squads moram em squads/ (L4 runtime, livre pra editar). Agents/hooks/rules moram em .aiox-core/ (L1/L2, protegidos) e .claude/ (consumido pelo harness). Um squad usa os agents e rules do core, mas adiciona seus proprios agents, tasks e templates. E uma expansao horizontal do framework, nao uma alteracao dele. Analogia: squads sao “distros” ou “pacotes” instalados sobre o kernel AIOX.

§10 Gates

BLOCK / WARN / INFO — exit code como politica

Ja aparece espalhado nas secoes anteriores, mas merece ser consolidado. “Gate” em AIOX e qualquer ponto onde uma condicao constitucional ou operacional e checada e resulta em tres comportamentos possiveis:

BLOCK
Hook exit 2 — tool call abortada

NON-NEGOTIABLE + MUST criticos. Nao prossegue, mostra stderr, exige correcao. Exemplos: L1 boundary, parallel subagent sem worktree, merge sem testes verdes, commit em zona de amendment sem aprovacao.

WARN
Hook exit 0 + mensagem

MUST nao-criticos. Tool call prossegue, alerta visivel. Exemplos: edit em L2 sem amendment, shared file entre stories, lifecycle threshold (consecutive reads), maestro delegation.

INFO
Log / relatorio

SHOULD. Registrado em logs, traces (Langfuse), reports. Nao toca o fluxo. Exemplos: queda de cobertura, context injection do synapse-engine, session digest precompact.

Por que exit codes e nao exceptions

E o protocolo que o harness Claude Code entende. Hook e um subprocess que o harness spawna no PreToolUse ou PostToolUse: se o subprocess sai com codigo 2, o harness interpreta como “deny this tool call”. Nao ha exception, nao ha API custom. E a mesma unix wisdom de grep saindo com 1 quando nao encontra match — exit codes como sinal.

O AIOX escolheu abracar esse mecanismo ao pe da letra, ao inves de construir uma abstracao maior. Isso mantem o framework compativel com qualquer evolucao do harness: Anthropic pode mudar internals, mas enquanto o protocolo de hook (stdin JSON → exit code) continuar estavel, AIOX continua funcionando.

§11 Amendments

Due process do framework — YAML como lei

Amendments sao o unico jeito legitimo de relaxar L1/L2, reclassificar paths, ou adicionar novas regras NON-NEGOTIABLE. Cada amendment e um YAML em .aiox/amendments/ com campos bem definidos: amendment_id, status, severity, affected_path, justification, signatures (dual approval @aiox-master + @architect ou equivalente).

O hook l1-boundary-guard.cjs le esses YAMLs em tempo real — cada escrita em L1 carrega todos amendments com status: RATIFIED e checa se algum cobre o path. Isso significa que “ratificar” e literal: basta editar o campo status pra RATIFIED e adicionar as assinaturas pro hook parar de bloquear.

AMA-001 (2026-03-28)
Reclassify core/execution/ L1 → L3

Primeiro amendment formal. Justificativa: wave-executor + metrics + crash recovery nao cabiam em wrappers L4 sem indirecao insustentavel. 9/9 reviewers disseram que wrapper era over-engineering. Dual approval @aiox-master + @architect, both signed 2026-03-28.

.aiox/amendments/AMA-001-reclassify-execution.yaml:1-31
AMA-2026-04-15-PSI
Parallel Subagent Isolation NON-NEGOTIABLE

Reacao ao INC-1. Formaliza que Agent tool com writing subagent MUST passar isolation:"worktree" em concorrencia ou tree dirty. Enforced por hook + regression test. Retirement criteria: so desativa se harness passar a enforcar nativamente ou outro isolation primitive substituir worktree.

.aiox/amendments/2026-04-15-parallel-subagent-isolation.yaml:1-87
AMA-2026-04-15-WBV
Worktree Base Verification

Reacao ao INC-2 (Follow-up). Harness cria worktree pinned em base stale — agents spawnados ali nao veem stories recentes. Hook worktree-base-verifier.cjs bloqueia worktree com base >5 commits behind HEAD ou sem paths criticos.

.aiox/amendments/2026-04-15-worktree-base-verification.yaml
AMA-002 a AMA-011
Dez amendments menores

QA gate enhancement, course-correction retrospective, quick-dev expansion, novos L2 tasks, brainstorming refactor, APC menu markers, step-file architecture, elicitation methods, project-context-gen. Cada um com justificativa e assinatura.

Amendments transformam “mudei uma regra hoje” em “eis o YAML, eis os signatarios, eis o incidente que motivou”.
§12 Memory AIOX vs nativo

Mesmo mecanismo, contrato de precedencia

O Claude Code harness tem memoria nativa: arquivos CLAUDE.md em cascata (user-level, project-level), auto-memory em ~/.claude/projects/..., e o sistema de “remember this” via tool. O AIOX nao substitui nada disso. Ele usa e impoe uma precedencia formal.

O .claude/CLAUDE.md do projeto comeca com exatamente essa linha:

// .claude/CLAUDE.md:5
Precedencia: Constitution > .claude/rules/ > Story AC >
             project-conventions.yaml > Este arquivo > Best practices

Essa linha e uma declaracao de conflito-resolucao. Quando duas instrucoes colidem (ex: CLAUDE.md diz “push livre”, rule diz “push EXCLUSIVO @devops”), a rule ganha. Quando story AC colide com CLAUDE.md, AC ganha. Isso e governance as configuration: o modelo nao precisa racionalizar, so seguir a tabela.

Ordem de precedencia formal
  1. 1.
    Constitution — Art. I-VIII, severidades NON-NEGOTIABLE/MUST/SHOULD. .aiox-core/constitution.md
  2. 2.
    .claude/rules/ — 38 arquivos. Always-on e on-demand via frontmatter paths:.
  3. 3.
    Story AC — Acceptance Criteria da story ativa em docs/stories/.
  4. 4.
    project-conventions.yaml — convencoes do repo ativo (multi-repo detecta via cwd).
  5. 5.
    .claude/CLAUDE.md — o proprio arquivo que declara a precedencia, resumo operacional.
  6. 6.
    Best practices — fallback quando nada acima aplica.
EVIDENCE -- memory layering real

Em toda sessao, o harness injeta na system-reminder o conteudo de: (a) user-level ~/.claude/CLAUDE.md (global), (b) project-level .claude/CLAUDE.md (projeto), (c) auto-memory em ~/.claude/projects/.../memory/MEMORY.md, (d) always-on rules, (e) skills discoverable via SKILL.md frontmatter. Todos esses mecanismos sao do harness. O AIOX so preenche, com convencao de precedencia explicita no proprio CLAUDE.md.

§13 Fechamento

AIOX = produtizacao + governance do harness. Nada magico.

Mapeando tudo isso de fora: o AIOX nao estende o harness Claude Code no sentido de adicionar capacidade nova ao modelo. Ele instala uma camada editorial em cima dos pontos de extensao ja publicos: CLAUDE.md, rules, agents, hooks, skills, commands. O que muda com isso:

  • Identidade por agent. Persona, escopo, autoridade exclusiva. O modelo deixa de ser “Claude genero” e vira uma das 20 personas contextuais, com regra de delegacao clara.
  • Governanca computacional. Regras importantes (L1/L2 boundary, parallel subagent, Art. VIII lifecycle) sao enforced por hooks com exit code. Nao dependem do modelo “lembrar”.
  • Rastreabilidade formal. Regra vira rule, rule aponta hook, hook aponta incidente, incidente aponta amendment. Cada mudanca tem justificativa e assinatura.
  • Modularidade via squads. Novos dominios de trabalho (support, copy, design, ads, clickup, community) viram squads plugaveis — sem tocar no core do framework.
  • Sem fork do Claude Code. Tudo e arquivo em paths convencionais. Upgrade do harness continua funcionando (inferencia: mesmo design que usa exit-code-as-signal).
O AIOX e fino. O volume vem das muitas camadas compostas, nao de abstracoes pesadas.

E tambem ha custo, que a Parte 4 vai criticar: o overhead de onboarding (um agente novo tem que absorver constituicao, 38 rules, 25 hooks, registry de squads), o risco de rules entrarem em conflito silencioso, a dependencia de um CLAUDE.md bem-mantido, a pressao sobre o token budget quando always-on rules crescem. Mas antes da critica, vem a Parte 3 com os estudos de caso — como o AIOX se comportou em incidentes reais (INC-1, INC-2), em workflows maestro-v2, em pipelines SDC, em parallel story execution.