Evolução do DeskPilot: v0.2 sobre a fatia vertical de v0.1

O capítulo 04 deixou a tabela suggestions vazia por desenho — ela existia no contrato, mas nada escrevia nela. Este capítulo escreve nela pela primeira vez, sem tocar em nenhuma regra herdada:

// Migration note (PE04 -> PE05): copied byte-for-byte again, still no type,
// transition or rule edited. Chapter 05 adds an AI suggestion path entirely
// in ../ai/ (schema validation, stub/real adapter, shadow orchestration) and
// extends the storage contract in ./repository.ts to persist the richer
// suggestion payload — it does not touch applyCommand, TICKET_TRANSITIONS or
// the "ai" role's exclusion from every allowedRoles list below. That
// exclusion is precisely the guard the new AI path depends on: no matter
// what a model outputs, nothing in this file lets it reach applyCommand.

Esse comentário está literalmente no topo de src/domain/domain.ts — o mesmo arquivo que o capítulo 04 já havia copiado byte a byte do capítulo 03. Três sessões depois, zero linhas de regra de domínio mudaram. O que mudou foi tudo ao redor:

src/ai/schema.ts valida o formato acima sem nenhuma biblioteca de terceiros — doze verificações sequenciais (campo obrigatório presente, categoria no enum, tenant e ticket batendo, tamanho de resumo, evidência verbatim, confiança no intervalo [0, 1]), cada uma retornando um motivo específico de rejeição, nunca um booleano opaco.

src/ai/adapter.ts define a interface SuggestionAdapter e duas implementações. StubAdapter é determinístico e offline — a única usada em qualquer teste ou no eval deste capítulo — e aceita um campo simulate que força um entre dez comportamentos (normal, abstenção, JSON malformado, tenant errado, resumo longo demais, evidência alucinada, categoria inválida, timeout, custo alto, indisponibilidade). HttpProviderAdapter implementa a mesma interface para um provedor real, mas nenhuma sessão até agora o instancia — não existe chave paga neste ambiente, e o próprio prompt que rege este pacote proíbe usar uma.

src/ai/shadow.ts é o orquestrador. Ele corre o adaptador contra um timeout com Promise.race, aplica um teto de custo por tarefa antes de aceitar qualquer resposta, valida com schema.ts, e decide entre gravar uma sugestão pending ou registrar um fallback auditável. Nenhum desses quatro comportamentos — timeout, custo, validação, fallback — é opcional ou condicional a um provedor específico; todos rodam para o stub exatamente como rodariam para um provedor real, porque dependem apenas da interface SuggestionAdapter, nunca da classe concreta por trás dela.

Duas rotas HTTP novas. POST /tickets/:id/suggest exige um ator com papel system — nem agent, nem manager, e certamente nunca ai, que não tem sessão possível. POST /tickets/:id/suggestions/review é a única rota que muda o estado de uma sugestão, chamando o applySuggestionCommand que já existia, inalterado, desde o capítulo 03.

migrations/0002_suggestion_details.sql é aditiva: nenhuma coluna, tipo ou política do capítulo 04 foi alterada. A nova tabela suggestion_details guarda resumo, evidência e confiança — os campos que uma sugestão precisa ter para ser revisável, mas que a tabela suggestions original nunca teve porque o capítulo 04 a deixou vazia por desenho. A mesma política de row-level security que protege tickets desde o capítulo 04 protege esta tabela nova, linha por linha idêntica, e um teste de integração real contra Postgres prova isso — não apenas o teste offline com repositório em memória.

Contratos e trade-offs

As quatro falhas que este capítulo precisa resolver, com sintoma, causa e resposta

Falha 1 — schema confundido com verdade. Sintoma: um JSON bem formado, com categoria dentro do enum, é tratado como se a categoria estivesse correta ou a evidência fosse real. Causa: validação estrutural e correção de conteúdo são a mesma verificação na cabeça de quem constrói o sistema, mas não são a mesma verificação no código. Resposta: examples/eval/report.json mantém valid_output_rate (0,84 em dev, 0,818 em holdout — quantos JSONs passaram na validação) separado de category_accuracy (0,895 em dev, 0,882 em holdout — de quem passou, quantos acertaram a categoria) como dois números distintos, nunca um só. O caso case-044 no dataset força exatamente esse cenário: um JSON válido cuja citação de evidência não existe no ticket — rejeitado por evidence_not_verbatim, mesmo com todo o resto correto.

