Beviskedja

Beviskedjan är dokumentationen för ett enskilt arbete: en uppgift, en plan, en planuppgift eller ett arbetspaket. Den besvarar frågor som en ändring behöver kunna besvara långt efter att den har mergats: var kom den ifrån, vem begärde den, vem äger den, vem fattade vilka beslut och varför, och vad levererades.

Coroid bygger upp den utifrån det som redan sker när arbetet går genom mjukvarufabriken: konversationen eller förfrågan som startade arbetet, dokumenten som godkändes, besluten som fattades samt pull requests och commits som levererade det. Samma dokumentation visas i portalen, i pull requests och i commits, och agenterna som arbetar med uppgiften läser den också.

Vad beviskedjan visar#

• Ursprung. Vad som startade arbetet, med en länk tillbaka till källan: en chattkonversation, en granskning av Förbered arbete, en förfrågan via Nytt arbete, ett importerat ärende eller ett ärende från en webhook, en hook, ett schema, en MCP-klient, API, ett fynd eller en rapport, eller en överordnad plan eller uppgift.
• Beställare och ägare. Personen som begärde arbetet och vem som äger det nu. När arbetet kommer via ett tjänstekonto eller från någon utanför din organisation, till exempel den som skapat ett GitHub-ärende, anges det kontot eller den personen i beviskedjan. Coroid gissar aldrig vilken medlem det gäller.
• Beslut. Godkännanden, ändringsförfrågningar, starter, stopp, nya försök, merges, åsidosättningar och ägarbyten, med uppgift om vem som gjorde vad, när och varför, om en orsak angavs.
• Diskussion. Meddelanden från personer som formade arbetet: korta utdrag ur konversationen som arbetet kom från och ur feedback på dokumenten, med avsändare och länk för varje utdrag.
• Leverans. Pull requests, commits, QA-bedömningar, granskningsbeslut och underlag.

En uppgift som ingår i en plan delar planens ursprung och beställare. Beviskedjan visar också sambanden: uppgiften, planen och arbetspaketet samt konversationen eller förfrågan de kom från.

Börja med sammanfattningen#

Varje vy av beviskedjan inleds med en sammanfattning, så att du snabbt ser vad arbetet syftar till och vem som står bakom det:

• Syfte: vad arbetet gör och varför, i ett kort stycke. Texten hämtas i första hand från det godkända syftet, annars från den godkända specifikationen, annars från den ursprungliga förfrågan och i sista hand från uppgifts- eller planbeskrivningen. En rad under texten anger källan.
• Begärd av: personen, tjänstekontot eller personen utanför organisationen som begärde arbetet.
• Ägare: vem som äger arbetet nu. Det är personen som arbetet senast överfördes till, annars personen som uppgiften är tilldelad, annars ägaren till konversationen som arbetet kom från och i sista hand beställaren.
• Godkänt av: personerna som godkände syftet, specifikationen och implementeringsplanen samt själva planen, med uppgift om vilken roll de godkände i.
• Viktiga beslut: upp till fem av de senaste beslut som personer fattat med en angiven orsak, med respektive orsak.

De som anges som godkännare är alltid personer. Godkännanden som Coroid registrerat automatiskt utelämnas; se Automatiska beslut.

Var du hittar det#

I portalen#

Öppna en uppgift eller en plan i Mjukvarufabrik och expandera avsnittet beviskedja. Under sammanfattningen hittar du följande delar:

• Ursprung: var arbetet kom ifrån, med en länk tillbaka till konversationen, förfrågan, ärendet eller rapporten.
• Härledning: planen och arbetspaketet som en uppgift ingår i, när den ingår i en plan.
• Beslut: äldst först, med en motivering för varje. En lång historik visar de senaste åtta, och med ett klick visas resten.
• Diskussion: meddelandena som formade arbetet, nyast först.
• Leverans: pull requests och vem som mergade dem, commits, QA-bedömningar, granskningar och bevis.

En kompakt version visas på fliken Detaljer för en uppgift och i granskningssteget för att marknadsföra en plan, med en länk till hela beviskedjan.

Åtkomsten följer själva arbetet. För att läsa en uppgifts beviskedja behöver du läsbehörighet till projektet. En plans beviskedja är synlig i hela organisationen, precis som planen.

I pull requests#

Varje pull request Coroid öppnar innehåller ett avsnitt om beviskedjan, oavsett om det levererar en uppgift, en plan eller en release. Avsnittet inleds med samma sammanfattning: avsikten, arbetet, vem som efterfrågade det, vem som äger det, vem som godkände det och de viktigaste besluten. Därefter följer ursprunget och länkarna till det, sedan härledningen, besluten, leveransen och en länk som öppnar arbetet i Coroid.

Coroid skriver sina övriga avsnitt runt det: en sammanfattning av ändringen, en länk till uppgiften och dess granskningsunderlag, acceptanskriterierna samt status för QA och granskning.

Coroid ansvarar bara för de avsnitt som markeras med dolda kommentarer i beskrivningen. När systemet uppdaterar pull request, till exempel efter omarbete, ersätter det de avsnitten och lämnar allt annat som du eller dina granskare skrev exakt som det var. Om en lång historik inte får plats tas de äldsta besluten bort först, och avsnittet anger att mer finns i Coroid.

En release-pull request listar i stället varje inkluderad pull request: vad den levererar, vem som efterfrågade den och vem som godkände den, i merge-ordning.

I commits#

Varje commit som Coroid skapar avslutas med trailers som anger vilket arbete den hör till:

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

Beroende på arbetet anger en commit också sin plantuppgift, sitt arbetspaket, sin agentkörning, patch eller release. Beställarens trailer innehåller ett namn, aldrig en e-postadress.

Coroid är committer för varje commit det skapar. När en commit skapas med en persons anslutna konto lägger Coroid också till sig självt som medförfattare:

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

Coroid har också en egen koppling från varje commit till dess uppgift eller plan. När en pull request som Coroid öppnat mergas i GitHub eller GitLab, registrerar Coroid merge- eller squash-commiten som lades till, så att en squash-merge inte bryter länken.

För agenter#

Arbetsordern för varje agent i en uppgift sammanfattar dess beviskedja: varför arbetet finns, vem som begärde det, vem som ansvarar för det och vad som beslutades. När en agent behöver mer information kan den läsa hela posten, ett avsnitt i taget.

Specifikationen gäller fortfarande. Om beviskedjan och specifikationen inte stämmer överens följer en agent specifikationen och nämner konflikten i sin rapport i stället för att välja i tysthet. Meddelanden och motiveringar som skrivits av människor passerar Coroids filter mot promptinjektion innan en agent läser dem, och text som filtret flaggar undanhålls.

Det här skickas aldrig till din git-värd#

Konversationstext skrivs aldrig till en pull request eller en commit. En pull request innehåller namn, roller, beslut, motiveringar och länkar. Diskussionen visas bara som antal meddelanden och vem som skrev dem, med en länk till konversationen i Coroid. E-postadresser skrivs aldrig ut; personer visas med namn.

Endast länkar#

Som standard innehåller avsnittet om beviskedja i en pull request stycket om avsikten, de viktigaste besluten och motiveringarna. En organisation kan i stället välja att bara visa länkar. Då innehåller avsnittet fortfarande vem som bad om arbetet, vem som äger det, vem som godkände det, besluten och länkarna tillbaka till Coroid, men utelämnar stycket om avsikten, de viktigaste besluten och alla motiveringar.

Välj att bara visa länkar om personer som inte bör läsa era resonemang om produkten kan se ert repo, till exempel om det är offentligt. Valet gäller pull requests som Coroid öppnar eller uppdaterar efter att du har gjort ändringen. Det finns ännu ingen inställningssida för detta. Kontakta oss om du vill att vi ändrar organisationen så att den bara visar länkar.

Beslut och motiveringar#

Coroid dokumenterar vem som fattade vilket beslut medan arbetet fortskrider: godkännanden av avsikten, specifikationen och planen, Qualification, att starta, stoppa, försöka igen och slutföra arbete manuellt, merges och force merges, åsidosättningar av grindar, releasegodkännanden, ändringar av vem som äger eller deltar i en konversation samt utlåtanden från QA- och Reviewer-agenterna och samordnaren.

När du godkänner och startar en plan, startar en plan, stoppar en uppgift eller försöker igen, frågar bekräftelsen efter en valfri motivering på upp till 2 000 tecken. Den sparas med ditt namn i arbetets beviskedja och visas i pull requests, såvida organisationen inte bara visar länkar. En mening räcker. ”Kunderna bad om detta inför vårkampanjen” säger nästa läsare mer än bara godkännandet. En force merge kräver redan en skriftlig motivering, som dokumenteras på samma sätt.

Automatiska beslut#

Vissa beslut dokumenteras på någons vägnar i stället för att fattas av personen själv. Leveranskontraktet för en planuppgift godkänns automatiskt utifrån den godkända planen, och om en plan godkänns utan en person träder dess skapare in i den personens ställe. I tidslinjen märks dessa beslut som ”Automatiskt”, och de räknas aldrig som en persons godkännande.

Beslut som fattas av agenter, till exempel QA- och granskningsutlåtanden och samordnarens beslut, visas under agentens namn tillsammans med sammanfattningen som den gav.

Lägg till kontext i en pågående uppgift#

Du kan ge agenterna information medan en uppgift körs, utan att stoppa den. Öppna fliken Aktivitet för uppgiften och välj ”Lägg till kontext” bredvid den pågående aktiviteten. Skriv vad agenterna behöver veta, upp till 2 000 tecken, och bekräfta.

• När en agent kör läser den ditt meddelande vid nästa tur. En samordnare som väntar på en annan agent vaknar för att läsa det.
• Om ingen agent kör läser nästa agent som startar meddelandet.

Meddelandet dokumenteras i uppgiftens beviskedja som ett beslut av typen ”Kontext tillagd”, tillsammans med ditt namn. Det ändrar inte vad uppgiften ska leverera: om meddelandet står i konflikt med specifikationen rapporterar agenten konflikten i stället för att välja i tysthet. Om du vill ändra resultatet ändrar du specifikationen eller skickar tillbaka uppgiften för omarbete.

Du behöver skrivbehörighet till uppgiftens projekt för att lägga till kontext. Funktionen är inte tillgänglig för slutförda eller avbrutna uppgifter.

Spåra kod tillbaka till arbetet#

Du kan börja med en kodrad och hitta arbetet som skapade den. Portalen, agenter, MCP-klienter och Git leder dig alla dit.

Varför finns det här?#

I kodgranskningen av en uppgift har varje ändringsblock som berör befintliga rader den här knappen. Den letar upp de commits som senast ändrade raderna på målbranchen och visar vad varje commit kom från:

• Skapad av Coroid: uppgiften eller planen, med avsikten, vem som begärde och godkände den, de viktigaste besluten och en länk till hela beviskedjan.
• Skapad utanför Coroid: ingen uppgift eller plan dokumenterar varför ändringen gjordes, så du ser upphovspersonen och datumet.

En fil som läggs till i ändringen har inga tidigare rader och därför ingen knapp.

Med en agent eller MCP-klient#

Agenter och MCP-klienter ställer samma fråga med ett verktyg. Det tar en fil och, om du vill, ett radintervall och en branch, tagg eller commit. Det returnerar varje radintervall tillsammans med den commit som senast ändrade det. För en commit som Coroid har gjort returnerar det också uppgiften eller planen bakom den och sammanfattar dess beviskedja. Verktyget heter explain_code.

• Agenter: Coroids Developer-, Reviewer- och samordnare-agenter använder den innan de ändrar eller tar bort kod vars syfte är oklart.
• MCP-klienter: det är ett läsverktyg, så det kräver rollen Reviewer och det här omfånget: mcp.read. Det fungerar bara i projekt som anslutningen har åtkomst till och tillåter 30 anrop per minut.

Med git#

Varje commit som Coroid skapar anger vilket arbete den hör till i sina trailers, så du hittar det även med git:

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

Öppna sedan uppgiften eller planen i portalen för att läsa dess beviskedja:

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

Öppna den pull request som en merge- eller squash-commit kommer från. I avsnittet om beviskedja finns en länk tillbaka till Coroid.

Exportera beviskedjan#

Panelen har två nedladdningsknappar högst upp. Markdown laddar ned beviskedjan som ett dokument med sammanfattningen först. Det har samma format som avsnittet pull request, med motiveringarna men utan samtalstext. JSON laddar ned hela posten, inklusive utdrag ur diskussionen, så att du kan spara den eller använda den i verktyg. Förvara JSON-filen lika privat som samtalet den citerar.

Ursprung inte registrerat#

Coroid registrerar beviskedja för arbete som skapats efter att funktionen infördes. Äldre arbete visar det här meddelandet i stället för ett ursprung:

Ursprung inte registrerat. Det här arbetet skapades innan Coroid började registrera beviskedja.

När Coroid känner till en källa från tidigare poster, till exempel samtalet som en plan härrör från eller rapporten bakom den, visas den som en känd källa i panelen. Beslut som redan hade registrerats, till exempel godkännanden av dokument, visas fortfarande; andra kan saknas.

Ett ursprung med etiketten "Härlett" har återskapats utifrån tidigare poster i stället för att registreras när arbetet skapades.

Relaterat#

• Uppgifter
• Planer
• Granska och slå samman resultatet
• Chattassistent
• Specifikationer
• Coroid som MCP-server