Esta página descreve o código de hoje: ciclo de 6 estágios + harness do Construtor (biblioteca por tools, ops, to-do ao vivo, lock da Estrutura, política no servidor, duas vias) — issues 01–08 implementadas (agent.js, agent-ops.js, agent-policy.js, agent-tools.js, agent-job.js, agent-intents.js, agent-distill.js, agent-ledger.js). O que ficou fora está marcado como pendente nos blocos «Hoje vs escopo». Specs: perfil em .scratch/ai-aprendizado-ciclo/spec.md; harness em spec-harness.md. Manutenção: app/docs/AI_AGENTE.md + AI_CONSTRUTOR.md + AI_APRENDIZADO.md.
promessa
Fontes do Construtor — e o que ensina o livro de aprendizado
O Construtor não se limita ao chat. No turno ele consulta uma biblioteca (índice no prompt, corpo por ferramenta) — isso é injeção, não o livro:
Turno de chat — insumo principal: o que o usuário deseja (ledger kind: turn)
Estantes — memória, schema + settings inteiro, diff/ops, registros de intenção, livro em capítulos, SurveyJS
Livro de aprendizado — repertório em capítulos (Parte I–VI); não viaja inteiro no system prompt; não é teto
Perfil da pesquisa — se houver surveys.research_profile, desambigua tipo / metodologia / setor / assunto
A saída do turno mutate são ops (o servidor aplica + valida e ainda devolve surveyJson ao Studio) — não um schema completo redigitado. O aceite (botão Salvar) é o que entra no ciclo de aprendizado (via rápida imediata; via lenta em lote). Rascunho não ensina.
Autosave (skipVersion: true) grava rascunho e não vira aceite. Só o botão Salvar (note: studio_json) gera versão e linha kind: accepted.
nao-e
Expectativa vs realidade
Não é (nem no escopo)
Hoje (código)
Pendente
Classificador lê JSON de cada survey_versions
Lê ledger accepted (diff de nomes + áreas) + brutos da via rápida (ops do agente, correção)
Diff do aceite com codes do schema (types, visibleIf, settings codes)
Cada mensagem vira regra
Só Salvar explícito
—
Construtor consulta /docs/ai-construtor via HTTP
Sys = proibições + runtime + índice de tools + envelope + orçamento; user = skeleton + digest do livro (≤4 linhas) + pedido; corpo do livro por chapter, schema por element/page
—
Saída = schema completo (modelo copista)
Ops por name; servidor aplica + política + verify; Studio recebe out.surveyJson. Schema inteiro só com createSurvey / 0 perguntas / rascunho
—
Três agentes conversam entre si em tempo real
Um chat (loop com tools; mutate vira job agent_turn) + um job agent_distill com dois passos (classificador → Aprendizado); via rápida no Salvar sem LLM; três sinais
Memória de chat como estante (turns) e ações com confirmação (clone/restore/status/pasta)
Restore automático
Só humano (chip vN)
Continua humano
workflow
Ciclo — clique no estágio ou no chip do documento
Fluxo cíclico, não linear. Clique no estágio para Objetivos, Detalhamento, Como processa, ver prompt (agentes IA), Exemplo, Lê/Gera e o bloco insumo to-spec; no chip do documento para a estrutura (popover). Glossário abre os nomes canônicos. Passe o mouse ou foque um estágio para o resumo do ciclo. Agrupado por ator: usuário, sistema, agentes IA.
Usuário Sistema Agentes IA Documento
Diagrama indisponível.
documento
pilar-construtor
Pilar — Construtor (edição)
Chat do Studio (rail Agente IA). POST /v1/admin/agent/chat.
intentinfo (síncrono, não edita) vs mutate (job: ops aplicadas no servidor → out.surveyJson). Resultado entra no editor como rascunho (skipVersion). Restore de versão = humano (chip vN).
Hoje vs escopo. Hoje: ops aplicadas no servidor (applyOps + agent-policy.js + verify no loop) e out.surveyJson materializado; o cliente só troca o JSON vivo. Pendente: nada neste passo.
pilar-construtor
Pilar — Construtor (estágio 6 → 1)
Chat do Studio (rail Agente IA). POST /v1/admin/agent/chat.
Harness do turno (runAgentTurn):
índice das tools (TOOL_INDEX) no system prompt — corpo por tool (não schema 40k); envelope { tool, data }; orçamento 12 passos / ~60k tokens
ops por name; servidor aplica + política + verify (com retry); Studio ainda recebe out.surveyJson
to-do ao vivo no job agent_turn (progress.plan[]); lock da Estrutura; «parar» / continue
digest do livro (≤4 linhas) colado no user message; capítulos inteiros só por chapter
Regras de comportamento em app/docs/construtor-regras.json (o turno carrega; o prompt não duplica o texto). Âncora surveyjson-form.
Hoje vs escopo. Hoje: loop com tools + ops + política + to-do + lock. Pendente: escrita de settings fora de filters|quotas|automations|messages (a estante settings lê todas as áreas, mas settingsPatch, política e correção só cobrem essas quatro); estante de memória (turns) e ações com confirmação.
pilar-classificador
Pilar — Classificador (estágio 4)
Job agent_distill (agent-distill.js). Não lê JSON completo de survey_versions.
Lê ledger kind: accepted gravado no Salvar:
diff de nomes (added / removed)
áreas de settings: filtro, cota, auto, messages, meta
Classifica num docIdfechado da lista de /docs/ai-construtor. Conclusão em duas colocações (estrito / lato) + 1–3 ledger ids de exemplo. Registro persistente: o classificador decide add / enriquece / inativa (raro, com motivo) / nada — nada é substituído por ser mais novo.
Hoje vs escopo. Hoje: via rápida no Salvar (agent_intent_raw, sinais accepted / corrected / rejected_by_verify / not_this, sem LLM) + via lenta (classifyWithLlm → decideIntentActions: add / edit-enrich / inactivate / noop por registro que bate no índice; supersedeThenInsertClassification removido). Gatilho 3+/24 h só na via lenta. Pendente: diff do aceite com codes do schema.
pilar-aprendizado
Pilar — Aprendizado (estágio 5)
Via lenta: lê registros enriquecidos e escreve o livro em capítulos (Parte I–VI) — só os tocados. Digest de 4 linhas é saída do índice, não o livro.
I Portfólio · II Forma · III Norma · IV Componentes e lato · V Linguagem · VI Índice
Hoje vs escopo. Hoje: writeChaptersWithLlm escreve só os capítulos tocados I–V (fallback heuristicChapters); Parte VI compilada pelo servidor (buildIndexChapter); mergeChapters preserva os demais; digest ≤4 linhas derivado (deriveDigest) e colado no prompt do Construtor; corpo por chapter. Layers workspace/user recebem o mesmo corpo. Sem endpoint novo.
pilar-book
Pilar — Registro de intenção e livro de aprendizado
Dois artefatos distintos. O registro de intenção é a saída do classificador. O livro de aprendizado é o que o Construtor consulta no próximo turno (saída do agente aprendizado).
Tabela agent_playbook_versions: layer workspace (até 20) e user (hash do token, até 10).
Próximo chat: loadBookItemsForPrompt (entradas da Parte VI) + pickBookItemsForPrompt (até 4) → formatBookPromptBlock = digest colado no user message; capítulos inteiros por chapter. Painel Memória (loadMemoryPanel: chapters + digest + items) = GET /v1/admin/agent/memory.
Tabela
Papel
agent_interaction_ledger
Fato: turno de chat (kind: turn, com agent_ops), chamada de tool (kind: tool) ou aceite (kind: accepted)
agent_intent_raw
Registro bruto da via rápida: docId × profileKey × componente, ops do agente, signal, correção; lido por intents(filter) e pelo classificador
agent_classification_rows
Registro de intenção enriquecido: docId + conclusão (stricto + lato) + calibração + componente [surveyId].[code] + áreas de ferramenta; persistente — classificador add / edit-enrich / inactivate (raro, com motivo) / noop
Etiquetas do catálogo (piloto/cati) — não é perfil nem área de ferramenta
agent_playbook_versions
Livro de aprendizado: body = { chapters[], readingOrder } (Parte I–VI); layers workspace/user
Hoje vs escopo. Hoje: livro em capítulos Parte I–VI; digest ≤4 linhas é saída derivada da Parte VI (deriveDigest) — colado no prompt do Construtor como índice curto; corpo por chapter. Pendente: nada neste artefato.
quando-atualiza
Quando a fila enfileira
shouldEnqueueDistill enfileira a via lenta (não a rápida) se:
3+ accepted pendentes; ou
1+ pendente e 24h desde o último livro de aprendizado; ou
1º aceite após turnos do Construtor, sem livro ainda
na-pratica
Na prática
Editar o questionário (humano ou Construtor)
Revisar no Studio
Salvar
Abrir Memória — o livro de aprendizado aparece após o distill
app/docs/AI_CONSTRUTOR.md — âncoras do livro de aprendizado
app/docs/AI_APRENDIZADO.md — esta página
legal-exclusao
Exclusão de dados
Pedido público (WhatsApp, e-mail ou CPF) para sair da lista / apagar dados. A página publica a política e o formulário; o callback da Meta só confirma recebimento.