Procedência

A procedência é o registro de um item de trabalho: uma tarefa, um plano, uma tarefa de plano ou um pacote de trabalho. Ela responde às perguntas que uma alteração precisa responder muito depois de ser mesclada: de onde veio, quem a solicitou, quem é o proprietário, quem decidiu o quê e por quê, e o que foi entregue.

Coroid cria esse registro a partir do que já acontece conforme o trabalho passa pela Factory: a conversa ou solicitação que o iniciou, os documentos que as pessoas aprovaram, as decisões que tomaram e as pull requests e commits que o entregaram. Você vê o mesmo registro no portal, nas pull requests e nos commits; os agentes que trabalham na tarefa também o leem.

O que a procedência responde?#

• Origem. O que deu início ao trabalho, com um link para ele: uma conversa de chat, uma revisão de Prepare Work, uma solicitação de Novo trabalho, uma issue importada ou por webhook, um hook, uma programação, um cliente MCP, o API, uma descoberta ou relatório, ou um plano ou tarefa pai.
• Solicitante e proprietário. A pessoa que solicitou o trabalho e quem o possui agora. Quando o trabalho chega por meio de uma conta de serviço ou de alguém externo à sua organização, como o autor de uma issue do GitHub, a procedência menciona essa conta ou pessoa. O Coroid nunca preenche um dado cujo valor precise adivinhar.
• Decisões. Aprovações, solicitações de alteração, inícios, paradas, novas tentativas, mesclagens, substituições e mudanças de propriedade, cada uma com quem a tomou, quando e o motivo, se houver.
• Discussão. As mensagens das pessoas que moldaram o trabalho: trechos curtos da conversa de origem e do feedback sobre seus documentos, cada um com seu autor e um link.
• Entrega. As pull requests, commits, vereditos de QA, decisões de Revisão e evidências.

Uma tarefa que pertence a um plano compartilha a origem e o solicitante do plano. Sua procedência também mostra a linhagem: a tarefa, seu plano e pacote de trabalho, e a conversa ou solicitação de onde vieram.

Resumo primeiro#

Toda visualização da procedência abre com um resumo, para que você possa ver rapidamente para que serve o trabalho e quem está por trás dele:

• Intenção: o que o trabalho faz e por quê, em um parágrafo curto. Ele vem da intenção aprovada, senão da especificação aprovada, senão da solicitação original, senão da descrição da tarefa ou plano. Uma linha abaixo indica qual delas foi usada.
• Solicitado por: a pessoa, conta de serviço ou pessoa externa que fez a solicitação.
• Proprietário: quem possui o trabalho agora. É a pessoa para quem foi transferido pela última vez, senão a pessoa à qual a tarefa está atribuída, senão o proprietário da conversa de origem, senão o solicitante.
• Aprovado por: as pessoas que aprovaram sua intenção, especificações e plano de implementação, além do próprio plano, cada uma com a função que exerceu na aprovação.
• Decisões importantes: até cinco das decisões mais recentes tomadas pelas pessoas, com o respectivo motivo para cada uma.

Os aprovadores listados são sempre pessoas. Uma aprovação registrada automaticamente pelo Coroid é excluída da lista; veja Decisões automáticas.

Onde você o vê#

No portal#

Abra uma Tarefa ou um Plano na Factory e expanda a seção de procedência. Abaixo do resumo, você encontrará as seguintes partes:

• Origem: onde o trabalho teve início, com um link para a conversa, solicitação, issue ou relatório.
• Linhagem: o plano e o pacote de trabalho aos quais uma tarefa pertence, quando ela está vinculada a um plano.
• Decisões: ordenadas da mais antiga para a mais recente, cada uma com seu motivo. Um histórico extenso exibe as oito mais recentes, e um clique mostra as demais.
• Discussão: as mensagens que moldaram o trabalho, ordenadas da mais recente para a mais antiga.
• Entrega: pull requests e quem os mesclou, commits, vereditos de QA, revisões e evidências.

Uma versão resumida aparece na aba Detalhes de uma tarefa e na revisão de promoção de um plano, com um link para a procedência completa.

O acesso segue o próprio trabalho. A procedência de uma tarefa requer acesso de leitura ao seu projeto, e a procedência de um plano é visível em toda a sua organização, assim como o plano.

Nos pull requests#

Cada pull request Coroid aberto inclui uma seção de procedência, seja para entregar uma tarefa, um plano ou um pull request de release. Essa seção começa com o mesmo resumo: a intenção, o trabalho, quem solicitou, quem é o proprietário, quem fez as aprovações e as principais decisões. Em seguida vêm a origem e seus links, depois a linhagem, as decisões, a entrega e um link para abrir o trabalho no Coroid.

Coroid preenche as demais seções ao redor: um resumo da alteração, um link para a tarefa e as evidências de revisão, os critérios de aceitação e o status de QA e revisão.

