Merge 9f08ab29e1 into bf5da9a9fb

This will make future contributions and development with the help of AI
Agents easier.

It is primarily generated by codex-cli v0.40.0 using gpt-5-codex-high,
along with the following AGENTS.md construction prompt:
- https://gist.github.com/PeterDaveHello/f30c38a156982a35683edfd5ece2d474

Reference:
- https://agents.md/

AGENTS.md

@@ -0,0 +1,70 @@
+# Repository Guidelines
+
+## Dos and Don’ts
+
+- **Do** match the interpreter requirement declared in `pyproject.toml` (Python ≥ 3.12) and install `requirements.txt` plus `requirements-dev.txt` before running tools.
+- **Do** run tests with `PYTHONPATH=.` set to keep imports functional (for example `PYTHONPATH=. ./.venv/bin/pytest tests/unittest/test_fix_json_escape_char.py -q`).
+- **Do** adjust configuration through `.pr_agent.toml` or files under `pr_agent/settings/` instead of hard-coding values.
+- **Don’t** commit secrets or access tokens; rely on environment variables as shown in the health and e2e tests.
+- **Don’t** reformat or reorder files globally; match existing 120-character lines, import ordering, and docstring style.
+- **Don’t** delete or rename configuration, prompt, or workflow files without maintainer approval.
+
+## Project Structure and Module Organization
+
+PR-Agent automates AI-assisted reviews for pull requests across multiple git providers.
+
+- `pr_agent/agent/` orchestrates commands (`review`, `describe`, `improve`, etc.) via `pr_agent/agent/pr_agent.py`.
+- `pr_agent/tools/` implements individual capabilities such as reviewers, code suggestions, docs updates, and label generation.
+- `pr_agent/git_providers/` and `pr_agent/identity_providers/` handle integrations with GitHub, GitLab, Bitbucket, Azure DevOps, and secrets.
+- `pr_agent/settings/` stores Dynaconf defaults (prompts, configuration templates, ignore lists) respected at runtime; `.pr_agent.toml` overrides repository-level behavior.
+- `tests/unittest/`, `tests/e2e_tests/`, and `tests/health_test/` contain pytest-based unit, end-to-end, and smoke checks.
+- `docs/` holds the MkDocs site (`docs/mkdocs.yml` plus content under `docs/docs/`); overrides live in `docs/overrides/`.
+- `.github/workflows/` defines CI pipelines for unit tests, coverage, docs deployment, pre-commit, and PR-agent self-review.
+- `docker/` and the root Dockerfiles provide build targets for services (`github_app`, `gitlab_webhook`, etc.) and the `test` stage used in CI.
+
+## Build, Test, and Development Commands
+
+- Create or activate a virtual environment, then install runtime dependencies with `pip install -r requirements.txt`; add development tooling via `pip install -r requirements-dev.txt`.
+- Run a single unit test (verified): `PYTHONPATH=. ./.venv/bin/pytest tests/unittest/test_fix_json_escape_char.py -q`.
+- Run the full unit suite: `PYTHONPATH=. ./.venv/bin/pytest tests/unittest -v`.
+- Execute the CLI locally once dependencies and API keys are available: `python -m pr_agent.cli --pr_url <https://host/org/repo/pull/123> review`.
+- Build the test Docker target mirror of CI when containerizing: `docker build -f docker/Dockerfile --target test .` (loads dev dependencies and copies `tests/`).
+- Generate and deploy documentation with MkDocs after installing the same extras as CI (`mkdocs-material`, `mkdocs-glightbox`): `mkdocs serve -f docs/mkdocs.yml` for previews and `mkdocs gh-deploy -f docs/mkdocs.yml` for publication.
+
+## Coding Style and Naming Conventions
+
+- Python sources follow the Ruff configuration in `pyproject.toml` (`line-length = 120`, Pyflakes plus `flake8-bugbear` checks, and isort ordering). Keep imports grouped as isort would produce and prefer double quotes for strings.
+- Pre-commit (`.pre-commit-config.yaml`) enforces trailing whitespace cleanup, final newlines, TOML/YAML validity, and optional `isort`; run `pre-commit run --all-files` before submitting patches if installed.
+- Match existing docstring and comment style—concise English comments using imperative phrasing only where necessary.
+- Configuration files in `pr_agent/settings/` are TOML; preserve formatting, section order, and comments when editing prompts or defaults.
+- Markdown in `docs/` uses MkDocs conventions (YAML front matter absent; rely on heading hierarchy already in place).
+
+## Testing Guidelines
+
+- Pytest is the standard framework; keep new tests under the closest matching directory (`tests/unittest/` for unit logic, `tests/e2e_tests/` for integration flows, `tests/health_test/` for smoke coverage).
+- Prefer focused unit tests that isolate helpers in `pr_agent/algo/`, `pr_agent/tools/`, or provider adapters; use parameterized tests where existing files already do so.
+- Set `PYTHONPATH=.` when invoking pytest from the repository root to avoid import errors.
+- End-to-end suites require provider tokens (`TOKEN_GITHUB`, `TOKEN_GITLAB`, `BITBUCKET_USERNAME`, `BITBUCKET_PASSWORD`) and may take several minutes; run them only when credentials and sandboxes are configured.
+- The health test (`tests/health_test/main.py`) exercises `/describe`, `/review`, and `/improve`; update expected artifacts if prompts change meaningfully.
+
+## Commit and Pull Request Guidelines
+
+- Follow `CONTRIBUTING.md`: keep changes focused, add or update tests, and use Conventional Commit-style messages (e.g., `fix: handle missing repo settings gracefully`).
+- Target branch names follow `feature/<name>` or `fix/<issue>` patterns for substantial work.
+- Reference related issues and update README or docs when user-facing behavior shifts.
+- Ensure CI workflows (`build-and-test`, `code-coverage`, `docs-ci`) succeed locally or in draft PRs before requesting review; reproduce failures with the documented commands above.
+- Include screenshots or terminal captures when modifying user-visible output or documentation previews.
+
+## Safety and Permissions
+
+- Ask for confirmation before adding dependencies, renaming files, or changing workflow definitions; many consumers embed these paths and prompts.
+- Stay within existing formatting and directory conventions—avoid mass refactors, re-sorting of prompts, or reformatting Markdown beyond the touched sections.
+- You may read files, list directories, and run targeted lint/test/doc commands without prior approval; coordinate before launching full Docker builds or e2e suites that rely on external credentials.
+- Never commit cached credentials, API keys, or coverage artifacts; CI already handles secrets through GitHub Actions.
+- Treat prompt and configuration files as single sources of truth—update mirrors (`.pr_agent.toml`, `pr_agent/settings/*.toml`) together when behavior changes.
+
+## Security and Configuration Tips
+
+- Secrets should be supplied through environment variables (see usages in `tests/e2e_tests/test_github_app.py` and `tests/health_test/main.py`); do not persist them in code or configuration files.
+- Adjust runtime behavior by overriding keys in `.pr_agent.toml` or by supplying repository-specific Dynaconf files; keep overrides minimal and documented inside the PR description.
+- Review `SECURITY.md` before disclosing vulnerabilities and follow its contact instructions for responsible reporting.

