PROVENANCE_POLICY.md

Provenance Policy

This repository records the provenance of committed artifacts. Provenance declarations provide reviewers and future maintainers with additional context about how project artifacts came into existence, improving transparency, reproducibility, and code review.

This document defines the project's conventions for recording those provenance declarations. Its purpose is to document engineering provenance rather than to endorse or discourage the use of any particular class of tools.

New classes of artifact-producing tools will continue to emerge. By focusing on provenance instead of implementation technology, this policy remains applicable as development tools evolve.

Scope

This policy applies to all version-controlled artifacts in this repository.

It does not currently govern publications, presentations, websites, or other materials maintained outside this repository. Future policies may extend these principles to additional artifacts.

Guiding Principles

This policy is guided by the following principles:

• Provenance should be transparent.
• Human contributors remain responsible for every committed change.
• Provenance should describe engineering workflows rather than the capabilities or status of tools.
• Provenance declarations should record only tools that materially contributed to a committed artifact.
• This policy intentionally classifies artifacts according to how they were produced rather than what technologies produced them.
• The policy should remain applicable as development tools evolve.

Definitions

Artifact

An artifact is any version-controlled content committed to the repository, including source code, tests, documentation, commit messages, changelog entries, and similar materials.

Artifact-producing tool

An artifact-producing tool is a software tool that materially contributes to the creation or transformation of project artifacts.

This definition is intentionally technology-agnostic. It includes any tool whose output materially affects committed artifacts, regardless of the underlying implementation.

Provenance declaration

A provenance declaration records the artifact-producing tools and engineering workflow that materially contributed to a committed artifact.

A provenance declaration consists of Git commit trailers describing:

• the artifact-producing tool, and
• the workflow by which the artifact was produced

Commit Trailers

Commits involving artifact-producing tools should include provenance declarations.

Example:

Provenance: ChatGPT (GPT-5.5 Instant, OpenAI)
Workflow: collaborative

The provenance declaration should identify the artifact-producing tool with enough specificity for a future reader to understand the workflow. When practical, this includes the product name, provider, model, and version.

Workflow classifies the engineering process by which the artifact was produced. It does not classify the provenance tool itself.

Workflow Classification

The following workflow classifications are defined:

Workflow	Description
human	Produced without material contribution from an artifact-producing tool.
generated	Materially generated by an artifact-producing tool with limited iterative refinement.
collaborative	Produced through iterative interaction between a human contributor and an artifact-producing tool.
transformed	Materially rewritten, translated, reformatted, or otherwise transformed by an artifact-producing tool.
reviewed	Materially influenced through analysis or review performed by an artifact-producing tool, without directly generating the committed artifact.
consulted	Informed by an artifact-producing tool without materially producing committed artifacts.
other	Any workflow not otherwise described. A brief explanation should accompany the provenance declaration.

Example:

Provenance: Internal Synthesis Tool (2026.3)
Workflow: other

Explanation: The artifact was produced by combining the outputs of
multiple artifact-producing tools through an automated workflow.

Material Contribution

Not every interaction with a software tool requires a provenance declaration.

In general, provenance should be recorded only when an artifact-producing tool materially contributes to committed artifacts.

The following are examples of material contributions:

• generating source code
• generating tests
• drafting documentation
• drafting commit messages
• rewriting or translating documentation
• performing substantial automated refactoring

The following normally do not require provenance declarations:

• syntax highlighting
• spell checking
• formatting
• linting
• static analysis
• code navigation
• simple identifier completion
• other tooling that does not materially contribute to committed artifacts

When in doubt, contributors are encouraged to err on the side of disclosure.

Information Handling

Provide information to artifact-producing tools only when that information may be processed by those tools under applicable organizational policy.

Contributors are responsible for ensuring that their use of artifact-producing tools complies with all applicable organizational policies governing confidential, proprietary, export-controlled, or otherwise restricted information.

Pull Requests

Pull requests containing one or more commits with provenance declarations should include the provenance-declared label.

The purpose of this label is to help reviewers identify pull requests whose history contains provenance declarations. It is not intended as a statement about the quality or acceptability of the changes.

Responsibility

Recording provenance does not transfer responsibility.

The human author of a commit remains responsible for:

• correctness
• security
• licensing
• confidentiality
• attribution
• compliance with project policies

Provenance declarations exist to improve transparency and review. They do not alter authorship or accountability.

Evolution

This policy is expected to evolve as development workflows and artifact-producing tools continue to change.