Coroid controla apenas as seções marcadas com comentários ocultos na descrição. Quando atualiza o pull request, por exemplo após retrabalho, ele substitui essas seções e mantém exatamente tudo o que você ou seus revisores escreveram. Se o histórico for muito longo, as decisões mais antigas são removidas primeiro e a seção indica que há mais informações no Coroid.

Um pull request de release lista cada pull request incluído: o que ele entrega, quem solicitou e quem aprovou, na ordem de merge.

Nos commits#

Todo commit feito pelo Coroid termina com trailers que indicam a qual trabalho ele pertence:

Coroid-Task: 3f6e2b1c-7d4a-4c1e-9b2f-0a8d5e6c7b91
Coroid-Plan: 8a41b7c3-25d0-4f6b-a1e9-6c3d2b7f4e05
Coroid-Requested-By: Maya Lindqvist
Coroid-Origin: prepare_work

Dependendo do trabalho, o commit também menciona sua tarefa de plano, pacote de trabalho, execução de agente, patch ou release. O trailer do solicitante contém um nome, nunca um endereço de e-mail.

Coroid é o autor de cada commit que faz. Quando um commit é criado com a conta conectada de uma pessoa, Coroid também é adicionado como coautor:

Co-authored-by: Coroid <ai@coroid.ai>

Coroid também mantém seu próprio mapeamento de cada commit para sua tarefa ou plano. Quando um pull request aberto pelo Coroid é mesclado no GitHub ou GitLab, Coroid registra o commit de merge ou squash que foi aplicado, para que um merge tipo squash não perca o link.

Para agentes#

A ordem de trabalho de cada agente em uma tarefa resume sua procedência: o motivo da existência do trabalho, quem solicitou, quem é o responsável e quais decisões foram tomadas. Quando um agente precisar de mais detalhes, poderá consultar o registro completo, seção por seção.

A especificação continua sendo a referência principal. Quando a procedência e a especificação divergem, o agente segue a especificação e relata o conflito em seu relatório, em vez de escolher silenciosamente. As mensagens e razões escritas por pessoas passam pelo filtro contra injeção de comandos do Coroid antes de serem lidas pelos agentes, e o texto bloqueado pelo filtro não é exibido.

O que nunca vai para seu host Git#

O texto da conversa nunca é escrito em um pull request ou em um commit. Uma pull request contém nomes, funções, decisões, motivos e links. A discussão aparece apenas com o número de mensagens e quem as escreveu, com um link para a conversa em Coroid. Endereços de e-mail nunca são incluídos; as pessoas são identificadas pelo nome.

Apenas links#

Por padrão, a seção de procedência de um pull request inclui o parágrafo de intenção, as principais decisões e os motivos apresentados pelas pessoas. Uma organização pode optar por exibir apenas links. Nesse caso, a seção mostra quem solicitou o trabalho, quem é o proprietário, quem deu aprovação, as decisões e os links para Coroid, omitindo o parágrafo de intenção, as principais decisões e todos os motivos.

Escolha a opção 'apenas links' quando pessoas que não devem ler sua justificativa técnica tiverem acesso ao seu repositório, como em casos de repositórios públicos. Essa configuração se aplica às pull requests que Coroid abre ou atualiza após sua definição. Ainda não há tela de configurações para isso. Contate-nos para alterar a configuração da sua organização para exibir apenas links.

Decisões e seus motivos#

Coroid registra quem tomou cada decisão durante o andamento do trabalho: aprovações de intenção, Especificações e planos, Qualificação, início, interrupção, reinício e conclusão manual do trabalho, merges e force merges, substituições de regras de controle, aprovações de lançamento, alterações no proprietário ou nos participantes de uma conversa, além dos vereditos dos agentes de QA e Revisão e do coordenador.

Quando você aprova e inicia um plano, interrompe uma tarefa ou tenta executar uma tarefa novamente, a confirmação solicita um motivo opcional de até 2.000 caracteres. Ele é salvo junto ao seu nome na seção de procedência do trabalho, e as pull requests o exibem, a menos que sua organização utilize a opção 'apenas links'. Uma frase curta é suficiente. 'Os clientes solicitaram isso antes da campanha de primavera' informa ao próximo leitor mais detalhes do que a simples aprovação. Um force merge já exige um motivo escrito, e ele é registrado da mesma forma.

Decisões automáticas#

Algumas decisões são registradas em nome de alguém, em vez de serem tomadas por essa pessoa. O contrato de entrega de uma tarefa de plano é aprovado automaticamente a partir do plano aprovado, e um plano criado sem associar uma pessoa tem seu criador como representante. A linha do tempo rotula essas decisões como 'Automática', e elas nunca contam como aprovação de uma pessoa.

