Skip to content

docs(discussions): adopt the round template in the AI model provenance discussion #2487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
josecelano merged 6 commits into from
Oct 8, 2026
Merged

docs(discussions): adopt the round template in the AI model provenance discussion #2487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b0f587a
docs(discussions): adopt the round template in the AI model provenanc…
josecelano Oct 8, 2026
2785635
docs(discussions): state that each provenance topic gained an attribu…
josecelano Oct 8, 2026
f70c403
docs(discussions): link the first mention of PR #2467 in the provenan…
josecelano Oct 8, 2026
149a174
docs(pr-reviews): add the PR #2487 review audit
josecelano Oct 8, 2026
f8f88b7
docs(pr-reviews): copy the Status Values block verbatim in the PR #24…
josecelano Oct 8, 2026
c98d418
docs(pr-reviews): record da2ce7 round-1 approval and F3 on #2487
josecelano Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 119 additions & 40 deletions ...aul-guardrails-and-automation/20261007-ai-model-provenance-in-commits/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,39 @@ semantic-links:
- .github/skills/dev/git-workflow/commit-changes/SKILL.md
- .github/agents/committer.agent.md
- docs/adrs/20260821172000_establish_ai_agent_context_capability_and_portability_governance.md
- docs/discussions/AGENTS.md
- docs/templates/DISCUSSION.md
---

<!-- cspell:ignore Deployers -->

# AI Model Provenance in Commits

| Field | Value |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status | Draft for review in the pull request that adds it |
| Started | 2026-10-07 |
| Participants | Jose Celano (the concern and the three purposes: tracking, analytics, legal); AI assistant using the Copilot SDK in VS Code, model `claude-opus-5.5` (research and draft) |
| Reviewer | Cameron (`da2ce7`), assignee of EPIC #2003 |
| Informs | EPIC #2003 - Overhaul: Automation Tools and AI Agent Guardrails |
| Scope | Aspect 2 (the commit-metadata contract and its format gate) and aspect 3 (the models an orchestration routes work to) of [Goals and Boundaries](../20261003-goals-and-boundaries/README.md): how a commit records which AI models were involved in its changes |
| Field | Value |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status | Open for rounds |
| Started | 2026-10-07 |
| Opened by | Jose Celano (`josecelano`), who raised the concern and its three purposes (tracking, analytics, legal) |
| Decision owner | Cameron (`da2ce7`), assignee of EPIC #2003 |
| Informs | EPIC #2003 - Overhaul: Automation Tools and AI Agent Guardrails |
| Scope | Aspect 2 (the commit-metadata contract and its format gate) and aspect 3 (the models an orchestration routes work to) of [Goals and Boundaries](../20261003-goals-and-boundaries/README.md): how a commit records which AI models were involved in its changes |
| AI assistance | AI assistant using the Copilot SDK in VS Code, model `claude-opus-5.5` (research and draft) |

## Why This Discussion
## Context

