diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5f217d9c..2260a950 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -25,6 +25,7 @@ This checklist serves as a reminder of a couple of things that ensure your pull **If PR contains AI-assisted content:** -- [ ] I have disclosed the use of AI tools in the PR description as per our [AI Usage Guidelines](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/docs/ai_usage.md). +- [ ] Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our [AI Usage Guidelines](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/docs/ai_usage.md). +- [ ] Every agent-authored or agent-edited public text body begins with the visible disclosure `🤖 *AI text below* 🤖` (titles are exempt). - [ ] AI-assisted commits include an `Assisted-by: [Model Name] via [Tool Name]` footer. - [ ] I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it. diff --git a/AGENTS.md b/AGENTS.md index 17ee84b9..1fc71389 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,6 +41,9 @@ ### General +- MUST read and follow `docs/ai_usage.md`. A human must review and understand + all AI-assisted work. AI assistance must not be used for contributions to + issues labeled `good first issue`. - MUST run `uvx nox -s lint` after every batch of changes. This runs the full `prek` hook set from `.pre-commit-config.yaml` (including `ruff`, `typos`, `ty`, formatting, and metadata checks). All hooks must pass before submitting. @@ -58,6 +61,23 @@ and changes will be overwritten. - PREFER running targeted tests over the full test suite during development. +### GitHub Issues and Pull Requests + +- MAY create, submit, and edit pull requests; create and manage issues; and + comment on issues or pull requests when the task explicitly authorizes that + external action. A single authorization may cover a clearly scoped task; + per-message approval is not required. Actions outside that scope require fresh + authorization. The human remains responsible for reviewing all submitted work. +- MUST use the repository's pull request template when one is present. +- Every agent-authored or agent-edited public text body MUST begin with + `🤖 *AI text below* 🤖` on its first line. This applies to issue and pull + request descriptions, review bodies, inline review comments, issue comments, + replies, and other submitted text bodies; titles are exempt. +- When editing human-authored public text, preserve its original content and add + the disclosure at the beginning of the edited field. +- MUST keep external communication accurate, specific, and non-repetitive; do + not post low-quality or unsolicited comments. + ### Python - MUST use Google-style docstrings @@ -73,3 +93,5 @@ - Did `uvx nox -s lint` pass without errors? - Are all changes covered by at least one automated test? +- Were any agent-authored issue or pull request texts explicitly authorized and + marked with the required visible disclosure? diff --git a/docs/ai_usage.md b/docs/ai_usage.md index 889d3c28..aa58206c 100644 --- a/docs/ai_usage.md +++ b/docs/ai_usage.md @@ -31,41 +31,59 @@ not submit it. ### 2. Human in the Loop -> **Autonomous contributions from AI agents are not allowed.** +**Humans remain accountable for AI-assisted contributions.** -When using AI tools, you must be the driver. The AI is the assistant. +AI agents may implement changes and manage issue and pull request workflows when +a human explicitly authorizes the scope and relevant external actions. The human +remains the driver and is responsible for the resulting contribution. -- **Review:** You must read and review all AI-generated code or text before - submitting it. +- **Review:** You must read and review all AI-generated code and relevant public + text before merging or otherwise accepting the contribution. You remain + accountable for public text posted within an authorized scope. - **Edit:** AI-generated code often requires significant editing to meet project standards and correctness. - **Verify:** Ensure the code actually solves the problem and doesn't introduce subtle bugs or security vulnerabilities. +- **Authorize:** Explicitly authorize agents before they create, edit, submit, + or comment on issues and pull requests. A single authorization may cover a + clearly scoped task; per-message approval is not required. Remain accountable + for all external communication that agents submit on your behalf. Actions + outside the authorized scope require fresh authorization. ### 3. Communication -**Do not use AI tools to generate issue descriptions, pull request comments, or -code reviews.** +**AI tools may be used to prepare and manage issue and pull request workflows, +including descriptions, comments, and code reviews, when a human has authorized +the action and remains responsible for the result.** -We value your personal input and communication. LLMs are notoriously unreliable -and can produce "smart-sounding" but incorrect or irrelevant claims -("hallucinations"). Phrase your communications in your own words. It is more -important that we can follow your reasoning than that the text sounds "perfect". +AI-generated communication can be incorrect, irrelevant, or overly generic. Keep +it accurate, specific, and useful to reviewers and contributors. Do not post +low-quality, repetitive, or unsolicited messages. + +Every agent-authored or agent-edited public text body must begin with the +following visible disclosure: + +`🤖 *AI text below* 🤖` + +This requirement applies to issue and pull request descriptions, review bodies, +inline review comments, issue-style comments, replies, and other submitted text +bodies. Pull request and issue titles are exempt. When editing existing +human-authored text, preserve the original content and add the disclosure at the +beginning of the edited field. ### 4. Transparency and Disclosure Transparency helps the community understand the role of these tools and develop best practices. -**We encourage you to disclose any AI assistance.** This helps us understand how -these tools are being used and identify potential issues. You can disclose this -information in the following ways: +**You must disclose AI assistance.** This helps us understand how the tools are +being used and identify potential issues. Disclose it in the following ways: - **Commit Messages**: Add a trailer to your commit message in the form `Assisted-by: [Model Name] via [Tool Name]` (example: `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`) -- **PR Description**: Mention the tool (name and version) and how it was used in - the PR description. +- **Public issue and pull request text**: Use the visible disclosure required in + the [communication policy](#3-communication). ### 5. Licensing and Copyright @@ -125,10 +143,10 @@ its contributors can thrive. - **"Good First Issues"**: Do not use AI tools to solve issues labeled as "good first issue". These are intended as learning opportunities for new contributors. Automating them defeats the purpose. -- **Spam**: Do not use AI to generate low-quality or repetitive comments/reviews - ("AI Slop"). -- **Unreviewed Code**: Submitting code that you, as a human, have not reviewed - and tested yourself. +- **Spam**: Do not use AI to generate low-quality, repetitive, or unsolicited + comments or reviews ("AI Slop"). +- **Unreviewed Code**: Merging or accepting code that you, as a human, have not + reviewed and tested yourself. ## Summary diff --git a/docs/contributing.md b/docs/contributing.md index a8e5ea83..c9271ffc 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -94,8 +94,13 @@ quality and licensing compliance. Please carefully read and follow our dedicated {doc}`ai_usage` before submitting any AI-assisted contribution. In short: **You are responsible for every line of code you submit**, and a -**human must always be in the loop**. We require disclosure of AI tool usage in -your PR description. +**human must always be in the loop**. Agents may perform coding and GitHub tasks +within an explicitly authorized scope, but you must review their work and remain +accountable for the result. Every agent-authored or agent-edited public text +body must begin with `🤖 *AI text below* 🤖`; issue and pull request titles are +exempt. AI-assisted commits must include an +`Assisted-by: [Model Name] via [Tool Name]` footer. AI assistance must not be +used for contributions to issues labeled "good first issue". If you use an agent, it will automatically read the provided {code}`AGENTS.md`, which contains context and instructions to help the agent work on MQT