@jaimevalasek/aioson 1.3.0

package/docs/pt/profiler-system.md

@@ -0,0 +1,214 @@
+# Sistema Profiler — Guia Rápido
+
+> Pipeline oficial para pesquisa, enriquecimento e geração de Genoma 3.0 e Advisors no AIOSON.
+
+---
+
+## O que é
+
+O Sistema Profiler cria um perfil cognitivo inferido de pessoas públicas a partir de evidências observáveis. O objetivo não é produzir uma "persona decorativa", mas sim um artefato utilizável que capture:
+
+- como a pessoa pensa
+- como decide
+- como comunica
+- onde demonstra expertise real
+- quais vieses e blind spots aparecem com frequência
+
+O pipeline gera dois outputs principais:
+
+- `Genoma 3.0`: conhecimento destilado + perfil cognitivo aplicável a agentes executores
+- `Advisor Agent`: conselheiro ativo que responde como a persona, com web search e memória
+
+---
+
+## Pipeline
+
+O fluxo oficial é sequencial:
+
+1. `@profiler-researcher`
+   Coleta material público e organiza evidências em `.aioson/profiler-reports/{person-slug}/research-report.md`
+2. `@profiler-enricher`
+   Consolida a pesquisa com materiais extras do usuário e produz `.aioson/profiler-reports/{person-slug}/enriched-profile.md`
+3. `@profiler-forge`
+   Transforma o perfil enriquecido em Genoma 3.0, Advisor Agent ou ambos
+
+Fluxo resumido:
+
+```text
+Pessoa alvo
+  -> @profiler-researcher
+  -> research-report.md
+  -> @profiler-enricher
+  -> enriched-profile.md
+  -> @profiler-forge
+  -> Genoma 3.0 / Advisor / ambos
+```
+
+---
+
+## Como iniciar
+
+### Opção 1: pipeline completo
+
+```text
+@profiler-researcher Stefan Georgi
+```
+
+Depois siga a sequência natural:
+
+```text
+@profiler-enricher stefan-georgi
+@profiler-forge stefan-georgi
+```
+
+### Opção 2: via `@genoma`
+
+```text
+@genoma
+Tipo: persona
+Pessoa: Stefan Georgi
+Domínio: direct response copywriting
+```
+
+Quando `type: persona` é detectado, o `@genoma` deve redirecionar para o pipeline profiler por padrão.
+
+### Opção 3: modo rápido
+
+Se o usuário pedir explicitamente um genoma persona rápido, leve ou `--quick`, o sistema pode gerar um resultado com baixa fidelidade usando apenas conhecimento inferido do LLM.
+
+Nesses casos:
+
+- `evidence_mode: inferred`
+- `confidence: low`
+- o arquivo deve explicitar que não houve profiling baseado em evidência
+
+---
+
+## Dimensões capturadas
+
+O profiler trabalha com múltiplas camadas de análise:
+
+- `DISC`
+- `Eneagrama`
+- `Big Five`
+- `MBTI`
+- frameworks e heurísticas de decisão
+- estilo de comunicação
+- valores e crenças operacionais
+- expertise demonstrada
+- histórico de decisões públicas
+- influências e antagonismos
+- vieses cognitivos e padrões de erro
+- valores inferidos via Schwartz
+- perfil de risco
+- estilo de liderança, quando aplicável
+
+Todos os perfis psicométricos devem ser tratados como `INFERIDOS`.
+
+---
+
+## Arquivos gerados
+
+### Relatórios intermediários
+
+```text
+.aioson/profiler-reports/{person-slug}/
+  research-report.md
+  enriched-profile.md
+```
+
+### Outputs finais
+
+```text
+.aioson/genomas/{person-slug}-{domain-slug}.md
+.aioson/genomas/{person-slug}-{domain-slug}.meta.json
+.aioson/advisors/{person-slug}-advisor.md
+```
+
+---
+
+## Quando usar Genoma 3.0
+
+Use Genoma 3.0 quando você quer enriquecer executores já existentes com a forma de pensar de uma pessoa.
+
+Exemplos:
+
+- copywriter do squad escrevendo com o raciocínio de um especialista em ofertas
+- estrategista editorial operando com lentes mentais de um criador específico
+- time de liderança avaliando decisões com a filosofia operacional de uma referência
+
+Genoma é artefato passivo. Ele não executa sozinho.
+
+---
+
+## Quando usar Advisor
+
+Use Advisor quando você quer consulta direta.
+
+Exemplos:
+
+- pedir opinião estratégica
+- desafiar um plano
+- analisar copy, documento, pitch ou tese
+- interpretar contexto atual com web search
+
+Advisor é ativo. Ele não substitui o executor; ele aconselha.
+
+---
+
+## Board de Advisors
+
+Múltiplos advisors podem operar como um board para comparar perspectivas.
+
+Uso recomendado:
+
+- decisões estratégicas
+- revisão de oferta
+- análise de mercado
+- resolução de conflito entre frameworks
+
+Nesse modelo:
+
+- cada advisor responde separadamente
+- o sistema destaca convergências e divergências
+- o usuário escolhe qual linha seguir ou aprofundar
+
+---
+
+## Critérios de qualidade
+
+Um profiling é considerado forte quando:
+
+- existe evidência suficiente e variada
+- os claims principais estão ancorados em fontes
+- a expertise real foi separada de opinião superficial
+- o output diferencia conhecimento, estilo, princípio e viés
+- limitações e blind spots aparecem explicitamente
+
+Sinais de profiling fraco:
+
+- material escasso
+- excesso de inferência sem evidência
+- confusão entre fama e competência
+- psicometria afirmada sem disclaimer
+
+---
+
+## Relação com o sistema atual
+
+O Profiler System é uma extensão do fluxo de genomas, não um substituto do Genoma 2.0.
+
+- Genoma 2.0 continua válido para `domain` e `function`
+- Genoma 3.0 entra quando existe `persona`
+- Advisors convivem com squads como membros consultivos
+- relatórios intermediários viram a fonte de verdade para reprocessamento futuro
+
+---
+
+## Regras operacionais
+
+- não tratar inferência psicométrica como diagnóstico clínico
+- não omitir limitações do perfil
+- não pular o enriquecimento quando o objetivo for alta fidelidade
+- preservar os relatórios intermediários como trilha de auditoria
+- preferir `Genoma 3.0 + Advisor` quando o caso exigir execução e consultoria