This discussion was opened in [PR #2467](https://github.com/torrust/torrust-tracker/pull/2467) with
a single-PR structure. It adopted the [discussion template](../../../templates/DISCUSSION.md) in a
round by its opening author, under the round rules in
[`docs/discussions/AGENTS.md`](../../AGENTS.md). The context below is unchanged; the open questions
moved into [Topics](#topics) without changes to their words, and each topic gained the template's
"Added by" attribution.

Cameron (`da2ce7`) posted a draft position on these questions as a pull-request comment on
PR #2467: <https://github.com/torrust/torrust-tracker/pull/2467#issuecomment-6035743101>. Its Part
C answers the topics: C1 (Q1), C2 (Q2), C3 (Q3 and Q4), C4 (Q5 and Q6), C5 (Q7), C6 (Q8), and C7
(Q9). Under the round rules it is linked here, not copied, until he adds it in his own round.

### Why This Discussion

On 2026-10-06, while preparing the spec-only PR #2461 for issue #2458, an AI agent running in the
Copilot SDK for VS Code added this trailer to three commits:
Expand All @@ -45,7 +62,7 @@ that the owner of EPIC #2003 can decide before anything is implemented.
Nothing here changes a specification or a rule. A conclusion takes effect only when the owner of
EPIC #2003 records it.

## Why the Default Trailer Is Only Half Useful
### Why the Default Trailer Is Only Half Useful

1. **It records who made the commit, not who wrote the changes.** The harness adds the trailer
whenever the agent runs `git commit`. A commit made by an agent can contain changes a human
Expand All @@ -63,15 +80,15 @@ EPIC #2003 records it.
5. **It displays the bot as a co-author.** GitHub shows `Co-authored-by` identities as commit
co-authors. That reads as shared authorship and accountability, which an AI model cannot hold.

## What the Project Wants from Attribution
### What the Project Wants from Attribution

- **Tracking:** know, for any change, which models were involved and in what role.
- **Analytics:** compare models with review findings, regressions, and rework. For example: which
model's changes needed the most review fixes?
- **Legal and compliance readiness:** keep an auditable provenance record of AI involvement. The
EU AI Act transparency rules are the main reason to ask this now (see below).

## Precedent in Other Projects
### Precedent in Other Projects

Checked on 2026-10-06 on the projects' own pages.

Expand All @@ -94,7 +111,7 @@ Both projects use `Assisted-by`, not `Co-authored-by`, and both keep a human acc
requires a precise model identifier or more than one model per commit. The purposes above would
take this project further than both.

## EU AI Act
### EU AI Act

This section needs legal review and is not legal advice.

Expand All @@ -113,7 +130,7 @@ Whether an open-source project that commits AI-assisted code has any obligation
established**. The project should not claim compliance. It can record the question for legal input
and design provenance metadata that would support compliance if it turns out to be needed.

## Options
### Options

| ID | Option | Pros | Cons |
| --- | -------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- |
Expand All @@ -125,7 +142,7 @@ and design provenance metadata that would support compliance if it turns out to
Commit trailers stay with the code after merge, because this repository does not squash. That is
the main argument against O2.

## Draft Conclusions
### Draft Conclusions

These are the drafting agent's proposals, not decisions.

Expand All @@ -143,30 +160,7 @@ These are the drafting agent's proposals, not decisions.
5. **Add an interim rule now.** Until the decision is recorded, `AGENTS.md` tells agents not to add
provider-default AI trailers.

## Open Questions for the Reviewer

1. **Granularity:** should provenance live in commit trailers, in the PR body, in issue-local
evidence, or in a combination?
2. **Which models count:** only models whose output is in the diff, or also models that explored,
reviewed, or planned? If reviewers count, they need a separate key so they are not confused
with authors.
3. **Identifier format:** is `<harness>:<vendor>/<model-id>` acceptable, and how should unknown
versions be recorded?
4. **Trailer key:** `Assisted-by`, for compatibility with the kernel and Fedora, or a
project-specific key that adds the role, such as `AI-Model:` or `Generated-by:`?
5. **Source of truth:** the harness knows which models ran, through model-switch notices, subagent
configuration, and session logs. Who is responsible for collecting the list: the agent, the
harness, or the human committer?
6. **Human edits and rewrites:** how is the list kept correct when a human edits AI output, when
commits are reworded or rebased, or when changes move between commits?
7. **Enforcement:** document the rule only, or also validate the trailer format in a `commit-msg`
check? A tool can check the format of a declared trailer. It cannot check whether a declaration
is complete.
8. **Interim rule:** should `AGENTS.md` forbid provider-default AI trailers before the decision?
9. **Legal input:** who reviews the EU AI Act question, and does the answer change the required
level of detail?

## Follow-up Work if Accepted
### Follow-up Work if Accepted

An issue specification, created after the outcome is recorded, carries the decision:

Expand All @@ -185,6 +179,91 @@ An issue specification, created after the outcome is recorded, carries the decis
Rewriting historical commits, giving legal advice, and changing the GPG-signing policy are out of
scope.

## Topics

### Q1 - Granularity

Should provenance live in commit trailers, in the PR body, in issue-local evidence, or in a
combination? Added by Jose Celano.
Comment thread
josecelano marked this conversation as resolved.

#### Positions

No positions yet.

### Q2 - Which models count

Only models whose output is in the diff, or also models that explored, reviewed, or planned? If
reviewers count, they need a separate key so they are not confused with authors. Added by Jose
Celano.

#### Positions

No positions yet.

### Q3 - Identifier format

Is `<harness>:<vendor>/<model-id>` acceptable, and how should unknown versions be recorded? Added by
Jose Celano.

#### Positions

No positions yet.

### Q4 - Trailer key

`Assisted-by`, for compatibility with the kernel and Fedora, or a project-specific key that adds the
role, such as `AI-Model:` or `Generated-by:`? Added by Jose Celano.

#### Positions

No positions yet.

### Q5 - Source of truth

The harness knows which models ran, through model-switch notices, subagent configuration, and
session logs. Who is responsible for collecting the list: the agent, the harness, or the human
committer? Added by Jose Celano.

#### Positions

No positions yet.

### Q6 - Human edits and rewrites

How is the list kept correct when a human edits AI output, when commits are reworded or rebased, or
when changes move between commits? Added by Jose Celano.

#### Positions

No positions yet.

### Q7 - Enforcement

Document the rule only, or also validate the trailer format in a `commit-msg` check? A tool can
check the format of a declared trailer. It cannot check whether a declaration is complete. Added by
Jose Celano.

#### Positions

No positions yet.

### Q8 - Interim rule

Should `AGENTS.md` forbid provider-default AI trailers before the decision? Added by Jose Celano.

#### Positions

No positions yet.

### Q9 - Legal input

Who reviews the EU AI Act question, and does the answer change the required level of detail? Added
by Jose Celano.

#### Positions

No positions yet.

## Outcome

Pending review.
Pending: no decision recorded.
Comment thread
da2ce7 marked this conversation as resolved.
Loading
Loading