Merge remote-tracking branch 'origin/main' into ci-merge-incremental-build-detect-dependencies

# Conflicts:
#	.github/workflows/pr-manual-component-test.yml

Author: gnodet

.github/workflows/pr-doc-validation.yml

@@ -22,6 +22,7 @@ on:
       - main
     paths:
       - '**.adoc'
+      - 'docs/**/*'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}

.github/workflows/pr-manual-component-test.yml

@@ -38,7 +38,7 @@ jobs:
           sparse-checkout: components
           sparse-checkout-cone-mode: true
       - name: Check Permission
-        uses: actions-cool/check-user-permission@7b90a27f92f3961b368376107661682c441f6103
+        uses: actions-cool/check-user-permission@c21884f3dda18dafc2f8b402fe807ccc9ec1aa5e
       - name: Retrieve PR sha and ref
         id: pr
         env:

.mvn/extensions.xml

@@ -8,7 +8,7 @@
     <extension>
         <groupId>eu.maveniverse.maven.nisse</groupId>
         <artifactId>extension</artifactId>
-        <version>0.7.0</version>
+        <version>0.8.1</version>
     </extension>
     <extension>
         <groupId>com.gradle</groupId>

AGENTS.md

@@ -43,6 +43,26 @@ These rules apply to ALL AI agents working on this codebase.
   Note: `fixVersions` cannot be set on an already-closed issue — set it before closing,
   or reopen/set/close if needed.
 
+### PR Description Maintenance
+
+When pushing new commits to a PR, **always update the PR description** (and title if needed) to
+reflect the current state of the changeset. PRs evolve across commits — the description must stay
+accurate and complete. Use `gh pr edit --title "..." --body "..."` after each push.
+
+### PR Reviewers
+
+When creating a PR, **always identify and request reviews** from the most relevant committers:
+
+- 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.
+- Use `git blame` on key modified files to identify who wrote the code being changed.
+- Cross-reference with the [committer list](https://camel.apache.org/community/team/#committers)
+  to ensure you request reviews from active committers (not just contributors).
+- For component-specific changes, prefer reviewers who have recently worked on that component.
+- For cross-cutting changes (core, API), include committers with broader project knowledge.
+- Request review from **at least 2 relevant committers** using `gh pr edit --add-reviewer`.
+- When all comments on the Pull Request are addressed (by providing a fix or providing more explanation) and the PR checks are green, re-request review on existing reviewers so that they are aware that the new changeset is ready to be reviewed.
+
 ### Merge Requirements
 
 - An agent MUST NOT merge a PR if there are any **unresolved review conversations**.
@@ -56,6 +76,95 @@ These rules apply to ALL AI agents working on this codebase.
 - All code must pass formatting checks (`mvn formatter:format impsort:sort`) before pushing.
 - All generated files must be regenerated and committed (CI checks for uncommitted changes).
 
+### Asynchronous Testing: Use Awaitility Instead of Thread.sleep
+
+Do **NOT** use `Thread.sleep()` in test code. It leads to flaky, slow, and non-deterministic tests.
+Use the [Awaitility](https://github.com/awaitility/awaitility) library instead, which is already
+available as a test dependency in the project.
+
+**Example — waiting for a route to be registered:**
+
+```java
+import static org.awaitility.Awaitility.await;
+
+await().atMost(20, TimeUnit.SECONDS)
+       .untilAsserted(() -> assertEquals(1, context.getRoutes().size()));
+```
+
+**Rules:**
+
+- New test code MUST NOT introduce `Thread.sleep()` calls.
+- When modifying existing test code that contains `Thread.sleep()`, migrate it to Awaitility.
+- Always set an explicit `atMost` timeout to avoid hanging builds.
+- Use `untilAsserted` or `until` with a clear predicate — do not replace a sleep with a
+  busy-wait loop.
+
+### Issue Investigation (Before Implementation)
+
+Before implementing a fix for a JIRA issue, **thoroughly investigate** the issue's validity and context.
+Camel is a large, long-lived project — code often looks "wrong" but exists for good reasons. Do NOT
+jump straight to implementation after reading the issue description and the current code.
+
+**Required investigation steps:**
+
+1. **Validate the issue**: Confirm the reported problem is real and reproducible. Question assumptions
+   in the issue description — they may be incomplete or based on misunderstanding.
+2. **Check git history**: Run `git log --oneline <file>` and `git blame <file>` on the affected code.
+   Read the commit messages and linked JIRA tickets for prior changes to understand *why* the code
+   is written the way it is.
+3. **Search for related issues**: Search JIRA for related tickets (same component, similar keywords)
+   to find prior discussions, rejected approaches, or intentional design decisions.
+4. **Look for design documents**: Check the `proposals/` directory for design docs (`.adoc` files)
+   that may explain architectural decisions in the affected area.
+5. **Understand the broader context**: If the issue involves a module that replaced or deprecated
+   another (e.g., `camel-opentelemetry2` replacing `camel-opentelemetry`), understand *why* the
+   replacement was made and what was intentionally changed vs. accidentally omitted.
+6. **Check if the "fix" reverts prior work**: If your proposed change effectively reverts a prior
+   intentional commit, stop and reconsider. If the revert is still justified, explicitly acknowledge
+   it in the PR description and explain why despite the original rationale.
+
+**Present your findings** to the operator before implementing. Flag any risks, ambiguities, or cases
+where the issue may be invalid or the proposed approach may conflict with prior decisions.
+
+### Knowledge Cutoff Awareness
+
+AI agents have a training data cutoff and may not know about recent releases, API changes, or
+deprecations in external projects. **Never make authoritative claims about external project state
+based solely on training knowledge.**
+
+- When a JIRA issue, PR, or code references a specific version of an external dependency (e.g.,
+  Spring Boot 4.0, JUnit 6, Jakarta EE 11), **verify it exists** by checking official sources
+  (web search, Maven Central, release notes) before questioning or relying on it.
+- When implementing or reviewing changes that depend on external project behavior, verify the
+  current state rather than assuming training data is up to date.
+- If uncertain about whether something exists or has changed, say so and verify — do not
+  confidently assert something is wrong based on potentially stale knowledge.
+
+### Git History Review (When Reviewing PRs)
+
+When reviewing PRs, apply the same investigative rigor:
+
+- Check `git log` and `git blame` on modified files to see if the change conflicts with prior
+  intentional decisions.
+- Verify that "fixes" don't revert deliberate behavior without justification.
+- Check for design proposals (`proposals/*.adoc`) related to the affected area.
+- Search for related JIRA tickets that provide context on why the code was written that way.
+
+### Documentation Conventions
+
+When writing or modifying `.adoc` documentation:
+
+- **Use `xref:` for internal links**, never external `https://camel.apache.org/...` URLs.
+  Example: `xref:manual::camel-jbang.adoc[Camel JBang]` instead of
+  `https://camel.apache.org/manual/camel-jbang.html[Camel JBang]`.
+- **Cross-version xref fragments**: When linking to a section anchor (e.g., `#_my_section`) using
+  the `components::` prefix, verify that the target section exists in the **current released version**,
+  not just on `main`. The `components::` prefix resolves to the latest released version, so anchors
+  that only exist on `main` will produce broken links. Either omit the fragment or use a
+  version-aware reference.
+- **When reviewing doc PRs**, check that all `xref:` links and anchors resolve correctly, especially
+  cross-component references that may span versions.
+
 ## Structure
 
 ```