package/docs/pt/runtime-observability.md

@@ -0,0 +1,72 @@
+# Runtime Observability
+
+## Objetivo
+
+Estabelecer o runtime do projeto como autoridade unica para:
+
+- task
+- run de agente
+- eventos operacionais
+- enforcement de workflow
+
+O prompt do agente nao e mais responsavel por persistir telemetria.
+
+## Principios
+
+1. Toda execucao relevante deve passar por um gateway oficial.
+2. O SQLite em `.aioson/runtime/aios.sqlite` e a fonte primaria de runtime por projeto.
+3. `execution_events` e o event store canonico.
+4. `tasks` e `agent_runs` permanecem como projecoes operacionais para UI e consultas simples.
+5. Workflow obrigatorio deve ser aplicado no runtime, nao em convencoes textuais de prompt.
+
+## Tabelas
+
+- `tasks`: unidade de trabalho visivel para o usuario
+- `agent_runs`: execucao concreta de um agente
+- `agent_events`: feed legado de compatibilidade
+- `execution_events`: trilha canonica append-only de observabilidade
+
+## Metadados novos em `agent_runs`
+
+- `source`
+- `workflow_id`
+- `workflow_stage`
+- `parent_run_key`
+
+## Taxonomia de runtime
+
+- `agent_kind=official`: agentes nativos do AIOS executados de forma direta ou governada
+- `agent_kind=squad`: sessoes e handoffs ligados a `@squad`
+- `agent_kind=workflow`: controlador de workflow e etapas de governanca
+
+- `source=direct`: handoff direto de agente oficial
+- `source=workflow`: execucao ou redirecionamento governado por workflow
+- `source=orchestration`: operacoes de controle como `parallel:*` e handoff de `@orchestrator`
+- `source=squad_session`: handoff direto para `@squad`
+
+## Papel do gateway
+
+O gateway oficial de execucao deve:
+
+1. resolver o projeto alvo
+2. garantir o runtime inicializado
+3. abrir ou reutilizar a task correta
+4. abrir ou reutilizar runs necessarios
+5. emitir eventos canonicos
+6. atualizar estado final de task e runs
+
+## Estado atual da implementacao
+
+- `install` e `init` agora inicializam o runtime no projeto
+- `execution_events` foi adicionado ao schema do runtime
+- `workflow:next` sincroniza task/run/eventos reais no SQLite via gateway
+- `agent:prompt` classifica handoffs diretos de `@squad` e `@orchestrator` no runtime
+- `parallel:init`, `parallel:assign` e `parallel:status` registram operacoes canonicas de orquestracao
+- templates novos nao instruem mais o agente a chamar `runtime-log` por shell snippet
+
+## Proximos passos
+
+1. instrumentar execucao de subagentes e runs filhas com `parent_run_key`
+2. conectar comandos de doctor/qa/squad pipeline ao mesmo gateway operacional
+3. migrar o dashboard para consumir `execution_events` como feed principal
+4. adicionar spool append-only como fallback de resiliencia