[P0][Continuous Findings] Reports em todas as etapas e issue obrigatória para todo problema encontrado

[wesleysimplicio]

Contexto

Complementa e endurece o contrato entregue em #433.

O reporting por etapa não pode apenas mostrar que um problema ocorreu. Todo problema confirmado encontrado durante qualquer etapa do loop deve virar um work item rastreável no GitHub, inclusive quando a origem estiver em:

• uma skill do Simplicio ou de terceiros;
• outro projeto/repositório do ecossistema;
• CLI, MCP, hook, adapter, runtime, provider ou ferramenta externa;
• build, lint, teste, integração, sistema, segurança, performance, documentação, instalação, empacotamento ou operação;
• configuração, contrato, permissão, autenticação, compatibilidade, observabilidade ou experiência do usuário.

Nenhum finding pode existir apenas em log, comentário, receipt, memória do agente ou resposta final.

Objetivo

Implementar um Finding → Report → Issue → Resolution lifecycle transversal a todas as etapas do simplicio-loop, garantindo que:

1. cada etapa produza report estruturado;
2. cada problema confirmado gere ou atualize exatamente uma issue canônica;
3. a issue seja criada no repositório responsável sempre que possível;
4. falhas de roteamento ou permissão gerem issue de fallback no simplicio-loop;
5. a issue contenha contexto profundo, reprodução, causa provável/confirmada, plano passo a passo, critérios de aceite e estratégia de testes;
6. o item original fique vinculado à issue derivada e não seja declarado completamente entregue se deixou problema in-scope sem rastreamento;
7. duplicatas sejam reconciliadas por fingerprint, sem “issue spam”;
8. a resolução só seja aceita com evidência verificável.

Invariantes obrigatórios

• Report em todas as etapas: nenhuma transição de stage ocorre sem stage report persistido.
• Issue para todo problema: todo finding classificado como problema confirmado produz issue_created ou issue_linked_existing.
• Nada silencioso: erro ao criar a issue produz outbox durável, retry e estado explícito issue_reporting_pending.
• Sem falso COMPLETE: findings in-scope não rastreados bloqueiam COMPLETE.
• Responsabilidade correta: issue vai para o repositório proprietário do componente afetado, não automaticamente para o repositório atualmente executado.
• Sem duplicação: o mesmo defeito observado por vários agents/stages/runs converge para uma issue canônica.
• Profundidade mínima: issue rasa, sem reprodução, passos de implementação, testes e critérios de aceite é inválida.
• Evidência antes de fechar: comentário “feito” ou confiança do agente não substitui teste/receipt/commit/PR verificável.
• Segurança: secrets, tokens, PII, signed URLs e logs crus nunca são publicados.

Cobertura obrigatória por etapa

Etapa	Report obrigatório	Problemas que devem abrir/vincular issue
Intake/preflight	fonte, autenticação, capacidades, versões, configuração	auth ausente, versão incompatível, requisito ambíguo, contrato incompleto
Mapping/orientation	freshness, cobertura, símbolos, dependências, drift	mapa stale/incompleto, parser quebrado, dependência não resolvida, arquivo ignorado
Planning	ACs, riscos, impacto, dependências, plano revisionado	AC impossível/não testável, conflito arquitetural, lacuna de spec, dependência externa
Execution	progresso, comandos, alterações, retries, receipts	erro de código, comando inexistente, skill inválida, tool failure, integração ausente
Validation	unit/integration/system/E2E, lint, typecheck, build	qualquer falha, teste ausente/fraco/flaky, caminho não exercitado, mock enganoso
Safety/security	classificação, scans, approvals, policy	secret, injection, authz, supply chain, operação destrutiva, permissão excessiva
Review	findings por reviewer e síntese	bug, regressão, dívida introduzida, qualidade, compatibilidade, blast radius
Delivery	branch/commit/PR/checks/merge/source sync	push/PR/check/merge falho, pacote não integrado, release/install incompleto
Watch/recovery	regressão, drift, retry, quarantine, stale state	regressão pós-entrega, loop travado, retry infinito, receipt inconsistente
Final audit/learning	cobertura de AC, findings ledger, precedentes	evidência ausente, claim falso, documentação divergente, problema residual

Classificação do finding

Criar contrato simplicio.finding/v1 com:

• finding_id, fingerprint e dedup_scope;
• run_id, task_id, stage, agent_id, attempt, fence;
• tipo: bug | security | performance | reliability | integration | test-gap | documentation | packaging | tooling | skill | configuration | compatibility | ux | other;
• estado: suspected | confirmed | disproved | accepted-risk | resolved | regressed;
• severidade e prioridade separadas;
• componente, skill/tool/provider e versão;
• repositório proprietário e repositório observado;
• symptom, expected, actual, reproduction;
• evidence refs sanitizadas;
• impacto e blast radius;
• causa provável e nível de confiança;
• source revision/head SHA;
• issue target, issue number/URL e remote confirmation;
• timestamps, retries e reason codes.

