Skip to content

[P0][Stage Agents][GitHub Reporting] Reportar cada item, agente e transição do fluxo por comentários idempotentes #433

Closed
#449
Closed
[P0][Stage Agents][GitHub Reporting] Reportar cada item, agente e transição do fluxo por comentários idempotentes#433
#449
Labels
coding-loopThe iterative loop / budget / exit conditionsenhancementNew feature or requestorchestratorOrchestration: DAG, pipeline, worker pool, isolationqualityQuality gates / verificationruntimeRuntime-agnostic core / adapters

Description

@wesleysimplicio
wesleysimplicio
opened on Jul 16, 2026

Parent: #422
Depends on: #423, #424
Integrates with: #425–#432
Extends/supersedes the limited progress-comment scope of: #296, #298–#304, especially #301

Objetivo

Garantir que cada item e cada fluxo relevante do simplicio-loop seja reportado no GitHub por comentários idempotentes, auditáveis e vinculados aos stage receipts, independentemente do runtime que executa a skill.

A execução pode usar agents nativos, processos isolados, workers remotos, CLI, MCP, hooks ou self-paced drive; o protocolo de reporting deve ser o mesmo.

Resultado esperado

Para cada work item deve existir um comentário vivo no GitHub contendo a timeline completa:

discovered
→ claimed
→ intake/planning
→ implementation
→ safety
→ review A/B/C + blast radius
→ delivery/PR/checks/merge
→ feedback/retry/recovery
→ final audit
→ COMPLETE | PARTIAL | BLOCKED | REGRESSED

O comentário não é a autoridade do estado; ele é uma projeção verificável dos events/receipts canônicos.

Gap em relação a #301

#301 implementou comentário único de progresso voltado principalmente a percentuais e entrega, com comportamento fail-open quando GitHub estava indisponível.

O novo contrato precisa cobrir:

  1. todos os agentes e etapas de [P0][Stage Agent][Intake/Planner] Materializar agente de compreensão, orientação e plano profundo por AC #425–[P0][Stage Agent][Completion Auditor] Materializar auditor final independente e completion oracle fail-closed #431;
  2. cada item individual, não apenas o progresso geral do run;
  3. attempt, fence, plan revision, agent identity e evidence refs;
  4. blockers, retries, quarantine, handoff, cancel e regressão;
  5. comentário no PR e na issue/control issue;
  6. outbox durável e confirmação remota;
  7. semantics configurável reporting_required=true;
  8. completion bloqueada enquanto reporting obrigatório estiver pendente;
  9. concorrência de múltiplos agentes sem comentários duplicados;
  10. sanitização e limite de conteúdo.

Superfícies de reporting

Work-item comment

Um comentário por run_id + task_id, identificado por marker invisível:

<!-- simplicio-loop:stage-report:v1 run=<run_id> task=<task_id> -->

O mesmo comentário é atualizado idempotentemente durante todo o lifecycle.

Run/control comment

Um comentário agregado na epic/control issue:

  • itens totais/ativos/blocked/done;
  • lanes e agentes ativos;
  • próxima ação;
  • links para comentários de cada item;
  • reporting outbox pendente;
  • estado final.

Pull request comment/body

  • stage summary e AC coverage;
  • review panel verdicts;
  • checks/merge state;
  • evidence links;
  • referência cruzada ao item e ao run.

Human-action comment

Quando houver decisão humana obrigatória, criar/atualizar um comentário separado com marker estável por approval request. A resposta/approval é vinculada por comment ID, actor e revision.

Eventos que obrigatoriamente geram projeção

Run

  • armed/preflight started/passed/blocked;
  • capability probe e adapter selection;
  • STOP/cancel/cap/handoff;
  • final completion audit.

Item

  • discovered/enqueued;
  • claimed/lease/fence;
  • dependency blocked/unblocked;
  • worktree/branch allocated;
  • item done/quarantined/reopened.