docs/docs/core-abilities/fetching_ticket_context.md

@@ -54,17 +54,17 @@ A `PR Code Verified` label indicates the PR code meets ticket requirements, but
 
 #### Configuration options
 
-- 
+-
 
-    By default, the tool will automatically validate if the PR complies with the referenced ticket.
+    By default, the `review` tool will automatically validate if the PR complies with the referenced ticket.
     If you want to disable this feedback, add the following line to your configuration file:
-    
+
     ```toml
     [pr_reviewer]
     require_ticket_analysis_review=false
     ```
 
-- 
+-
 
     If you set:
     ```toml
@@ -72,9 +72,36 @@ A `PR Code Verified` label indicates the PR code meets ticket requirements, but
     check_pr_additional_content=true
     ```
     (default: `false`)
-    
+
     the `review` tool will also validate that the PR code doesn't contain any additional content that is not related to the ticket. If it does, the PR will be labeled at best as `PR Code Verified`, and the `review` tool will provide a comment with the additional unrelated content found in the PR code.
 
+### Compliance tool
+
+The `compliance` tool also uses ticket context to validate that PR changes fulfill the requirements specified in linked tickets.
+
+#### Configuration options
+
+-
+
+    By default, the `compliance` tool will automatically validate if the PR complies with the referenced ticket.
+    If you want to disable ticket compliance checking in the compliance tool, add the following line to your configuration file:
+
+    ```toml
+    [pr_compliance]
+    require_ticket_analysis_review=false
+    ```
+
+-
+
+    If you set:
+    ```toml
+    [pr_compliance]
+    check_pr_additional_content=true
+    ```
+    (default: `false`)
+
+    the `compliance` tool will also validate that the PR code doesn't contain any additional content that is not related to the ticket.
+
 ## GitHub/Gitlab Issues Integration
 
 Qodo Merge will automatically recognize GitHub/Gitlab issues mentioned in the PR description and fetch the issue content.

docs/docs/tools/compliance.md

@@ -329,6 +329,10 @@ enable_global_pr_compliance = true
 ???+ example "Ticket compliance options"
 
     <table>
+      <tr>
+        <td><b>require_ticket_analysis_review</b></td>
+        <td>If set to true, the tool will fetch and analyze ticket context for compliance validation. Default is true.</td>
+      </tr>
       <tr>
         <td><b>enable_ticket_labels</b></td>
         <td>If set to true, the tool will add ticket compliance labels to the PR. Default is false.</td>