From 7db22c6a60b9713fe6d42b7b418ae4e53059eaf3 Mon Sep 17 00:00:00 2001
From: Ioannis Polyzos <git@ipolyzos.com>
Date: Sat, 10 Oct 2026 16:03:55 +0100
Subject: [PATCH 1/3] =?UTF-8?q?ci:=20test=20Python=203.10=E2=80=933.13=20a?=
 =?UTF-8?q?nd=20macOS=20compatibility?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/validate.yml | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index b6f160c..aab9b2d 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -28,3 +28,30 @@ jobs:
         run: python3 scripts/run_benchmark.py evaluations/benchmarks/stdlib-smoke.json --cwd . --output /tmp/playbook-smoke-evidence.json
       - name: Verify fixture artifact assertions
         run: python3 scripts/run_fixture.py evaluations/benchmarks/copy-task.json --fixture evaluations/benchmarks/fixtures/copy-task --output /tmp/playbook-copy-evidence.json
+
+  compatibility:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: ubuntu-latest, python: "3.10"}
+          - {os: ubuntu-latest, python: "3.12"}
+          - {os: ubuntu-latest, python: "3.13"}
+          - {os: macos-latest, python: "3.12"}
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install package and validation dependencies
+        run: |
+          python -m pip install -e .
+          python -m pip install -r requirements-dev.txt
+      - name: Validate installed command
+        run: aicp --version
+      - name: Run regression tests
+        run: python -m unittest discover -s tests -v

From aa5b32bc6d0ec8c03e6bf473639c792e4a8a1aa3 Mon Sep 17 00:00:00 2001
From: Ioannis Polyzos <git@ipolyzos.com>
Date: Sat, 10 Oct 2026 16:04:04 +0100
Subject: [PATCH 2/3] docs: document platform matrix and manual agent
 integration limits

---
 docs/COMPATIBILITY.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 docs/COMPATIBILITY.md

diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md
new file mode 100644
index 0000000..7b3438e
--- /dev/null
+++ b/docs/COMPATIBILITY.md
@@ -0,0 +1,17 @@
+# Compatibility and integration testing
+
+The GitHub Actions [Validate workflow](../.github/workflows/validate.yml) runs the standard validation job and a compatibility matrix for Python 3.10, 3.12, and 3.13 on Linux, plus Python 3.12 on macOS. Each matrix job installs the package, exercises the installed CLI, and runs unit tests. This matrix is a compatibility sample, not a guarantee for every Python version and operating system.
+
+## Agent integration tests
+
+Unit tests for `aicp run` mock the agent executable. They do **not** validate real Codex, Claude, or Gemini CLI behavior. Real agent integration testing is intentionally **manual and opt-in**, because it requires vendor installations, authentication, a disposable host, and potentially network access.
+
+Before attempting a real run:
+
+1. Provision an isolated, disposable machine with no personal or organization credentials beyond the minimum vendor-specific test account.
+2. Review the agent command and the task and checks files; use synthetic data only.
+3. Explicitly approve host execution and run `aicp run` as documented in [CLI](CLI.md).
+4. Review modified files, command hashes, exit statuses, and test evidence; do not treat the JSON report as scope enforcement or proof of isolation.
+5. Delete the disposable environment and revoke temporary credentials.
+
+The project does not execute live vendor agents in standard CI. Do not add real API keys or private project data to workflow fixtures.

From d1a4748da52626920d64d9b9047f7433fdd59304 Mon Sep 17 00:00:00 2001
From: Ioannis Polyzos <git@ipolyzos.com>
Date: Sat, 10 Oct 2026 16:04:08 +0100
Subject: [PATCH 3/3] docs: link compatibility and integration guidance

---
 docs/README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/README.md b/docs/README.md
index 2508837..8d65d49 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,6 +11,7 @@ Start with [Getting started](GETTING_STARTED.md) for quick setup, the [practical
 - [Non-destructive adoption](ADOPTION.md)
 - [Generated tool entrypoints](TOOL_ENTRYPOINTS.md)
 - [Local verification](VERIFICATION.md)
+- [Platform compatibility and agent integration](COMPATIBILITY.md)
 
 ## Engineering guides