Regra de confirmação

• confirmed: reprodução determinística, teste falhando, contrato violado ou evidência independente suficiente → issue obrigatória.
• suspected: criar/atualizar uma issue de investigação quando não for possível confirmar dentro do orçamento; nunca declarar o fato como confirmado.
• disproved: registrar receipt com evidência e não abrir issue nova.
• accepted-risk: exige ator, justificativa, prazo/revisão e issue rastreável.

Resolução do repositório proprietário

Implementar IssueTargetResolver determinístico:

1. ler ownership explícito no manifesto/registry;
2. resolver package/module → repository;
3. resolver skill → plugin/repository de origem;
4. resolver CLI/tool/adapter → repository configurado;
5. considerar CODEOWNERS, dependency metadata e source URL;
6. confirmar que o target existe e que há permissão de issue;
7. se houver mais de um candidato, criar issue de triagem no control repo com candidatos/evidência;
8. se não houver permissão/conector, criar fallback no simplicio-loop com label external-owner-pending;
9. nunca adivinhar silenciosamente o proprietário.

Configuração proposta:

finding_issues:
  enabled: true
  required: true
  target_policy: owning_repository
  fallback_repository: wesleysimplicio/simplicio-loop
  suspected_policy: investigation_issue
  dedup_scope: repository
  max_create_retries: 8

Template mínimo obrigatório da issue derivada

Toda issue criada automaticamente deve conter:

1. Resumo objetivo
2. Origem da descoberta — run, task, stage, agent e item pai
3. Componente afetado — repo/path/symbol/skill/tool e versão
4. Comportamento esperado
5. Comportamento atual
6. Passos exatos para reproduzir
7. Evidências sanitizadas e reproduzíveis
8. Impacto, severidade e blast radius
9. Causa raiz — confirmada ou hipóteses claramente marcadas
10. Plano de implementação passo a passo, indicando arquivos/contratos quando conhecidos
11. Compatibilidade, migração, rollback e riscos
12. Plano de testes — unitário, integração, sistema/E2E, regressão e fault injection conforme aplicável
13. Critérios de aceite verificáveis em checkboxes
14. Definition of Done
15. Links bidirecionais para item pai, report, receipt, PR e issues relacionadas
16. marker invisível estável:

<!-- simplicio-loop:finding:v1 fingerprint=<sha256> owner=<repo> -->

A criação deve falhar na validação local se o template mínimo não estiver completo.

Deduplicação e atualização

1. Normalizar erro removendo timestamps, IDs efêmeros, paths locais e números de linha instáveis.
2. Calcular fingerprint com owner_repo + component + error_class + normalized_signature + affected_contract.
3. Procurar marker/fingerprint em issues abertas e fechadas.
4. Issue aberta encontrada: comentar nova ocorrência e atualizar occurrence count/last seen.
5. Issue fechada com mesma versão/causa: reabrir como regressão.
6. Issue fechada com causa diferente: criar nova issue e relacionar.
7. Findings parecidos, mas não comprovadamente iguais, não podem ser mesclados automaticamente.
8. Updates concorrentes usam intent/confirmation e re-query após timeout.
9. Persistir canonical_issue_id no finding ledger.
10. Um run com 100 observações idênticas deve produzir uma issue e 100 ocorrências auditáveis.

Reports em todas as etapas

Estender o stage reporting de #433 com:

• findings_total, confirmed, suspected, resolved, untracked;
• links das issues derivadas por etapa;
• estado do issue outbox;
• última confirmação remota;
• problemas externos e target owner;
• duplicatas reconciliadas;
• blockers para completion.

Cada stage receipt deve incluir:

{
  "findings": [],
  "issue_projection": {
    "required": true,
    "pending": 0,
    "confirmed": [],
    "high_water_mark": 0
  }
}

Transição de stage deve chamar o collector antes de persistir o report. Findings tardios de review/watcher devem atualizar reports anteriores sem reescrever receipts imutáveis: emitir evento de correção vinculado.

Outbox transacional e recuperação

Criar outbox append-only para:

• issue_create_intent;
• issue_create_confirmation;
• issue_update_intent;
• issue_update_confirmation;
• issue_reopen_intent;
• issue_link_confirmation.

Requisitos:

• retry com exponential backoff + jitter;
• re-query por marker antes de repetir mutation;
• retomada após crash;
• idempotency key;
• dead-letter observável, nunca descarte;
• rate-limit consciente;
• ordenação por sequence/high-water mark;
• CLI:
  • simplicio-loop findings list --json
  • simplicio-loop findings report --json
  • simplicio-loop findings flush --json
  • simplicio-loop findings reconcile --json
  • simplicio-loop findings doctor --json.

Plano de implementação

1. Mapear todos os producers de erro/finding no runner, stage agents, adapters, hooks, review, tests, delivery e watcher.
2. Definir schemas finding/v1, issue intent, issue confirmation, occurrence e resolution receipt.
3. Implementar FindingCollector transversal e API única; proibir criação ad hoc fora dela.
4. Integrar collector antes de cada stage transition/report.
5. Implementar IssueTargetResolver e registry de ownership do ecossistema.
6. Implementar validator do template profundo.
7. Implementar fingerprint, busca, dedup, reopen e link de ocorrências.
8. Criar GitHub issue adapter transacional com outbox e reconciliation.
9. Integrar projeção aos comentários de stage de [P0][Stage Agents][GitHub Reporting] Reportar cada item, agente e transição do fluxo por comentários idempotentes #433.
10. Adicionar completion gate para untracked_confirmed_findings == 0.
11. Integrar problemas de skills, plugins, CLIs, MCPs, hooks, runtimes e providers.
12. Implementar fallback control issue quando target externo estiver indisponível.
13. Adicionar sanitização e allowlist de evidências/URLs.
14. Implementar comandos CLI e diagnósticos.
15. Atualizar SKILL.md, referências, schemas, README e runbook.
16. Atualizar cópias bundled/plugin/wheel e testar parity.
17. Executar migração de findings existentes em logs/receipts ainda sem issue.
18. Validar em sandbox multi-repo e publicar receipts de conformidade.

Matriz de testes obrigatória

Unitários

• schema e state machine;
• fingerprint estável;
• normalização de dados efêmeros;
• target resolver;
• template validator;
• sanitização;
• severity/priority;
• dedup/reopen;
• completion gate;
• report aggregation.

Integração

• finding confirmado → create → remote confirmation;
• ocorrência repetida → update da issue canônica;
• owner em outro repositório;
• fallback sem permissão;
• timeout após mutation;
• 403/404/409/422/429/5xx;
• issue transferida/renomeada/fechada;
• stage report recebe link confirmado;
• crash antes/depois de intent e confirmation;
• outbox parcialmente corrompida.

Sistema/E2E multi-repo

• problema no próprio loop;
• problema em simplicio-mapper;
• problema em simplicio-dev-cli;
• problema em uma skill/plugin;
• problema em tool/provider externo;
• mesmo finding observado por múltiplos agents;
• regressão de issue fechada;
• run offline e posterior recovery;
• COMPLETE bloqueado até todas as issues obrigatórias estarem confirmadas.

Segurança

• token/secret/PII em stdout e stacktrace;
• prompt injection solicitando omitir issue ou trocar owner;
• Markdown/HTML malicioso;
• signed URL;
• path traversal em artifact refs;
• conteúdo de issue tratado como untrusted no re-ingest;
• agente sem permissão tentando suprimir finding.

Performance e resiliência

• 10.000 findings/ocorrências sem perda;
• burst de múltiplos agents;
• rate limit prolongado;
• reinício repetido;
• compactação sem perder evidência/links;
• custo e latência medidos antes/depois.

Critérios de aceite

• Todas as etapas do lifecycle emitem report estruturado, inclusive em erro, cancelamento e crash recuperado.
• Todo problema confirmado gera ou vincula exatamente uma issue canônica.
• Problems em skills, projetos, CLIs, MCPs, hooks, adapters, runtimes, providers e ferramentas estão cobertos.
• Issue é criada no repositório proprietário ou em fallback explícito e rastreável.
• Toda issue derivada contém reprodução, evidência, impacto, plano passo a passo, testes, critérios de aceite e DoD.
• Findings suspeitos recebem issue de investigação sem serem apresentados como fatos confirmados.
• Fingerprint impede duplicatas e preserva ocorrências.
• Regressão reabre a issue correta quando a causa é a mesma.
• Outbox sobrevive a crash/offline/rate limit e confirma o efeito remotamente.
• Nenhum secret, PII, signed URL ou log cru é publicado.
• Stage reports exibem issues/findings e health do outbox.
• COMPLETE é bloqueado enquanto existir finding confirmado in-scope sem issue remotamente confirmada.
• Problemas descobertos depois da entrega revogam o estado terminal e produzem REGRESSED.
• Source/plugin/bundle/wheel permanecem em parity.
• Testes unitários, integração, sistema/E2E, segurança, recovery e performance passam.
• Cada checkbox possui link para teste, receipt, issue sandbox ou evidência reproduzível.