As decisões tomadas pelos agentes, como vereditos de QA e Revisão e as decisões do coordenador, aparecem sob o nome do agente com o resumo fornecido por ele.

Adicionar contexto a uma tarefa em execução#

É possível informar algo aos agentes enquanto uma tarefa está em execução, sem interrompê-la. Abra a aba Atividade da tarefa e selecione "Adicionar contexto" ao lado da atividade em andamento. Escreva o que os agentes precisam saber, até 2.000 caracteres, e confirme.

• Quando um agente está em execução, ele lerá sua mensagem na próxima rodada de processamento. Um coordenador que estiver aguardando outro agente acordará para lê-la.
• Se nenhum agente estiver em execução, o próximo agente a ser iniciado a lerá.

A mensagem é registrada na procedência da tarefa como uma decisão de "Contexto adicionado", com seu nome. Ela não altera o que a tarefa deve entregar: se sua mensagem entrar em conflito com as especificações, o agente relatará o conflito em vez de escolher silenciosamente. Para mudar o resultado, altere as especificações ou envie a tarefa de volta como retrabalho.

Para adicionar contexto, é necessário ter acesso de escrita ao projeto da tarefa. Tarefas concluídas e canceladas não permitem essa ação.

Rastreie o código até o trabalho que o gerou#

Você pode começar por uma linha de código e encontrar o trabalho que a criou. O portal, os agentes, os clientes MCP e o Git levam você até lá.

Por que isso está aqui?#

Na revisão de código de uma tarefa, cada trecho que afeta linhas existentes tem esse botão. Ele busca os commits que alteraram essas linhas pela última vez no branch de destino e mostra de onde cada um veio:

• Feito por Coroid: a tarefa ou plano, com sua intenção, quem solicitou e aprovou, as principais decisões e um link para a procedência completa.
• Criado fora do Coroid: não há registros de tarefa ou plano que expliquem o motivo da alteração; portanto, é possível ver o autor e a data.

O arquivo adicionado pela alteração não possui linhas anteriores, logo não tem botão.

Com um agente ou cliente MCP#

Os agentes e clientes MCP fazem a mesma pergunta usando uma ferramenta. Ela recebe um arquivo e, se desejar, um intervalo de linhas, além de um branch, tag ou commit. Em seguida, retorna cada intervalo de linhas com o commit que o alterou pela última vez. Para um commit feito pelo Coroid, a ferramenta também retorna a tarefa ou o plano associado e resume sua procedência. Essa ferramenta é chamada de explain_code.

• Agentes: Os agentes Desenvolvedor, Revisor e coordenador da Coroid utilizam esse registro antes de alterar ou excluir código cujo propósito não é claro.
• Clientes MCP: É uma ferramenta de leitura, portanto requer a função de Revisor e este escopo: mcp.read. Ela funciona apenas nos projetos que a conexão consegue alcançar e permite 30 chamadas por minuto.

Com o Git#

Cada commit que o Coroid gera nomeia seu trabalho nos trailers, permitindo que o Git também o localize:

git blame -L 120,120 src/search/alerts.ts   # the commit that last changed line 120
git log -1 <sha>                            # its Coroid-Task or Coroid-Plan trailer

Em seguida, abra essa tarefa ou plano no portal para ler sua procedência:

• Tarefa: https://client.coroid.ai/factory/task:<task id>?panel=provenance
• Plano: https://client.coroid.ai/factory/<plan id>#provenance

Para um commit de merge ou squash, abra o pull request do qual ele provém. Sua seção de procedência contém um link para o Coroid.

Exportar procedência#

O painel possui dois botões de download na parte superior. O formato Markdown baixa a procedência como um documento com o resumo em primeiro lugar. Ele tem a mesma estrutura da seção do pull request, incluindo os motivos e sem o texto das conversas. O JSON baixa o registro completo, incluindo trechos das discussões, para seus próprios registros ou ferramentas. Mantenha o arquivo JSON tão privado quanto a conversa que ele cita.

Origem não registrada#

O Coroid registra a procedência do trabalho criado após a introdução do recurso. Trabalhos mais antigos exibem esta mensagem em vez de uma origem:

Origem não registrada. Este trabalho foi criado antes que o Coroid passasse a registrar a procedência.

Quando o Coroid identifica uma fonte a partir de registros anteriores, como a conversa que gerou um plano ou o relatório por trás dele, o painel a lista como uma fonte conhecida. Decisões já registradas anteriormente, como aprovações de documentos, ainda aparecem; outras podem estar ausentes.

Uma origem rotulada como "Derivada" foi reconstruída a partir de registros anteriores, em vez de ser capturada quando o trabalho foi criado.

Relacionados#

• Tarefas
• Planos
• Revisar e mesclar o resultado
• Assistente de Chat
• Especificações
• Coroid como servidor MCP