@jaimevalasek/aioson 1.7.2 → 1.8.0

package/docs/pt/feature-archive.md

@@ -0,0 +1,191 @@
+# Feature Archive — Limpeza automática do contexto
+
+O `feature:archive` move os artefatos de uma feature concluída para `.aioson/context/done/{slug}/` e mantém um manifest que permite aos agentes consultarem o histórico sem carregar os arquivos arquivados.
+
+O objetivo é manter o root de `.aioson/context/` enxuto automaticamente — o usuário não precisa fazer nada.
+
+---
+
+## Como funciona
+
+Quando o `@qa` aprova uma feature e roda `aioson feature:close --verdict=PASS`, o arquivamento acontece no mesmo ato:
+
+```
+@qa aprova → aioson feature:close --feature={slug} --verdict=PASS
+                ├── atualiza spec-{slug}.md (QA sign-off)
+                ├── atualiza features.md → done
+                ├── limpa project-pulse.md
+                └── chama feature:archive automaticamente
+                        ├── move *-{slug}.{md,yaml,yml,json} → done/{slug}/
+                        └── atualiza done/MANIFEST.md
+```
+
+Não existe etapa manual. O contexto fica limpo sem que o desenvolvedor precise lembrar de nada.
+
+---
+
+## Arquivos que são movidos
+
+O comando identifica os artefatos da feature pelo padrão de nome: qualquer arquivo no **root** de `.aioson/context/` que contenha o slug da feature no nome. Exemplos para `--feature=checkout`:
+
+```
+prd-checkout.md
+spec-checkout.md
+requirements-checkout.md
+architecture-checkout.md
+implementation-plan-checkout.md
+sheldon-enrichment-checkout.md
+qa-report-checkout.md
+qa-report-checkout-hardening.md   ← sufixo extra: também capturado
+conformance-checkout.yaml
+security-findings-checkout.json
+```
+
+**O que nunca é movido:**
+
+- Arquivos globais do projeto: `project.context.md`, `project-pulse.md`, `features.md`, `discovery.md`, `design-doc.md`, `prd.md`, `architecture.md`, `scan-*.md`, `test-plan.md`, `test-inventory.md`, `module-src.md`, `context-pack.md`, `memory-index.md`, `handoff-*.json`, etc.
+- Subdiretórios: `bootstrap/`, `forensics/`, `parallel/`, `seeds/`, `done/`
+- Arquivos de outra feature (proteção contra colisão de slugs similares)
+
+---
+
+## O manifest
+
+Após cada arquivamento, `.aioson/context/done/MANIFEST.md` é atualizado com uma linha por feature:
+
+```markdown
+| slug | completed | files | summary |
+|------|-----------|-------|---------|
+| checkout | 2026-04-24 | 7 | Fluxo completo de checkout com Stripe e endereço. |
+| user-auth | 2026-03-10 | 5 | Autenticação JWT com refresh token e 2FA opcional. |
+```
+
+O summary é extraído automaticamente da seção `## Vision` do PRD da feature.
+
+Agentes que precisam de contexto histórico (`@cypher`, `@neo`, `@discover`, `@sheldon`) leem o manifest em vez de varrer os arquivos arquivados — custo de tokens mínimo.
+
+---
+
+## Comandos disponíveis
+
+### Arquivamento (chamado automaticamente pelo feature:close)
+
+```bash
+# Já acontece automaticamente via feature:close --verdict=PASS
+aioson feature:close . --feature=checkout --verdict=PASS
+
+# Mas você pode rodar diretamente se precisar
+aioson feature:archive . --feature=checkout
+
+# Ver o que seria movido sem mover nada
+aioson feature:archive . --feature=checkout --dry-run
+
+# Desabilitar o archive automático em um feature:close específico
+aioson feature:close . --feature=checkout --verdict=PASS --no-archive
+```
+
+### Restauração (para reabrir uma feature arquivada)
+
+```bash
+# Ver o que seria restaurado
+aioson feature:archive . --feature=checkout --restore --dry-run
+
+# Restaurar os arquivos de volta ao root
+aioson feature:archive . --feature=checkout --restore
+```
+
+Após restaurar, atualize `features.md` manualmente se quiser mudar o status da feature de `done` para `in_progress`.
+
+### Arquivamento retroativo
+
+Para features que já estão como `done` em `features.md` mas ainda têm arquivos no root (projetos que fizeram upgrade do AIOSON):
+
+```bash
+aioson feature:archive . --feature=cypher-agent
+aioson feature:archive . --feature=harness-driven-aioson
+# etc.
+```
+
+O comando é idempotente — rodar duas vezes na mesma feature é no-op seguro.
+
+### Opção --force
+
+```bash
+# Arquivar mesmo que o slug não esteja registrado em features.md
+aioson feature:archive . --feature=minha-feature --force
+```
+
+Use apenas em emergências ou migrações manuais.
+
+### Saída JSON
+
+```bash
+aioson feature:archive . --feature=checkout --json
+```
+
+```json
+{
+  "ok": true,
+  "slug": "checkout",
+  "completed": "2026-04-24",
+  "archiveDir": ".aioson/context/done/checkout",
+  "moved": ["prd-checkout.md", "spec-checkout.md"],
+  "skipped": [],
+  "totalArchived": 7,
+  "manifestEntry": {
+    "slug": "checkout",
+    "completed": "2026-04-24",
+    "files": "7",
+    "summary": "Fluxo completo de checkout com Stripe e endereço."
+  }
+}
+```
+
+---
+
+## Estrutura após o arquivamento
+
+```
+.aioson/context/
+├── project.context.md       ← global, nunca arquivado
+├── project-pulse.md         ← global
+├── features.md              ← registro de todas as features
+├── prd-nova-feature.md      ← feature ativa (ainda no root)
+├── done/
+│   ├── MANIFEST.md          ← resumo de todas as features concluídas
+│   ├── checkout/
+│   │   ├── prd-checkout.md
+│   │   ├── spec-checkout.md
+│   │   └── ...
+│   └── user-auth/
+│       ├── prd-user-auth.md
+│       └── ...
+└── bootstrap/               ← cache semântico (separado)
+```
+
+---
+
+## Impacto nos agentes
+
+| Agente | Comportamento |
+|--------|--------------|
+| `@qa` | Roda `aioson feature:close --verdict=PASS` ao fechar — o archive cascateia automaticamente |
+| `@dev`, `@analyst`, `@architect`, `@tester`, `@pm`, `@ux-ui` | Sem mudança — já operavam apenas na feature ativa |
+| `@product` | Sem mudança — vê apenas `prd.md` e `prd-{slug}.md` ativos |
+| `@cypher` | Lê `done/MANIFEST.md` para evitar duplicar briefings de features já entregues |
+| `@neo` | Lê `done/MANIFEST.md` para contexto geral do projeto |
+| `@discover` | Lê `done/MANIFEST.md` ao montar `bootstrap/what-it-does.md` |
+| `@sheldon` | Lê `done/MANIFEST.md` — features arquivadas não aparecem no menu de enrichment |
+
+---
+
+## Safety guards
+
+| Situação | Comportamento |
+|----------|--------------|
+| Feature com status `in_progress` em `features.md` | Aborta com erro (use `--force` para forçar) |
+| Feature não registrada em `features.md` | Aborta com erro (use `--force` para forçar) |
+| Arquivo já presente no destino | Skip silencioso (idempotente) |
+| `--restore` com conflito no root | Aborta e lista os conflitos — resolve manualmente |
+| `--verdict=FAIL` no feature:close | Sem arquivamento (feature permanece no root para correção) |
+| Subdiretórios em `.aioson/context/` | Nunca afetados — o glob é somente sobre arquivos no root |

package/docs/pt/genome-3.0-spec.md

@@ -1,9 +1,10 @@
 # Genome 3.0 — Especificação de Formato
 
-> Versão: 3.0  
+> Versão: 3.1  
 > Status: Ativo  
-> Compatibilidade: retrocompatível com Genome 2.0  
-> Data: 2026-03-13
+> Compatibilidade: retrocompatível com Genome 2.0 e 3.0  
+> Data: 2026-04-07  
+> Changelog: adição de campos 4.0-track (anchor_prompt, relations, hexaco_h, trait_interactions)
 
 ---
 
@@ -57,6 +58,13 @@ generated: [YYYY-MM-DD]
 sources_count: [int]
 mentes: [int]
 skills: [int]
+# Campos opcionais do track 4.0 (retrocompatíveis — leitores 2.0/3.0 ignoram)
+relations:
+  - genome: [slug]
+    type: [complementa|contradiz|depende-de|sobrepõe]
+activation_scope:
+  - task: [strategic-decision|content-generation|review-critique|research]
+    load: [lista de seções canônicas a carregar]
 ---
 ```
 
@@ -71,9 +79,17 @@ disc: "[XY]"
 enneagram: "[XwY]"
 big_five: "O:[H] C:[M] E:[L] A:[L] N:[M]"
 mbti: "[XXXX]"
+# hexaco_h: dimensão Honesty-Humility do HEXACO (opcional, track 4.0)
+# Relevante para personas com dimensão ética, negociação ou comportamento moral
+# low = tendência estratégico-manipulativa | high = código de honra rígido, transparência auto-imposta
+hexaco_h: [low|medium|high]
 confidence: [low|medium|high]
 profiler_report: ".aioson/profiler-reports/[slug]/enriched-profile.md"
 hybrid_mode: [domain-function|single-persona|multi-persona]
+# anchor_prompt: resumo ultra-compacto para reforço em sessões longas (track 4.0)
+# Inserir a cada ~10 turnos para evitar deriva de persona (PersonaAgent NeurIPS 2025)
+anchor_prompt: |
+  [1-3 linhas: traço dominante, padrão de julgamento, anti-padrão central]
 ```
 
 ### Exemplo de frontmatter persona