Definition of Done

Executar um cenário sandbox com múltiplos repositórios e múltiplos agents no qual problemas sejam injetados em cada etapa e em pelo menos: código do loop, mapper, dev-cli, uma skill, um adapter e uma ferramenta externa. O sistema deve produzir reports em todas as etapas, criar/vincular uma única issue profunda por problema no owner correto, recuperar após offline/crash sem duplicação, sanitizar conteúdo sensível e impedir COMPLETE até observar remotamente todas as issues obrigatórias.

Dependências e relacionamento

• Extende: [P0][Stage Agents][GitHub Reporting] Reportar cada item, agente e transição do fluxo por comentários idempotentes #433
• Deve reutilizar os stage events/receipts e o reporting idempotente já implementados.
• Não deve reintroduzir heurísticas edit-last, comentários duplicados ou estado baseado apenas em presença de arquivo.

[wesleysimplicio]

Fresh finding — 2026-07-17 — command surface gap

Durante a tentativa de executar o preflight exigido pelo fluxo atualizado, o operador real apresentou dois problemas verificáveis:

Reprodução

No checkout C:\Users\Z0059V7A\m\repos\simplicio-agent:

simplicio-loop preflight --task .orchestrator/loop/goal-all-open-issues.md --repo . --json

Resultado:

simplicio-loop: error: argument command: invalid choice: 'preflight'
choices: install, dashboard, task, plan, run, oracle, status, verify, progress,
resume, tick, batch, cancel, maintenance-deferred, defer-maintenance, deliver,
decide, sync-source, drain, ledger
exit=1

A tentativa de injetar o checkout corrigido do mapper também falhou antes do dispatch porque a camada simplicio shell compact/PowerShell não preservou a atribuição de $env:PYTHONPATH, produzindo um comando mutilado. Isso deixa o caminho de validação dependente de quoting específico e sem receipt.

Impacto

• O contrato operacional exige preflight, mas o CLI instalado não expõe esse subcomando.
• Uma skill atualizada pode instruir um comando que não existe na versão instalada.
• O operador não consegue provar, em uma única chamada, que Runtime, mapper, dev-cli, skills e receipts estão prontos.
• A limitação de empacotamento do mapper (feat: add shared run budget and delta contract #233) ainda pode impedir que o executável global consuma a correção feat: record bounded WorkItem attempt history #232.
• O erro de quoting pode mascarar qual implementação do mapper foi realmente usada.

Plano de correção

1. Definir o contrato canônico do preflight: argumentos, JSON schema, exit codes e gates obrigatórios.
2. Implementar ou expor simplicio-loop preflight na versão pública, ou atualizar a skill para o comando oficialmente suportado sem duplicar lógica.
3. Fazer o preflight validar explicitamente as versões/localizações de simplicio, simplicio-loop, simplicio-mapper e simplicio-dev-cli.
4. Fazer o preflight emitir receipt persistente com fase, versão, source SHA, freshness do mapper, capabilities e blockers.
5. Corrigir o caminho Windows para preservar variáveis de ambiente e comandos com --, paths com espaços e quoting PowerShell.
6. Adicionar testes de processo real para invocation via Runtime passthrough, incluindo erro de comando inexistente e fallback honesto.
7. Cobrir o caso em que o mapper source checkout é usado temporariamente, marcando o resultado como UNVERIFIED| package not published.
8. Integrar o gate ao run para impedir dispatch quando o preflight não tiver receipt válido.

Matriz mínima de testes

• preflight --json bem-sucedido em checkout limpo;
• preflight --json com cada operador ausente;
• versão instalada anterior ao SHA exigido;
• mapper com artefato stale, lock ativo, lock órfão e timeout;
• PowerShell com path contendo espaços;
• Runtime compact passthrough com variáveis de ambiente;
• fallback sem mapper publicado;
• receipt corrompido, ausente e de run anterior;
• exit code distinto para bloqueio, erro de ferramenta e sucesso.

Critérios de aceite adicionais

• Existe um comando/documento canônico que a skill pode chamar para preflight.
• O comando retorna JSON estável e exit code não-zero quando qualquer gate obrigatório falha.
• O receipt informa versão e caminho reais dos operadores chamados.
• O preflight não aceita artefato stale nem mistura source checkout com pacote global sem marcar a procedência.
• A invocação Windows preserva env, paths, argumentos e separadores.
• O run registra issue/link quando um comando documentado não existe.
• Há teste E2E do mesmo comando que será usado pelo próximo run de simplicio-agent.

Evidência relacionada: mapper PR #232 mesclado; release/install follow-up #233; agent issue #151.

[wesleysimplicio]

Implementado via PR #473