Sinais do Agente

Emita sinais estruturados de uma estação de trabalho para o operador ou outras estações.

Quando usar

• Uma estação de trabalho precisa de atenção do operador (mãos para cima, bloqueado)
• O trabalho está completo e pronto para revisão (concluído)
• Progresso significativo que vale a pena notar (ponto de controle)
• Duas estações de trabalho discordam e não conseguem resolver (mãos para cima)
• O TA está relatando a qualidade da coordenação (parceria)

Tipos de sinal

hands-up

Duas estações de trabalho discordam e não conseguem resolver com base em fatos externos. Este é o sistema funcionando — o operador lê onde as estações de trabalho discordam, não onde elas demonstram confiança.

blocked

Uma estação de trabalho não pode prosseguir sem entrada — acesso faltando, escopo ambíguo, precisa de uma decisão que só o operador pode tomar.

done

O trabalho está completo e pronto para revisão. Artefatos estão na bancada.

checkpoint

Progresso significativo que vale a pena o operador saber, mas o trabalho continua. Não bloqueado, não concluído — apenas um marcador.

partnership

Usado pelo TA (coordenador da sala) para relatar a qualidade da coordenação. Pontuações de autoavaliação refletem a coordenação, não a precisão do código:

• intenção — entendeu o que o operador precisava
• confiança — o trabalho certo foi para as estações de trabalho certas
• precisão — o trabalho despachado produziu o resultado certo
• completude — nada ficou para trás

Como emitir

1. Escreva um arquivo JSON de sinal para .signals/

Esta é a saída principal — é o que o painel lê. Crie desks/<desk-name>/.signals/<timestamp>.json:

{
  "signal_type": "execution",
  "subtype": "checkpoint",
  "timestamp": "2026-07-19T21:30:00Z",
  "run_id": "<optional; set to pair this with an outcome signal>",
  "agent_name": "<desk-name>",
  "self_assessment": {
    "intent": 4,
    "confidence": 5,
    "accuracy": 4,
    "completeness": 3
  },
  "patterns": {
    "what_worked": "description of what went well",
    "what_was_hard": "description of challenges",
    "skill_gap": "areas for improvement"
  },
  "escalation": {
    "reason": null,
    "blocked_on": null,
    "recommendation": null
  }
}

Mapeamento de tipo de sinal

O campo subtype preserva o estado específico do sinal para consumidores do painel. signal_type controla a prioridade de ordenação (escalonamento → topo).

Nota: A extensão de tela do painel de sinais lê subtype quando presente e recorre a signal_type para exibição. Se estiver consumindo sinais em suas próprias ferramentas, prefira subtype para o estado específico.

Ordenação: inclua um timestamp (ISO 8601 UTC). O painel ordena os sinais por ele e recorre ao mtime do arquivo apenas quando ele está ausente — um clone/checkout git redefine os mtimes, então o mtime sozinho não é um relógio confiável.

2. Anote o sinal no diário

Também anexe um marcador curto ao diário da estação de trabalho para persistência:

## <date> — [signal:<type>] <summary>
- <key details>

A nota do diário é o marcador de trilha. O arquivo JSON é o sinal legível por máquina.

Sinais de resultado (calibração)

O painel de sinais pode emparelhar a autoavaliação de uma estação de trabalho com um resultado — uma classificação independente do resultado realizado — e mostrar a lacuna de honestidade (o quão longe a confiança da estação de trabalho estava da qualidade entregue). Sinais de resultado são opcionais e geralmente são emitidos por um revisor/avaliador, não pela estação de trabalho em si.

Escreva-os no mesmo diretório .signals/:

{
  "signal_type": "outcome",
  "run_id": "<same run_id as the signal it rates>",
  "agent_name": "<reviewer name>",
  "quality_rating": 4,
  "effort_to_merge": "minimal",
  "issues_found": ["optional short strings"],
  "timestamp": "2026-07-19T22:00:00Z"
}

• run_id correlaciona um resultado com o sinal de execução/parceria que ele avalia — defina o mesmo run_id em ambos. Se estiver ausente, o painel recorre ao resultado mais próximo emitido logo após o último sinal.
• quality_rating (0–5) é a qualidade realizada; o painel compara-a com a confidence autoavaliada da estação de trabalho para calcular a lacuna de honestidade.
• effort_to_merge — "minimal", "moderate", ou "significant".
• issues_found — array opcional de strings curtas.

Princípios

…