@@ -130,6 +146,14 @@ profiler_report: ".aioson/profiler-reports/stefan-georgi/enriched-profile.md"
 | `## Vieses e Pontos Cegos` | Sim | Biases, erros recorrentes e compensações |
 | `## Conflict Resolution` | Só multi-persona | Hierarquia e desempate entre personas |
 
+### Opcionais — track 4.0 (retrocompatíveis)
+
+| Seção | Quando usar |
+|-------|-------------|
+| `## Trait Interactions` | Em `## Perfil Cognitivo` de personas com perfis psicométricos combinados complexos |
+| `## Relations` | Quando o genome depende ou complementa outros genomes instalados |
+| `## Activation Scope` | Quando o genome deve carregar seções diferentes por tipo de task |
+
 ---
 
 ## Estrutura recomendada das novas seções
@@ -216,6 +240,78 @@ Cobrir:
 
 ---
 
+## Seções track 4.0 (opcionais, retrocompatíveis)
+
+### `## Trait Interactions`
+
+Incluída dentro de `## Perfil Cognitivo` quando a combinação de traços psicométricos gera comportamentos emergentes relevantes para quem aplica o genome.
+
+**Por que importa:** pesquisa de 2026 (HumanLLM arXiv 2601.10198) demonstrou que avaliar traços em combinação (MPD — Multi-Pattern Dynamics) produz fidelidade de persona significativamente superior à avaliação por traço isolado (IPE). Um perfil DISC:D + Enneagram:9 cria tensão real que muda como o agente se comporta.
+
+Estrutura recomendada:
+
+```markdown
+### Trait Interactions
+
+| Combinação | Comportamento Emergente | Implicação para Agentes |
+|---|---|---|
+| DISC-D × Enneagram-9 | Liderança assertiva em público, conflito-aversivo em privado | Não espere confronto direto — busque harmonia primeiro |
+| Big Five O:H × C:H | Cria sistemas para explorar novidade — inventário, não caos | Respostas vêm em frameworks, não em brainstorms livres |
+| Enneagram-3w4 × DISC-DI | Competição orientada a distintividade, não só resultado | Gatilho: comparação com pares percebidos como criativos |
+```
+
+Regras:
+- incluir apenas combinações que gerem comportamento não-óbvio
+- máximo 5 entradas por genome
+- focar em implicações práticas para agentes que aplicam o genome
+
+### `## Relations`
+
+Declara dependências e relações tipadas com outros genomes instalados no projeto.
+
+**Por que importa:** Agentic RAG e sistemas de memória 2026 (A-MEM, MemOS) demonstram que representação explícita de relações entre nós de conhecimento reduz turnos necessários em 18% e aumenta completude de task em 19%.
+
+Estrutura recomendada:
+
+```markdown
+## Relations
+
+| Genome | Tipo | Nota |
+|---|---|---|
+| `persuasion-psychology` | depende-de | frameworks de persuasão usados nas heurísticas |
+| `brand-voice-acme` | sobrepõe | voz da marca tem precedência sobre tom genérico |
+| `storytelling-retention` | complementa | narrativa + copy trabalham juntos |
+```
+
+Tipos válidos:
+- `depende-de` — este genome pressupõe o outro instalado
+- `complementa` — combinação produz resultado superior
+- `contradiz` — aplicar ambos simultaneamente cria conflito — escolher um
+- `sobrepõe` — o outro tem precedência no campo declarado
+
+### `## Activation Scope`
+
+Define quais seções canônicas carregar por tipo de task. Permite injeção parcial do genome em contexto, reduzindo tokens e aumentando precisão.
+
+**Por que importa:** PRISM (arXiv 2603.18507, 2026) demonstrou que personas de expert melhoram alinhamento mas podem danificar acurácia factual quando ativadas integralmente em tasks analíticas. Roteamento seletivo por task resolve isso.
+
+Estrutura recomendada:
+
+```markdown
+## Activation Scope
+
+| Task type | Seções a carregar |
+|---|---|
+| `strategic-decision` | Filosofias, Modelos mentais, Perfil Cognitivo |
+| `content-generation` | Frameworks, Heurísticas, Skills, Estilo de Comunicação |
+| `review-critique` | Vieses e Pontos Cegos, Mentes, Application notes |
+| `research` | O que saber, Evidence, Relations |
+```
+
+Se esta seção estiver ausente: carregar o genome completo (comportamento padrão).
+
+---
+
 ## Regras de compatibilidade
 
 ### Leitura por sistema 2.0
@@ -247,6 +343,15 @@ Quando um genome persona for gerado sem profiler completo:
 - `confidence: low`
 - incluir disclaimer explícito em `## Application notes`
 
+### Campos track 4.0 (adição retrocompatível)
+
+Os campos `relations`, `activation_scope`, `hexaco_h` e `anchor_prompt` são retrocompatíveis por adição:
+
+- leitores 2.0/3.0 que não reconhecem esses campos os ignoram
+- o genome continua válido e operacional sem eles
+- nenhum campo track 4.0 é obrigatório
+- `anchor_prompt` é recomendado para genomes persona usados em sessões longas (multi-turn)
+
 ---
 
 ## Meta file recomendado
@@ -268,8 +373,14 @@ Além do markdown, recomenda-se um `.meta.json` correspondente com:
   "enneagram": "3w4",
   "big_five": "O:H C:H E:H A:M N:L",
   "mbti": "ENTJ",
+  "hexaco_h": "medium",
   "confidence": "medium",
-  "profiler_report": ".aioson/profiler-reports/stefan-georgi/enriched-profile.md"
+  "profiler_report": ".aioson/profiler-reports/stefan-georgi/enriched-profile.md",
+  "anchor_prompt": "Pensa em copy como vendedor infatigável. Pesquisa antes de escrever. Mecanismo vem antes do headline. Especificidade > generalidade. Evitar: persuasão genérica sem ângulo único.",
+  "relations": [
+    { "genome": "copywriting", "type": "complementa" },
+    { "genome": "persuasion-psychology", "type": "depende-de" }
+  ]
 }
 ```
 

package/docs/pt/genome-distribution.md

@@ -0,0 +1,232 @@
+# Genome Distribution — Modelo de Distribuição via aioson.com
+
+> Versão: 1.0
+> Status: Spec
+> Data: 2026-04-07
+> Substitui: referências a makopy.com (descontinuado)
+
+---
+
+## Visão geral
+
+Genomes podem ser criados por usuários localmente, publicados no registry do **aioson.com** e instalados em projetos de terceiros via CLI.
+
+---
+
+## Tiers de genome
+
+| Tier | Origem | Curadoria | Disponível em |
+|---|---|---|---|
+| `aioson-core` | Equipe AIOSON | Revisão manual | Template + aioson.com |
+| `community` | Usuários publicados | Score por downloads/rating | aioson.com |
+| `local` | Usuário, não publicado | Nenhuma | Só no projeto |
+
+Genomes `aioson-core` chegam pré-instalados no `template/.aioson/genomes/`.
+Genomes `community` precisam ser instalados via `aioson genome:install`.
+
+---
+
+## Formato de arquivo — decisão de estrutura
+
+### Decisão: genome permanece arquivo `.md` monolítico
+
+Razões:
+- O genome é **camada cognitiva** (injetada em contexto de LLM), não playbook operacional
+- Material de referência profundo vive em skills — o genome referencia skills, não as duplica
+- Arquivo único facilita install, diff, versionamento e injeção em contexto
+- Genome denso é preferível a genome fragmentado: a pesquisa de 2026 confirma que structured prompts superam narrativas dispersas
+
+### Exceção: companion dir opcional para genomes ricos
+
+Quando um genome precisar de material de evidência ou referência própria (não reutilizável por skills), pode ter um diretório companion:
+
+```
+.aioson/genomes/
+  copywriting.md            ← genome principal (sempre presente)
+  copywriting.meta.json     ← metadata (sempre presente)
+  copywriting.refs/         ← companion dir (opcional)
+    evidence-appendix.md
+    trait-examples.md
+```
+
+O sistema lê o companion dir automaticamente quando presente, mas não o requer.
+
+### Genomes persona (3.0)
+
+Para genomes com `type: persona` ou `type: hybrid`, o pipeline Profiler já produz arquivos separados em:
+
+```
+.aioson/profiler-reports/{slug}/
+  research-report.md
+  enriched-profile.md
+```
+
+Esses arquivos são a fonte de verdade para o genome. Não precisam ir para o companion dir.
+
+---
+
+## Dependências declaradas no `.meta.json`
+
+Genomes podem declarar quais skills e outros genomes são necessários para funcionar corretamente. Isso evita que o usuário instale um genome e descubra na hora de usar que referências estão quebradas.
+
+### Formato
+
+```json
+// .aioson/genomes/{slug}.meta.json
+{
+  "dependencies": {
+    "skills": ["marketing", "storytelling"],
+    "genomes": ["copywriting"]
+  }
+}
+```
+
+### Quando declarar
+
+| Situação | Declarar |
+|---|---|
+| Genome referencia arquivos de uma skill específica (ex: `## Conditional reference loading`) | Sim — declare a skill |
+| Genome persona pressupõe que outro genome de domínio está instalado | Sim — declare o genome |
+| Genome não referencia nenhum arquivo externo | Não — deixar arrays vazios |
+
+### Comportamento do sistema
+
+**`aioson genome:doctor <file>`** — verifica se todas as dependências estão disponíveis no projeto:
+```
+skill "marketing": OK (.aioson/skills/marketing)
+skill "storytelling": MISSING
+→ Install: aioson skill:install --slug=storytelling
+```
+
+**`@genome` (agente) ao aplicar (Opção 4)** — checa dependências antes de vincular ao squad. Avisa se houver dependências ausentes e pergunta se deve prosseguir.
+
+**`aioson genome:install` (futuro)** — ao instalar um genome do aioson.com, lê `dependencies` do meta e oferece instalar as dependências na mesma operação:
+```
+Genome "persona-copy" requires:
+  skills: marketing, persuasion-psychology
+  genomes: copywriting
+Install dependencies too? [Y/n]
+```
+
+### Skills built-in vs. instaladas
+
+O sistema considera uma skill disponível se ela existir em qualquer um destes caminhos:
+- `.aioson/installed-skills/{slug}/` — skills instaladas via `skill:install`
+- `.aioson/skills/{slug}/` — skills built-in do projeto (sem precisar instalar)
+
+Genomes `aioson-core` como `copywriting` dependem da skill `marketing` que já vem built-in no template. Projetos que não usam o template precisam instalar essa skill separadamente.
+
+---
+
+## Fluxo de publicação (usuário → aioson.com)
+
+### Pré-requisito
+
+```bash
+aioson config set AIOSON_TOKEN=<token>
+# Token obtido em aioson.com/settings
+```
+
+### Publicar genome
+
+Via agente `@genome`, opção [3] na etapa de resultado.
+
+Ou via CLI (a implementar):
+
+```bash
+aioson genome:publish --slug=copywriting
+```
+
+O sistema envia `.md` + `.meta.json`. O companion dir `.refs/` é enviado se presente.
+
+### Resultado após publicação
+
+```
+Genome publicado: aioson.com/genomes/copywriting
+Instalar em outro projeto: aioson genome:install --slug=copywriting
+```
+
+---
+
+## Fluxo de instalação (terceiro → projeto)
+
+```bash
+aioson genome:install --slug=copywriting
+```
+
+**Comportamento:**
+1. Busca o genome no registry do aioson.com
+2. Baixa `.md` + `.meta.json` para `.aioson/genomes/{slug}.md`
+3. Baixa `.refs/` se presente
+4. Registra em `.aioson/genomes/.installed.json` (source, slug, installedAt, version)
+5. Confirma: `Genome "copywriting" instalado em .aioson/genomes/`
+
+**Flags:**
+- `--force` — sobrescreve se já existir
+- `--dry-run` — mostra o que seria instalado sem salvar
+- `--from=./path/genome.md` — instala de arquivo local
+
+---
+
+## Registro de genomes instalados
+
+```json
+// .aioson/genomes/.installed.json
+[
+  {
+    "slug": "copywriting",
+    "source": "community",
+    "author": "jaimevalasek",
+    "version": "1.2.0",
+    "installedAt": "2026-04-07T14:00:00Z",
+    "path": ".aioson/genomes/copywriting.md"
+  }
+]
+```
+
+---
+
+## Comandos CLI (a implementar em /dev)
+
+| Comando | Descrição |
+|---|---|
+| `aioson genome:install --slug=X` | Instala genome do aioson.com |
+| `aioson genome:install --from=./path` | Instala de arquivo local |
+| `aioson genome:publish --slug=X` | Publica genome no aioson.com |
+| `aioson genome:list` | Lista genomes instalados no projeto |
+| `aioson genome:remove --slug=X` | Remove genome do projeto |
+| `aioson genome:doctor <file>` | Valida genome (já existe) |
+| `aioson genome:migrate <file>` | Migra formato legado (já existe) |
+
+---
+
+## Relação com o sistema de skills
+
+Genome e skill têm sistemas de install paralelos mas independentes:
+
+| Aspecto | Skill | Genome |
+|---|---|---|
+| Install | `aioson skill:install` | `aioson genome:install` |
+| Destino | `.aioson/installed-skills/{slug}/` | `.aioson/genomes/{slug}.md` |
+| Estrutura | Diretório com `SKILL.md` + refs | Arquivo `.md` + `.meta.json` opcional |
+| Distribuição npm | Via `@tech-leads-club/agent-skills` | Não (só aioson.com) |
+| Distribuição cloud | Via `cloudBaseUrl` | Via aioson.com registry |
+
+Um genome pode **referenciar** skills, mas não os empacota:
+
+```markdown
+## Conditional reference loading
+
+| When writing... | Load these references |
+|---|---|
+| Any sales page | `.aioson/skills/marketing/references/patterns.md` |
+```
+
+---
+
+## Notas de compatibilidade
+
+- `MAKOPY_KEY` é descontinuado — usar `AIOSON_TOKEN`
+- Projetos que tinham `MAKOPY_API_KEY` no `.aioson/install.json` devem migrar para `AIOSON_TOKEN`
+- O `mcp-init.js` não inclui mais o servidor makopy
+- Genomes gerados antes desta spec continuam funcionando sem mudanças

package/docs/pt/inicio-rapido.md

@@ -246,5 +246,6 @@ Exemplos:
 - [Como usar com Claude Code, Codex e Gemini](./clientes-ai.md)
 - [Cenários completos com exemplos práticos](./cenarios.md)
 - [Guia de agentes: quando usar cada um](./agentes.md)
+- [Hardening do motor: gates, auto-cura e test briefing](./motor-hardening.md)
 - [Suporte a projetos Web3](./web3.md)
 - [Orquestração paralela para projetos MEDIUM](../en/parallel.md)