This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 43c360784835 Add merge procedure rules and anti-hallucination
safeguards for AI agents
43c360784835 is described below
commit 43c3607848357b8b31147d1427bbdf4ff7a9d6b5
Author: Guillaume Nodet <[email protected]>
AuthorDate: Mon Jul 6 16:33:56 2026 +0200
Add merge procedure rules and anti-hallucination safeguards for AI agents
Co-authored-by: Claude Opus 4.6 <[email protected]>
* Add merge procedure rules for AI agents
Document the complete merge workflow: derive milestone from
target-branch pom.xml, assign milestone/labels/assignees on
both the PR and JIRA issue, merge, close JIRA, and clean up
the branch. Rules added to both AGENTS.md and the oss-helper
project-guidelines so all agent tooling picks them up.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* Require programmatic username lookup to prevent hallucination
Agents have been hallucinating the operator's or PR author's
GitHub username instead of looking it up. Add explicit rules
to both the Attribution section and the Merge Procedure to
always use `gh api /user` or `gh pr view --json author` and
never guess.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* Do not request reviewers on draft PRs
Agents were requesting reviewers immediately on PR creation,
even for drafts still being worked on. Defer reviewer
requests until the PR is marked ready for review.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* Include AI co-authorship trailer in squash-merge commit message
Address review feedback from @davsclaus: when squash-merging
an AI-assisted PR, the resulting commit message must include
the Co-authored-by trailer for the AI agent.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
---
.oss-ai-helper-rules/project-guidelines.md | 8 +++++
AGENTS.md | 54 +++++++++++++++++++++++++++++-
2 files changed, 61 insertions(+), 1 deletion(-)
diff --git a/.oss-ai-helper-rules/project-guidelines.md
b/.oss-ai-helper-rules/project-guidelines.md
index 2f03203b9b3f..56a516dbcd54 100644
--- a/.oss-ai-helper-rules/project-guidelines.md
+++ b/.oss-ai-helper-rules/project-guidelines.md
@@ -17,3 +17,11 @@ This rule file contains branching, commit, PR, and
task-finding conventions for
- **Find-task intermediate:** Filter 12352792 (easy issues)
- **Find-task experienced JQL:** `project = CAMEL AND status = Open AND labels
= help-wanted` (maxResults=10)
- **Scope-too-large redirect:** create a Jira issue directly
+- **Merge procedure:**
+ 1. Derive milestone from target branch: read `<version>` from root `pom.xml`
on the target branch and strip `-SNAPSHOT` (e.g., `4.22.0-SNAPSHOT` → `4.22.0`)
+ 2. Assign milestone to PR (`gh pr edit <PR> --milestone <version>`) and set
`fixVersions` on the JIRA issue to the same version (before closing)
+ 3. Assign PR to the PR author (`gh pr edit <PR> --add-assignee <author>`)
and verify JIRA issue is assigned to the contributor. **Never guess the
author** — look it up with `gh pr view <PR> --json author --jq '.author.login'`
+ 4. Categorize PR with labels based on JIRA issue type or PR content: `bug`
(Bug), `enhancement` (Improvement/New Feature), `documentation`
(Documentation), `task` (Task/refactoring), `dependency` (dependency upgrades),
`test` (Test)
+ 5. Merge the PR (after verifying human approval and no unresolved
conversations)
+ 6. Close the JIRA issue (transition to Resolved/Fixed, add comment linking
to merged PR)
+ 7. Delete the PR branch
diff --git a/AGENTS.md b/AGENTS.md
index 5d3716fd0a6a..b790b00131a4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -19,6 +19,9 @@ These rules apply to ALL AI agents working on this codebase.
- All AI-generated content (GitHub PR descriptions, review comments, JIRA
comments) MUST clearly
identify itself as AI-generated and mention the human operator.
Example: "_Claude Code on behalf of [Human Name]_"
+- **Never guess or hallucinate the operator's name.** Always determine it
programmatically:
+ - Use `gh api /user --jq '.login'` to get the authenticated GitHub username.
+ - If for any reason the lookup fails, omit the name rather than guessing.
- AI coding agents MUST be configured to add co-authorship trailers to commits
(e.g., `Co-authored-by`). For Claude Code, enable this via the
[attribution
settings](https://code.claude.com/docs/en/settings#attribution-settings).
@@ -54,7 +57,9 @@ accurate and complete. Use `gh pr edit --title "..." --body
"..."` after each pu
### PR Reviewers
-When creating a PR, **always identify and request reviews** from the most
relevant committers:
+When a PR is **ready for review** (not in draft), **always identify and
request reviews** from
+the most relevant committers. **Do NOT request reviewers on draft PRs** — wait
until the PR is
+marked ready for review.
- Run `git log --format='%an' --since='1 year' -- <affected-files> | sort |
uniq -c | sort -rn | head -10`
to find who has been most active on the affected files.
@@ -72,6 +77,53 @@ When creating a PR, **always identify and request reviews**
from the most releva
- An agent MUST NOT merge a PR without at least **one human approval**.
- An agent MUST NOT approve its own PRs — human review is always required.
+### Merge Procedure
+
+When merging a PR, an agent MUST perform the following steps **in order**:
+
+1. **Derive the milestone from the target branch**:
+ - Read the `<version>` from the root `pom.xml` on the PR's **target
branch** (e.g., `main`,
+ `camel-4.18.x`).
+ - Strip the `-SNAPSHOT` suffix to get the milestone name (e.g.,
`4.22.0-SNAPSHOT` → `4.22.0`).
+
+2. **Assign the milestone**:
+ - Set the GitHub milestone on the PR: `gh pr edit <PR> --milestone
<version>`.
+ - If the milestone does not exist yet on GitHub, create it first:
+ `gh api repos/{owner}/{repo}/milestones -f title="<version>"`.
+ - Set `fixVersions` on the corresponding JIRA issue to the same version.
Note: `fixVersions`
+ cannot be set on an already-closed issue — always set it **before**
closing.
+
+3. **Assign the PR and JIRA issue to the contributor**:
+ - **Never guess or hallucinate the PR author's username.** Always look it
up programmatically:
+ `gh pr view <PR> --json author --jq '.author.login'`.
+ - Assign the PR to the PR author on GitHub: `gh pr edit <PR> --add-assignee
<author>`.
+ - Ensure the JIRA issue is assigned to the contributor (it should already
be from the
+ "JIRA Ticket Ownership" rules, but verify).
+
+4. **Categorize the PR with labels**:
+ - Determine the PR category from the linked JIRA issue type or PR content:
+ - `bug` — for bug fixes (JIRA type: Bug)
+ - `enhancement` — for improvements and new features (JIRA type:
Improvement, New Feature)
+ - `documentation` — for documentation-only changes (JIRA type:
Documentation)
+ - `task` — for chores, refactoring, build changes (JIRA type: Task)
+ - `dependency` — for dependency upgrades
+ - `test` — for test-only changes (JIRA type: Test)
+ - Apply the label: `gh pr edit <PR> --add-label <category>`.
+
+5. **Merge the PR**:
+ - Verify all merge requirements above are satisfied (human approval, no
unresolved conversations).
+ - If any commit in the PR was AI-assisted, the squash-merge commit message
MUST include the
+ AI co-authorship trailer (e.g., `Co-authored-by: Claude Opus 4.6
<[email protected]>`).
+ - Merge the PR: `gh pr merge <PR> --squash` (or `--merge` / `--rebase` as
appropriate).
+
+6. **Close the JIRA issue**:
+ - Transition the JIRA issue to **Resolved/Fixed** (ensure `fixVersions` is
already set from step 2).
+ - Add a comment linking to the merged PR.
+
+7. **Clean up the branch**:
+ - Delete the PR branch after merge (GitHub may do this automatically if
configured).
+ - As per the "Git branch" rules, branches must be cleaned up after merge or
rejection.
+
### Code Quality
- Every PR must include tests for new functionality or bug fixes.