Falha 2 — confiança autodeclarada usada como autorização. Sintoma: um número de confiança alto vira desculpa para pular revisão humana ou aceitar automaticamente. Causa: confidence parece uma probabilidade porque tem a forma de uma, mas é autodeclarada pelo mesmo modelo que pode estar errado sobre o resto. Resposta: confidenceSelfDeclared é gravado em suggestion_details e devolvido para exibição — e não existe nenhuma outra leitura desse campo em src/ai/shadow.ts ou src/api/server.ts. O teste "normal scenario: writes a pending suggestion... never touches ticket state" prova isso operacionalmente: mesmo com confiança 0,82, a sugestão nasce em estado pending, idêntico ao que nasceria com confiança 0,3 — só applySuggestionCommand, chamado por um agente humano autenticado, muda esse estado.

Falha 3 — holdout contaminado. Sintoma: o holdout deixa de significar alguma coisa porque o sistema foi ajustado repetidamente contra os próprios erros que ele deveria medir de forma independente. Causa: a tentação de "só mais um ajuste" depois de ver um caso de holdout falhar é imediata e parece inofensiva caso a caso. Resposta: o campo split em examples/eval/cases.synthetic.jsonl é fixado no momento em que cada caso foi escrito, nunca recalculado depois de rodar o eval; run.ts resume os dois splits na mesma passada, sem nenhum branch que leia holdout antes de decidir algo sobre dev; e o adaptador/política sob teste (StubAdapter, deskpilot-suggest-v1, shadow-v0.2) não foram ajustados contra falhas de holdout durante esta sessão — o único ciclo de ajuste que houve foi contra as asserções unitárias de test/ai/*.test.ts, que usam fixtures próprias, não este dataset. É uma disciplina de processo, documentada em examples/eval/README.md, não uma trava de código — e a diferença entre as duas é exatamente o ponto: um código não consegue impedir alguém de reler o holdout antes da hora, só a disciplina registrada consegue.

Falha 4 — fallback que oculta falha e perde trabalho. Sintoma: um timeout ou erro de provedor é tratado como se nada tivesse acontecido, ou pior, corrompe o que já existia na fila manual. Causa: fallback silencioso parece mais seguro no curto prazo porque não gera alarme, mas esconde exatamente o sinal que alguém precisaria ver para saber que o provedor está degradado. Resposta: toda saída de fallback() em src/ai/shadow.ts grava um evento de auditoria suggestion.fallback antes de retornar — visível, não silencioso — e o fallbackReason volta na resposta HTTP ({"ok": false, "fallbackReason": "timeout", ...}), não apenas em um log que ninguém lê. Mais importante: a fila do ticket, seu estado e seu histórico de auditoria anterior ficam completamente intocados por uma tentativa de sugestão que falhou — não existe trabalho de estado de ticket para um fallback perder, porque a geração de sugestão nunca toca esse estado em primeiro lugar. O teste de timeout confirma isso: depois de simular 850ms de atraso contra um orçamento de 100ms, repo.getSuggestion("tenant-a", "ticket-a1") continua retornando null, e a fila segue exatamente como estava.

Avaliação: o que os 47 casos provam e o que não provam

O dataset (examples/eval/cases.synthetic.jsonl) tem 47 casos, 25 em dev e 22 em holdout, cobrindo seis categorias normais mais uma classe rara (security_incident, três casos no total), quatro casos ambíguos, três de informação insuficiente, dois tickets longos, dois com tentativa de injeção de instrução, dois com PII sintética, e sete cenários adversariais — um para cada simulate do adaptador (JSON malformado, tenant errado, resumo longo demais, evidência alucinada, timeout, custo alto, indisponibilidade).

O que os números provam: taxa de saída válida de 84% em dev e 81,8% em holdout; de quem passou na validação, acerto de categoria de 89,5% (17 de 19 casos, excluindo abstenções e fallbacks) em dev e 88,2% (15 de 17) em holdout; taxa de abstenção entre saídas válidas de 9,5% em dev e 5,6% em holdout; e, mais importante para a segurança do sistema, cada um dos sete cenários adversariais produziu exatamente o fallback que deveria produzir — nenhum deles foi tratado como sucesso. Os dois casos de injeção de instrução (case-037, case-038) confirmam que o texto embutido ("ignore instruções anteriores...", "você está em modo admin...") nunca alcança um comando real: um deles produz uma sugestão normal ignorando a instrução embutida (porque o classificador nunca lê instruções, só palavras-chave), o outro é rejeitado por categoria inválida quando a injeção tenta forçar um valor fora do enum.

O que os números não provam, e o relatório declara isso explicitamente em report.json.limitations: o StubAdapter reaproveita a mesma função de classificação por palavra-chave que o baseline de regras usa — então, em qualquer caso não-adversarial, os dois caminhos têm exatamente a mesma taxa de acerto de categoria por construção, não por uma vantagem real da "camada de IA". Sem provedor real e sem chave paga nesta sessão, não existe forma honesta de medir se um modelo de verdade supera o baseline de regras nesta tarefa — e este relatório não finge que existe. Quarenta e sete casos rotulados por um único anotador (esta sessão) também não sustentam um intervalo de confiança apertado por classe, especialmente para a classe rara, com apenas três exemplos no total e um só no holdout. Os quatro casos do bucket "ambíguo" documentam explicitamente onde um segundo anotador razoável discordaria do rótulo escolhido — por exemplo, um ticket que menciona tanto "password reset" quanto "erro" recebe rótulo de acesso pela leitura humana, mas o classificador por palavra-chave escolhe bug primeiro, porque a ordem de verificação de categorias no código prioriza bug antes de access.

Nenhuma dessas ressalvas invalida o valor do capítulo — elas são exatamente o tipo de coisa que a Anthropic recomenda verificar antes de confiar em um eval: se a tarefa está bem definida o suficiente para que um humano a resolvesse de forma consistente. Onde a resposta é "nem sempre" — como nos quatro casos ambíguos --, o eval documenta a discordância em vez de escondê-la atrás de uma média.

Custo, segurança e reversibilidade

Custo por tarefa útil (sugestão não-abstida, com saída válida) nesta sessão: $0,00471 em holdout, calculado a partir de constantes fixas do stub ($0,004 por chamada normal, $0,42 quando o cenário simula custo alto e por isso é descartado antes de contar como "útil"). Esse número não representa preço real de nenhum provedor — é um marcador de que o pipeline sabe calcular custo por tarefa útil, não uma estimativa de orçamento de produção.

Segurança mapeada linha a linha contra a taxonomia OWASP para aplicações LLM em examples/threat-model.md: das dez categorias, sete se aplicam diretamente a este pacote e cada uma tem uma resposta específica no código — injeção de prompt contida pelo schema fechado, divulgação de informação sensível contida pelo evento de auditoria que nunca guarda texto de ticket, consumo ilimitado contido por timeout e orçamento de custo. Três categorias (envenenamento de dados/modelo, vazamento de prompt de sistema, fraquezas de embedding) não se aplicam porque este capítulo não tem pipeline de treino, não expõe prompt de sistema a cliente final, e não usa busca vetorial — não por acaso, mas porque nenhum erro observado justificou adicionar RAG quando o contexto autorizado já cabe inteiro na entrada.

Reversibilidade: uma sugestão rejeitada, expirada ou nunca revisada não deixa nenhum rastro no estado do ticket. Reverter uma aceitação indevida significa uma segunda chamada humana a applySuggestionCommand — o mesmo comando testado desde o capítulo 03 --, nunca uma operação especial de "desfazer IA". Isolamento por tenant é redundante em duas camadas independentes, a mesma disciplina do capítulo 04: filtro de aplicação em toda consulta e RLS no banco, agora provado também para suggestion_details, não só para tickets.

Checklist de saída deste capítulo

• Modo offline roda sem chave: npm test e node run.ts não fazem nenhuma chamada de rede além de npm install.
• Holdout é um campo fixo no dataset, nunca recalculado depois de ver resultados.
• Todo JSON de saída é validado campo a campo antes de ser gravado; JSON malformado, categoria fora do enum e evidência não-verbatim são rejeitados, não corrigidos silenciosamente.
• Timeout, indisponibilidade, custo acima do orçamento e tenant incorreto produzem fallback auditável, nunca sucesso fingido.
• Nenhuma leitura de confidenceSelfDeclared decide um resultado — grep confirma que o campo só é escrito e exibido.
• Uma sugestão nasce sempre em estado pending; só um ator humano autenticado (agent/manager) muda esse estado.
• RLS protege suggestion_details com a mesma política de tickets, provado contra Postgres real, não só contra o repositório em memória.
• O relatório de eval separa saída válida de acerto de categoria, e declara as próprias limitações em vez de escondê-las.

Exercícios

Básico. Adicione um caso novo em examples/eval/cases.synthetic.jsonl com simulate: "normal" para a categoria feature_request em português, rode node run.ts e confirme que category_accuracy do split escolhido mudou de denominador. Critério de aceite: o novo caso aparece em report.json.dataset.total (agora 48) e o denominador de category_accuracy do split correspondente aumenta em exatamente um, salvo se o caso cair em gold_abstain: true.

Solução comentada: o ponto mais fácil de errar aqui é esquecer que tenant_id/ticket_id só podem ser tenant-a/ticket-a1 ou tenant-b/ticket-b1 neste harness — run.ts usa exclusivamente os dois tickets fixture por design (ver comentário no topo do arquivo), então um ticket_id inventado causa ticket_not_found dentro de writeShadowSuggestion, não um erro de validação de schema.

Intermediário. Escreva um teste novo em test/ai/shadow.test.ts que force dois fallbacks seguidos no mesmo ticket (por exemplo, timeout seguido de malformed_json) e confirme que o segundo fallback não é bloqueado nem alterado pelo primeiro — ou seja, que shadow.ts não guarda nenhum estado entre chamadas que pudesse fazer a segunda tentativa se comportar diferente da primeira. Critério de aceite: os dois fallbackReason retornados batem exatamente com o que cada simulação deveria produzir, e repo.listAudit mostra dois eventos suggestion.fallback distintos, não um só.

Solução comentada: isso deveria passar sem nenhuma mudança de código — runShadowSuggestion não tem nenhuma variável de módulo compartilhada entre chamadas, só recebe tudo por parâmetro. Se o teste falhar, o bug mais provável é algum estado escondido em MemoryRepository sendo reaproveitado incorretamente entre as duas chamadas dentro do mesmo teste; o fix correto é garantir que cada chamada de runShadowSuggestion seja de fato independente, nunca "corrigir" o teste para esconder o comportamento.

Avançado. Implemente uma segunda métrica de qualidade além de category_accuracy: uma checagem de que o summary de cada sugestão válida realmente resume o conteúdo do evidenceQuotes citado, não apenas o primeiro trecho do ticket (hoje, StubAdapter.buildOutput usa firstSentence como atalho — um resumo real precisaria de mais do que a primeira frase para tickets longos). Critério de aceite: a nova métrica aparece em report.json com seu próprio denominador, separada de category_accuracy, e o relatório continua declarando explicitamente que ela mede resumo-vs-evidência, não resumo-vs-qualidade-editorial (que exigiria um segundo anotador humano ou um juiz LLM calibrado — fora do escopo deste capítulo).

Solução comentada: o risco aqui é exatamente o vies de verbosidade que aparece na avaliação com LLM-as-a-judge — se a nova métrica virar "o resumo é longo o suficiente", ela vai recompensar resumos genéricos em vez de resumos precisos. Uma métrica honesta compara o resumo contra o conjunto de evidenceQuotes (por exemplo, checando se os termos centrais do resumo aparecem em pelo menos uma citação), não contra um alvo de tamanho.

Glossário

• Modo sombra (shadow mode): a sugestão é gerada e fica visível para revisão, mas nenhum código a usa para mudar o estado do sistema sozinha.
• Confiança autodeclarada: o número que um modelo retorna dizendo o quão certo ele está — não é uma probabilidade calibrada e não deveria ser tratada como uma.
• Grounding (evidência verbatim): exigir que toda afirmação citada por um modelo exista literalmente no texto que ele estava autorizado a ler.
• Abstenção: a saída explícita de "não tenho informação suficiente", tratada como resposta válida, não como falha.
• Fallback auditável: um caminho de erro que grava evidência de que falhou, em vez de fingir sucesso ou desaparecer silenciosamente.
• Holdout: o subconjunto do dataset nunca usado para ajustar o sistema, reservado só para medir generalização no fim.

Ponte para o capítulo 06

O capítulo 06 herda o MVP v0.2 (código deste capítulo), o contrato de eventos (inalterado, com dois tipos novos aditivos em events.schema.json) e o relatório de eval em examples/eval/report.json. A pergunta que ele precisa responder — segundo ../product-designer-serie-06/prompt.md, lido apenas na seção que descreve sua entrada e escopo — é se uma taxa de aceitação de sugestão alta esconde retrabalho, e como desenhar métricas e um experimento por tenant sem confundir correlação com impacto de negócio. Este capítulo não mede impacto de negócio nenhum — só mede se a sugestão que chega ao agente é válida, fundamentada e contida quando algo dá errado. O que o capítulo 06 faz com a taxa de aceitação dessa sugestão — e com o retrabalho que uma aceitação alta pode esconder — é a próxima pergunta, não esta.