Intake/planning (#425)

  • source observation;
  • planning started;
  • clarification required;
  • plan/AC/impact gate passed ou blocked;
  • plan revision invalidated.

Implementation (#426)

  • agent spawned/ready;
  • implementation started;
  • scoped progress checkpoint;
  • test result;
  • retry/failure;
  • candidate/head produced.

Safety (#428)

  • action classified;
  • secret scan;
  • allow/deny/human gate;
  • approval received/expired/rejected.

Review panel (#427)

  • cada reviewer A/B/C/blast criado;
  • cada verdict e finding count;
  • synthesis;
  • re-review após novo head.

Delivery (#429)

  • composed verification;
  • push/PR intent e confirmation;
  • checks/reviews;
  • merge intent/confirmation;
  • target reachability;
  • source close/reopen.

Feedback/recovery (#430)

  • failure fingerprint;
  • invalidated receipts;
  • retry/replan/repair;
  • quarantine/escalation;
  • regression detected.

Completion auditor (#431)

  • audit started;
  • missing/stale evidence;
  • terminal verdict;
  • completion receipt;
  • terminal revoked/regressed.

Formato do comentário

Cabeçalho:

  • run/item/status;
  • source revision e plan revision;
  • attempt/fence;
  • último update;
  • truth class.

Tabela de stages:

Stage Agent Status Attempt Evidence Updated

AC summary:

AC Status Verified by Receipt/evidence

Seções:

  • blockers;
  • findings;
  • next action;
  • PR/delivery;
  • outbox/reporting health;
  • links para receipts/artifacts, nunca logs crus.

Contrato de eventos e receipts

Criar simplicio.github-stage-report/v1 contendo:

  • event ID e sequence;
  • run/task/work-item/stage/role/agent IDs;
  • attempt/fence/plan/source revision;
  • event type/status/reason code;
  • evidence refs;
  • rendered body hash;
  • target repo/issue/PR IDs;
  • idempotency key;
  • comment marker e remote comment ID;
  • request/response timestamps;
  • remote URL;
  • confirmation state;
  • retry count e next retry;
  • sanitized fields manifest.

O GitHub comment confirmation receipt deve registrar:

  • comment ID/URL;
  • body SHA-256;
  • observed updated_at;
  • target issue/PR identity;
  • marker encontrado uma única vez;
  • request ID quando disponível;
  • source event high-water mark.

Idempotência e concorrência

  1. Buscar comentário pelo marker exato.
  2. Zero comentários encontrados: criar com idempotency record.
  3. Um comentário: atualizar por comment ID.
  4. Mais de um: bloquear/reconciliar, escolher autoridade por persisted comment ID e sinalizar duplicação.
  5. Persistir comment ID antes/depois do efeito via intent/confirmation.
  6. Usar sequence/high-water mark para impedir update antigo sobrescrever novo.
  7. Aplicar compare-and-reconcile quando dois agentes atualizam.
  8. Retry após timeout consulta antes de recriar.
  9. Rate-limit agrega eventos, mas nunca perde transição terminal/blocker/human gate.
  10. Reporting geral e por item usam markers distintos.

Disponibilidade e fail-closed

Reporting opcional

Quando reporting_required=false:

  • eventos entram na outbox;
  • execução pode continuar;
  • status exibe UNVERIFIED reporting_pending;
  • completion receipt não pode alegar que o GitHub foi atualizado.

Reporting obrigatório

Quando o goal ou config exige comentários no GitHub:

  • falha temporária mantém outbox e retries;
  • mutações locais já seguras não precisam ser desfeitas;
  • COMPLETE é bloqueado até confirmation receipt;
  • resultado é PARTIAL/BLOCKED(reporting_pending);
  • ausência de auth/permission é blocker explícito;
  • nunca descartar eventos silenciosamente.

Isso substitui o fail-open absoluto de #301 para execuções que declararem reporting obrigatório.

Plano de implementação

  1. Registrar github_reporting como estágio transversal no manifesto [P0][Stage Agents][Contract] Definir manifesto, lifecycle, identidade e receipts tipados por etapa #423.
  2. Definir schemas de event, projection, intent e confirmation receipt.
  3. Criar renderer puro por item e por run.
  4. Criar target resolver: source issue, control issue e PR.
  5. Implementar marker/idempotency/search/update por ID.
  6. Reutilizar o adapter transacional de feat(github): implementar adapter transacional do ciclo de vida das issues com comentário único e idempotente #285/[P1][Feedback][Entrega] Instrumentar web_verify/video_evidence/pr_evidence, secao de progresso no PR e comentario idempotente de progresso na issue #301, removendo edit-last e heurísticas.
  7. Criar outbox append-only com retry/backoff/jitter e high-water mark.
  8. Implementar reconciler para timeout, duplicate comment e update concorrente.
  9. Instrumentar os lifecycle events de [P0][Stage Agents][Driver] Criar coordinator portátil e adapters para materializar agentes em qualquer runtime #424–[P0][Stage Agent][Completion Auditor] Materializar auditor final independente e completion oracle fail-closed #431.
  10. Adicionar comment confirmation receipt ao stage graph.
  11. Fazer [P0][Stage Agent][Completion Auditor] Materializar auditor final independente e completion oracle fail-closed #431 exigir reporting confirmation quando obrigatório.
  12. Fazer [P0][Stage Agents][Conformance] Certificar agentes concretos em todos os runtimes, bundles e modos de drive #432 certificar reporting em native/command/queue e hook/self-paced.
  13. Sanitizar secrets, PII, signed URLs, headers e raw logs.
  14. Aplicar max body size, truncamento por prioridade e artifact links.
  15. Implementar retention/compaction preservando timeline terminal.
  16. Adicionar status CLI: stage-agents reporting status|flush|reconcile --json.
  17. Atualizar documentação e runbook.
  18. Garantir source/plugin/wheel parity.

Matriz de testes

Unitários

  • marker e idempotency key;
  • renderer determinístico;
  • event ordering/high-water mark;
  • target resolution;
  • body hash;
  • sanitization;
  • truncamento;
  • required/optional semantics;
  • duplicate detection.

Integração com adapter mock

  • create→update do mesmo comentário;
  • 100 eventos resultam em um comentário por item;
  • out-of-order updates;
  • timeout após create/update;
  • response duplicada;
  • rate limit/403/404/5xx;
  • issue transfer/close/reopen;
  • PR e issue simultâneos.

GitHub sandbox E2E

  • dois updates produzem um único comment ID;
  • múltiplos agentes atualizam sem perder evento;
  • cada stage aparece na tabela;
  • blocker e human gate aparecem imediatamente;
  • final audit atualiza terminal;
  • regressão altera COMPLETE para REGRESSED;
  • body SHA e remote observation conferem.

Recovery/fault injection

  • crash antes/depois do intent;
  • crash após efeito e antes da confirmation;
  • outbox corrompida parcialmente;
  • clock skew;
  • network offline e retorno;
  • token removido/restaurado;
  • duplicate coordinator;
  • stale agent tenta sobrescrever comentário novo.

Segurança

  • secret no diff/log/finding;
  • prompt injection tentando mudar marker;
  • malicious Markdown/HTML;
  • signed URL;
  • path/URL externo não permitido;
  • GitHub comment content tratado como untrusted no re-ingest.

Sistema/conformance

  • run com múltiplos itens;
  • task em converge e drain;
  • native/command/queue adapters;
  • hook-bound/self-paced/CLI/MCP;
  • limited slots/waves;
  • STOP/cancel/handoff;
  • item quarantined;
  • final delivery e source close.

Critérios de aceite

Definition of Done

Executar um run sandbox com múltiplos itens e todos os agentes de #425–#431. Para cada item deve existir exatamente um comentário GitHub atualizado ao longo de toda a timeline, mais um comentário agregado do run. Desconectar a rede no meio, reiniciar e recuperar sem duplicar comentários. O auditor final só pode emitir COMPLETE depois que os comentários obrigatórios forem observados remotamente e os body hashes confirmados.

Metadata

Metadata

Assignees

No one assigned

    Labels

    coding-loopThe iterative loop / budget / exit conditionsenhancementNew feature or requestorchestratorOrchestration: DAG, pipeline, worker pool, isolationqualityQuality gates / verificationruntimeRuntime-agnostic core / adapters

    Projects

    Simplicio - Loop
    Status
    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions