Provenance

Provenance is the record of one piece of work: a task, a plan, a plan task or a work package. It answers the questions a change has to answer long after it merged: where did this come from, who asked for it, who owns it, who decided what and why, and what was delivered.

Coroid builds it from what already happens as work moves through the factory: the conversation or request that started it, the documents people approved, the decisions they made, and the pull requests and commits that delivered it. You see the same record in the portal, in pull requests and in commits, and the agents working on the task read it too.

What provenance answers#

• Origin. What started the work, with a link back to it: a chat conversation, a Prepare Work review, a New Work request, an imported or webhooked issue, a hook, a schedule, an MCP client, the API, a finding or report, or a parent plan or task.
• Requester and owner. The person who asked for the work, and who owns it now. When work arrives through a service account or from someone outside your organisation, such as the author of a GitHub issue, the provenance names that account or person. Coroid never fills in a member it would have to guess.
• Decisions. Approvals, change requests, starts, stops, retries, merges, overrides and ownership changes, each with who made it, when, and the reason when one was given.
• Discussion. The messages from people that shaped the work: short excerpts from the conversation it came from and from feedback on its documents, each with its author and a link.
• Delivery. The pull requests, commits, QA verdicts, review decisions and evidence.

A task that belongs to a plan shares the plan's origin and requester. Its provenance also shows the lineage: the task, its plan and work package, and the conversation or request they came from.

Summary first#

Every view of the provenance opens with a summary, so you can see at a glance what the work is for and who stands behind it:

• Intent: what the work does and why, in a short paragraph. It comes from the approved intent, else the approved specification, else the original request, else the task or plan description. A line under it says which.
• Requested by: the person, service account or outside person who asked.
• Owner: who owns the work now. That is the person it was last transferred to, else the person the task is assigned to, else the owner of the conversation it came from, else the requester.
• Approved by: the people who approved its intent, specification and implementation plan, and the plan itself, each with the role they approved in.
• Key decisions: up to five of the latest decisions people made with a reason, each with that reason.

The approvers listed are always people. An approval that Coroid recorded automatically is left out; see Automatic decisions.

Where you see it#

In the portal#

Open a task or a plan in the Factory and expand its Provenance section. Below the summary you find these parts:

• Origin: where the work came from, with a link back to the conversation, request, issue or report.
• Lineage: the plan and work package a task belongs to, when it belongs to a plan.
• Decisions: oldest first, each with its reason. A long history shows the latest eight, and one click shows the rest.
• Discussion: the messages that shaped the work, newest first.
• Delivery: pull requests and who merged them, commits, QA verdicts, reviews and evidence.

A compact version appears on the Details tab of a task and in the promotion review of a plan, with a link to the full provenance.

Access follows the work itself. A task's provenance needs read access to its project, and a plan's provenance is visible across your organisation, like the plan.

In pull requests#

Every pull request Coroid opens carries a provenance section, whether it delivers a task, a plan or a release. The section opens with the same summary: the intent, the work, who asked for it, who owns it, who approved it and the key decisions. The origin and its links follow, then the lineage, the decisions, the delivery and a link that opens the work in Coroid.

Coroid writes its other sections around it: a summary of the change, a link to the task and its review evidence, the acceptance criteria, and the QA and review status.

Coroid owns only the sections it marks with hidden comments in the description. When it updates the pull request, after rework for example, it replaces those sections and keeps everything else you or your reviewers wrote exactly as it was. When a long history does not fit, the oldest decisions give way first and the section says that more is in Coroid.

A release pull request lists each bundled pull request instead: what it delivers, who asked for it and who approved it, in merge order.

In commits#

Every commit Coroid makes ends with trailers that name the work it belongs to:

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

Depending on the work, a commit also names its plan task, work package, agent run, patch or release. The requester trailer holds a name, never an email address.

Coroid is the committer of every commit it makes. When a commit is authored with a person's connected account, Coroid also adds itself as co-author:

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

Coroid also keeps its own map from each commit to its task or plan. When a pull request Coroid opened is merged in GitHub or GitLab, Coroid records the merge or squash commit that landed, so a squash merge does not lose the link.

For agents#

The work order of each agent on a task summarises its provenance: why the work exists, who asked for it, who owns it and what was decided. When an agent needs more, it can read the full record, one section at a time.

The specification still governs. When the provenance and the specification disagree, an agent follows the specification and names the conflict in its report instead of choosing silently. Messages and reasons written by people pass Coroid's prompt-injection filter before an agent reads them, and text the filter flags is withheld.

What never goes to your git host#

Conversation text is never written to a pull request or a commit. A pull request carries names, roles, decisions, reasons and links. The discussion appears only as the number of messages and who wrote them, with a link to the conversation in Coroid. Email addresses are never written; people appear by name.

Links only#

By default, the provenance section of a pull request includes the intent paragraph, the key decisions and the reasons people gave. An organisation can choose links only instead. The section then keeps who asked, who owns the work, who approved it, the decisions and the links back to Coroid, and leaves out the intent paragraph, the key decisions and every reason.

Choose links only when people who should not read your product reasoning can see your repository, for example when it is public. The choice applies to pull requests Coroid opens or updates after you make it. It has no settings screen yet. Contact us to switch your organisation to links only.

Decisions and their reasons#

Coroid records who decided what as the work moves: approvals of the intent, specification and plan, Qualification, starting, stopping, retrying and completing work by hand, merges and force merges, gate overrides, release approvals, changes to who owns or takes part in a conversation, and the verdicts of the QA and Reviewer agents and the Coordinator.

When you approve and start a plan, start a plan, stop a task or try a task again, the confirmation asks for an optional reason of up to 2,000 characters. It is saved with your name in the work's provenance, and pull requests show it unless your organisation uses links only. One sentence is enough. "Customers asked for this before the spring campaign" tells the next reader more than the approval alone. A force merge already needs a written reason, and it is recorded the same way.

Automatic decisions#

Some decisions are recorded on someone's behalf rather than made by them. A plan task's delivery contract is approved automatically from the approved plan, and a plan approved without a person has its creator stand in. The timeline labels these decisions "Automatic", and they never count as a person's approval.

Decisions made by agents, such as QA and review verdicts and the Coordinator's decisions, appear under the agent's name with the summary it gave.

Add context to a running task#

You can tell the agents something while a task runs, without stopping it. Open the Activity tab of the task and choose "Add context" next to the live activity. Write what the agents should know, up to 2,000 characters, and confirm.

• When an agent is running, it reads your message on its next turn. A Coordinator that is waiting for another agent wakes up to read it.
• When no agent is running, the next agent to start reads it.

The message is recorded in the task's provenance as a "Context added" decision, with your name. It does not change what the task must deliver: if your message conflicts with the specification, the agent reports the conflict instead of choosing silently. To change the outcome, change the specification or send the task back as rework.

Adding context needs write access to the task's project. Completed and cancelled tasks do not offer it.

Trace code back to its work#

You can start from a line of code and find the work that put it there. The portal, agents, MCP clients and git all lead you there.

Why is this here?#

In the code review of a task, each hunk that touches existing lines has this button. It looks up the commits that last changed those lines on the target branch and shows what each one came from:

• Made by Coroid: the task or plan, with its intent, who requested and approved it, the key decisions and a link to the full provenance.
• Made outside Coroid: no task or plan records why the change was made, so you see the author and the date.

A file that the change adds has no earlier lines, so it has no button.

With an agent or MCP client#

Agents and MCP clients ask the same question with a tool. It takes a file and, if you want, a line range and a branch, tag or commit. It returns each line range with the commit that last changed it. For a commit Coroid made, it also returns the task or plan behind it and summarises its provenance. The tool is called explain_code.

• Agents: Coroid's Developer, Reviewer and Coordinator agents use it before they change or delete code whose purpose is unclear.
• MCP clients: it is a read tool, so it needs the Reviewer role and this scope: mcp.read. It works only in the projects the connection can reach and allows 30 calls a minute.

With git#

Every commit Coroid makes names its work in its trailers, so git gets you there too:

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

Then open that task or plan in the portal to read its provenance:

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

For a merge or squash commit, open the pull request it came from. Its provenance section links back to Coroid.

Export provenance#

The panel has two download buttons at the top. Markdown downloads the provenance as a summary-first document. It has the same form as the pull request section, with the reasons and without conversation text. JSON downloads the complete record, including the discussion excerpts, for your own records or tools. Keep the JSON file as private as the conversation it quotes.

Origin not recorded#

Coroid records provenance for work created after the feature was introduced. Older work shows this message instead of an origin:

Origin not recorded. This work was created before Coroid recorded provenance.

Where Coroid knows a source from earlier records, such as the conversation a plan came from or the report behind it, the panel lists it as a known source. Decisions that were already recorded before then, such as approvals of documents, still appear; others may be missing.

An origin labelled "Derived" was reconstructed from earlier records rather than captured when the work was created.

Related#

• Tasks
• Plans
• Review and merge the result
• Chat assistant
• Specifications
• Coroid as an MCP server