@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/{memoria-contexto.md → _arquivo/memoria-contexto.md}

@@ -1,255 +1,262 @@
-# Memória e Contexto
-
-> Guia prático para entender quais arquivos o AIOSON gera, qual é a função de cada um e como montar contexto mínimo para trabalhar melhor com LLMs e CLIs como Codex, Claude Code e Gemini.
-
-## Visão geral
-
-O AIOSON separa contexto em camadas para evitar que você precise mandar o repositório inteiro para a IA em toda tarefa.
-
-Pense assim:
-
-- `scan:*` gera mapas e índices do código
-- `discovery.md` e `skeleton-system.md` explicam o sistema existente
-- `architecture.md` define a estrutura técnica alvo
-- `spec.md` guarda a memória viva do desenvolvimento
-- arquivos derivados, como `memory-index.md` e `spec-current.md`, ajudam a carregar só o que importa
-- `context:pack` monta um pacote mínimo de leitura para uma tarefa específica
-
-## Arquivos principais
-
-| Arquivo | Papel |
-|---|---|
-| `.aioson/context/project.context.md` | Contexto base do projeto: stack, classificação, idioma, framework e premissas |
-| `.aioson/context/discovery.md` | Memória de descoberta do sistema existente |
-| `.aioson/context/skeleton-system.md` | Índice estrutural leve do sistema |
-| `.aioson/context/architecture.md` | Decisões técnicas e estrutura de implementação |
-| `.aioson/context/spec.md` | Memória viva de desenvolvimento; continua sendo a fonte principal |
-| `.aioson/context/memory-index.md` | Índice de navegação: “leia este arquivo quando precisar de X” |
-| `.aioson/context/spec-current.md` | Recorte derivado do `spec.md` com foco no estado atual |
-| `.aioson/context/spec-history.md` | Recorte derivado do `spec.md` com foco no histórico |
-| `.aioson/context/module-<pasta>.md` | Memória focada de um módulo ou pasta escaneada |
-| `.aioson/context/context-pack.md` | Pacote mínimo para a tarefa atual |
-
-## Arquivos de scan
-
-Quando você roda `scan:project`, o AIOSON gera os mapas brutos do projeto:
-
-- `.aioson/context/scan-index.md`
-- `.aioson/context/scan-folders.md`
-- `.aioson/context/scan-<pasta>.md`
-- `.aioson/context/scan-aioson.md`
-
-Esses arquivos são ótimos para brownfield porque mostram a estrutura real do código. Eles não substituem o `discovery.md`; eles servem de base para construí-lo.
-
-## O que o scan gera hoje
-
-### 1. Scan local
-
-```bash
-aioson scan:project . --folder=src,app
-```
-
-Esse modo gera:
-
-- `scan-index.md`
-- `scan-folders.md`
-- `scan-src.md`, `scan-app.md`, etc.
-- `scan-aioson.md`
-- `memory-index.md`
-- `module-src.md`, `module-app.md`, etc.
-
-Se existir `spec.md`, ele também gera:
-
-- `spec-current.md`
-- `spec-history.md`
-
-### 2. Scan com LLM
-
-```bash
-aioson scan:project . --folder=src,app --with-llm --provider=openai
-```
-
-Além dos arquivos acima, esse modo gera ou atualiza:
-
-- `discovery.md`
-- `skeleton-system.md`
-
-Importante:
-
-- `scan:project` nunca gera `architecture.md`
-- `architecture.md` continua vindo depois com `@architect`
-
-## Merge x rewrite
-
-Quando `discovery.md` e `skeleton-system.md` já existem, o padrão agora é:
-
-```bash
-aioson scan:project . --folder=src,app --with-llm --provider=openai
-```
-
-Nesse caso, o comportamento é `merge`.
-
-O que isso significa:
-
-- o scanner lê a memória existente
-- tenta preservar conhecimento estável e notas ainda válidas
-- atualiza o que mudou no projeto
-- cria backup automático em `.aioson/backups/` antes de sobrescrever
-
-Se você quiser regenerar do zero:
-
-```bash
-aioson scan:project . --folder=src,app --with-llm --provider=openai --context-mode=rewrite
-```
-
-Use `rewrite` quando:
-
-- a memória antiga está claramente errada
-- o projeto mudou radicalmente
-- você quer uma regeneração limpa
-
-## O papel do `spec.md`
-
-O `spec.md` continua sendo a memória viva principal do desenvolvimento.
-
-Os derivados:
-
-- `spec-current.md`
-- `spec-history.md`
-
-não substituem o `spec.md`. Eles existem para facilitar leitura seletiva.
-
-Regra prática:
-
-- quer a verdade completa do histórico e do plano? leia `spec.md`
-- quer só o estado atual e o que está em andamento? leia `spec-current.md`
-- quer decisões passadas, trabalho concluído e contexto histórico? leia `spec-history.md`
-
-## O papel do `memory-index.md`
-
-O `memory-index.md` é um roteador.
-
-Ele existe para responder perguntas como:
-
-- “qual arquivo devo ler primeiro?”
-- “onde está o contexto de produto?”
-- “onde está a memória de implementação?”
-- “qual arquivo eu abro para um módulo específico?”
-
-Em vez de mandar tudo para a LLM, você pode começar por ele e depois abrir apenas o que fizer sentido.
-
-## O que é `context:pack`
-
-`context:pack` é um montador de contexto mínimo.
-
-Exemplo:
-
-```bash
-aioson context:pack . --agent=dev --goal="ajustar captions do editor do YouTube" --module=src
-```
-
-Ele gera:
-
-- `.aioson/context/context-pack.md`
-
-Esse arquivo contém:
-
-- ordem de leitura recomendada
-- lista dos arquivos escolhidos
-- trechos embutidos dos arquivos mais relevantes
-
-Na prática, ele tenta selecionar só o que a tarefa precisa, por exemplo:
-
-- `project.context.md`
-- `memory-index.md`
-- `skeleton-system.md`
-- `discovery.md`
-- `spec-current.md`
-- `architecture.md`
-- `module-src.md`
-- `scan-src.md`
-
-## Fluxos práticos
-
-### Brownfield sem API no AIOSON
-
-```bash
-aioson scan:project . --folder=src,app
-aioson context:pack . --agent=analyst --goal="consolidar discovery brownfield" --module=src
-```
-
-Depois:
-
-1. Abra Codex, Claude Code ou Gemini CLI.
-2. Rode `@analyst`.
-3. Use os arquivos de scan ou o `context-pack.md` para escrever `discovery.md`.
-4. Depois passe para `@architect`.
-5. Só então vá para `@dev`.
-
-### Brownfield com API no AIOSON
-
-```bash
-aioson scan:project . --folder=src,app --with-llm --provider=openai
-aioson context:pack . --agent=dev --goal="implementar ajuste no caption editor" --module=src
-```
-
-Depois:
-
-1. Revise `discovery.md` com `@analyst` se necessário.
-2. Gere `architecture.md` com `@architect`.
-3. Monte um `context:pack` para a tarefa atual.
-4. Trabalhe com `@dev`.
-
-### Atualizar memória existente com segurança
-
-```bash
-aioson scan:project . --folder=src,app --with-llm --provider=openai
-```
-
-Esse comando:
-
-- usa `merge` por padrão
-- preserva a memória existente quando possível
-- cria backup automático
-
-### Forçar regeneração limpa
-
-```bash
-aioson scan:project . --folder=src,app --with-llm --provider=openai --context-mode=rewrite
-```
-
-## Regra simples para uso diário
-
-Se estiver em dúvida, siga esta ordem:
-
-1. `project.context.md`
-2. `memory-index.md`
-3. `skeleton-system.md`
-4. `discovery.md`
-5. `spec-current.md`
-6. `architecture.md`
-7. `module-<pasta>.md` ou `scan-<pasta>.md` só se precisar aprofundar
-
-## O que pode ir para commit
-
-Regra prática:
-
-- pode versionar os arquivos de `.aioson/context/`
-- pode versionar squads e genomes do projeto quando eles forem parte real do trabalho
-- normalmente nao deve versionar arquivos gerenciados do framework em `.aioson/agents/`, `.aioson/locales/`, `.aioson/skills/`, `.aioson/schemas/`, `.aioson/tasks/`, `.aioson/templates/` e `.aioson/advisors/`
-
-O AIOSON agora reforça isso no `.gitignore` do projeto durante `install`, `update` e `scan:project`.
-
-Importante:
-
-- se esses arquivos ja estavam rastreados pelo Git antes, adicionar no `.gitignore` nao basta
-- nesse caso, remova-os do indice uma vez com `git rm --cached` para que parem de aparecer no status
-
-## Resumo sem dúvida
-
-- `scan:project` cria os mapas e os derivados locais
-- `--with-llm` gera ou atualiza `discovery.md` e `skeleton-system.md`
-- `merge` é o padrão para brownfield
-- `rewrite` é opção explícita para regeneração limpa
-- `spec.md` continua sendo a fonte principal da memória de desenvolvimento
-- `context:pack` serve para montar um pacote mínimo e relevante para a tarefa atual
+# [Arquivado] Memória e Contexto
+
+> **Esta doc foi consolidada em [`5-referencia/memoria-e-contexto.md`](../5-referencia/memoria-e-contexto.md)**.
+> Conteúdo abaixo preservado para referência histórica.
+
+---
+
+# Memória e Contexto
+
+> Guia prático para entender quais arquivos o AIOSON gera, qual é a função de cada um e como montar contexto mínimo para trabalhar melhor com LLMs e CLIs como Codex, Claude Code e Gemini.
+
+## Visão geral
+
+O AIOSON separa contexto em camadas para evitar que você precise mandar o repositório inteiro para a IA em toda tarefa.
+
+Pense assim:
+
+- `scan:*` gera mapas e índices do código
+- `discovery.md` e `skeleton-system.md` explicam o sistema existente
+- `architecture.md` define a estrutura técnica alvo
+- `spec.md` guarda a memória viva do desenvolvimento
+- arquivos derivados, como `memory-index.md` e `spec-current.md`, ajudam a carregar só o que importa
+- `context:pack` monta um pacote mínimo de leitura para uma tarefa específica
+
+## Arquivos principais
+
+| Arquivo | Papel |
+|---|---|
+| `.aioson/context/project.context.md` | Contexto base do projeto: stack, classificação, idioma, framework e premissas |
+| `.aioson/context/discovery.md` | Memória de descoberta do sistema existente |
+| `.aioson/context/skeleton-system.md` | Índice estrutural leve do sistema |
+| `.aioson/context/architecture.md` | Decisões técnicas e estrutura de implementação |
+| `.aioson/context/spec.md` | Memória viva de desenvolvimento; continua sendo a fonte principal |
+| `.aioson/context/memory-index.md` | Índice de navegação: “leia este arquivo quando precisar de X” |
+| `.aioson/context/spec-current.md` | Recorte derivado do `spec.md` com foco no estado atual |
+| `.aioson/context/spec-history.md` | Recorte derivado do `spec.md` com foco no histórico |
+| `.aioson/context/module-<pasta>.md` | Memória focada de um módulo ou pasta escaneada |
+| `.aioson/context/context-pack.md` | Pacote mínimo para a tarefa atual |
+
+## Arquivos de scan
+
+Quando você roda `scan:project`, o AIOSON gera os mapas brutos do projeto:
+
+- `.aioson/context/scan-index.md`
+- `.aioson/context/scan-folders.md`
+- `.aioson/context/scan-<pasta>.md`
+- `.aioson/context/scan-aioson.md`
+
+Esses arquivos são ótimos para brownfield porque mostram a estrutura real do código. Eles não substituem o `discovery.md`; eles servem de base para construí-lo.
+
+## O que o scan gera hoje
+
+### 1. Scan local
+
+```bash
+aioson scan:project . --folder=src,app
+```
+
+Esse modo gera:
+
+- `scan-index.md`
+- `scan-folders.md`
+- `scan-src.md`, `scan-app.md`, etc.
+- `scan-aioson.md`
+- `memory-index.md`
+- `module-src.md`, `module-app.md`, etc.
+
+Se existir `spec.md`, ele também gera:
+
+- `spec-current.md`
+- `spec-history.md`
+
+### 2. Scan com LLM
+
+```bash
+aioson scan:project . --folder=src,app --with-llm --provider=openai
+```
+
+Além dos arquivos acima, esse modo gera ou atualiza:
+
+- `discovery.md`
+- `skeleton-system.md`
+
+Importante:
+
+- `scan:project` nunca gera `architecture.md`
+- `architecture.md` continua vindo depois com `@architect`
+
+## Merge x rewrite
+
+Quando `discovery.md` e `skeleton-system.md` já existem, o padrão agora é:
+
+```bash
+aioson scan:project . --folder=src,app --with-llm --provider=openai
+```
+
+Nesse caso, o comportamento é `merge`.
+
+O que isso significa:
+
+- o scanner lê a memória existente
+- tenta preservar conhecimento estável e notas ainda válidas
+- atualiza o que mudou no projeto
+- cria backup automático em `.aioson/backups/` antes de sobrescrever
+
+Se você quiser regenerar do zero:
+
+```bash
+aioson scan:project . --folder=src,app --with-llm --provider=openai --context-mode=rewrite
+```
+
+Use `rewrite` quando:
+
+- a memória antiga está claramente errada
+- o projeto mudou radicalmente
+- você quer uma regeneração limpa
+
+## O papel do `spec.md`
+
+O `spec.md` continua sendo a memória viva principal do desenvolvimento.
+
+Os derivados:
+
+- `spec-current.md`
+- `spec-history.md`
+
+não substituem o `spec.md`. Eles existem para facilitar leitura seletiva.
+
+Regra prática:
+
+- quer a verdade completa do histórico e do plano? leia `spec.md`
+- quer só o estado atual e o que está em andamento? leia `spec-current.md`
+- quer decisões passadas, trabalho concluído e contexto histórico? leia `spec-history.md`
+
+## O papel do `memory-index.md`
+
+O `memory-index.md` é um roteador.
+
+Ele existe para responder perguntas como:
+
+- “qual arquivo devo ler primeiro?”
+- “onde está o contexto de produto?”
+- “onde está a memória de implementação?”
+- “qual arquivo eu abro para um módulo específico?”
+
+Em vez de mandar tudo para a LLM, você pode começar por ele e depois abrir apenas o que fizer sentido.
+
+## O que é `context:pack`
+
+`context:pack` é um montador de contexto mínimo.
+
+Exemplo:
+
+```bash
+aioson context:pack . --agent=dev --goal="ajustar captions do editor do YouTube" --module=src
+```
+
+Ele gera:
+
+- `.aioson/context/context-pack.md`
+
+Esse arquivo contém:
+
+- ordem de leitura recomendada
+- lista dos arquivos escolhidos
+- trechos embutidos dos arquivos mais relevantes
+
+Na prática, ele tenta selecionar só o que a tarefa precisa, por exemplo:
+
+- `project.context.md`
+- `memory-index.md`
+- `skeleton-system.md`
+- `discovery.md`
+- `spec-current.md`
+- `architecture.md`
+- `module-src.md`
+- `scan-src.md`
+
+## Fluxos práticos
+
+### Brownfield sem API no AIOSON
+
+```bash
+aioson scan:project . --folder=src,app
+aioson context:pack . --agent=analyst --goal="consolidar discovery brownfield" --module=src
+```
+
+Depois:
+
+1. Abra Codex, Claude Code ou Gemini CLI.
+2. Rode `@analyst`.
+3. Use os arquivos de scan ou o `context-pack.md` para escrever `discovery.md`.
+4. Depois passe para `@architect`.
+5. Só então vá para `@dev`.
+
+### Brownfield com API no AIOSON
+
+```bash
+aioson scan:project . --folder=src,app --with-llm --provider=openai
+aioson context:pack . --agent=dev --goal="implementar ajuste no caption editor" --module=src
+```
+
+Depois:
+
+1. Revise `discovery.md` com `@analyst` se necessário.
+2. Gere `architecture.md` com `@architect`.
+3. Monte um `context:pack` para a tarefa atual.
+4. Trabalhe com `@dev`.
+
+### Atualizar memória existente com segurança
+
+```bash
+aioson scan:project . --folder=src,app --with-llm --provider=openai
+```
+
+Esse comando:
+
+- usa `merge` por padrão
+- preserva a memória existente quando possível
+- cria backup automático
+
+### Forçar regeneração limpa
+
+```bash
+aioson scan:project . --folder=src,app --with-llm --provider=openai --context-mode=rewrite
+```
+
+## Regra simples para uso diário
+
+Se estiver em dúvida, siga esta ordem:
+
+1. `project.context.md`
+2. `memory-index.md`
+3. `skeleton-system.md`
+4. `discovery.md`
+5. `spec-current.md`
+6. `architecture.md`
+7. `module-<pasta>.md` ou `scan-<pasta>.md` só se precisar aprofundar
+
+## O que pode ir para commit
+
+Regra prática:
+
+- pode versionar os arquivos de `.aioson/context/`
+- pode versionar squads e genomes do projeto quando eles forem parte real do trabalho
+- normalmente nao deve versionar arquivos gerenciados do framework em `.aioson/agents/`, `.aioson/locales/`, `.aioson/skills/`, `.aioson/schemas/`, `.aioson/tasks/`, `.aioson/templates/` e `.aioson/advisors/`
+
+O AIOSON agora reforça isso no `.gitignore` do projeto durante `install`, `update` e `scan:project`.
+
+Importante:
+
+- se esses arquivos ja estavam rastreados pelo Git antes, adicionar no `.gitignore` nao basta
+- nesse caso, remova-os do indice uma vez com `git rm --cached` para que parem de aparecer no status
+
+## Resumo sem dúvida
+
+- `scan:project` cria os mapas e os derivados locais
+- `--with-llm` gera ou atualiza `discovery.md` e `skeleton-system.md`
+- `merge` é o padrão para brownfield
+- `rewrite` é opção explícita para regeneração limpa
+- `spec.md` continua sendo a fonte principal da memória de desenvolvimento
+- `context:pack` serve para montar um pacote mínimo e relevante para a tarefa atual