From d2dedd9b1901ab71999d7ce2a6a4e35696e2ece9 Mon Sep 17 00:00:00 2001
From: Andrew Masiye <amasiye313@gmail.com>
Date: Thu, 6 Aug 2026 04:27:38 +0200
Subject: [PATCH 1/3] docs(guardrails): codify remote branch policy

---
 AGENTS.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index cb8a28f..109f5d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,6 +11,14 @@ These rules apply to `lenga/engine` package code and tests. They are version-con
 - Prefer `use` imports over fully qualified class names. Keep fully qualified names only when there is a clear reason, such as global built-ins, unavoidable name collisions, or intentionally explicit runtime references.
 - Keep files LF/Unix line endings. Do not introduce CRLF line endings.
 
+## Remote Branch Policy
+
+- Keep feature, fix, release-preparation, agent, and other topic branches local by default. Never push a non-`develop` branch to GitHub or another remote unless the user explicitly instructs you to push that named branch.
+- The normal sharing workflow is to finish or merge local work into local `develop`, then push only `develop` to the remote `develop` branch. Do not push `main` directly unless the user explicitly instructs it.
+- A request to implement, commit, continue, prepare a release, or create a branch is not permission to publish a topic branch. Do not infer remote-push permission from the broader task.
+- Before every push, verify the current branch and use an explicit `develop:develop` refspec for the normal workflow. Never rely on a bare `git push` when it could publish another branch.
+- If the user explicitly authorizes a remote topic branch, remove that remote branch after it is merged or closed unless the user asks to preserve it.
+
 ## Native Runtime Boundary
 
 - Do not ship `EngineHeader.php` or any PHP declarations for native bridge functions.

From 0d1d970e1d62d7194bbb5f873aa0e06c8a314887 Mon Sep 17 00:00:00 2001
From: Andrew Masiye <amasiye313@gmail.com>
Date: Thu, 6 Aug 2026 14:59:01 +0200
Subject: [PATCH 2/3] ci(php): validate api package on pushes and pull requests

---
 .github/workflows/ci.yml | 59 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 .github/workflows/ci.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..543ec58
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,59 @@
+name: PHP API CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - develop
+      - main
+    tags:
+      - '*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out PHP API
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.5'
+          extensions: dom, json, libxml, mbstring, tokenizer, xml, xmlwriter
+          tools: composer:v2
+          coverage: none
+
+      - name: Cache Composer downloads
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/composer/files
+          key: composer-${{ runner.os }}-${{ hashFiles('composer.lock', 'composer.json') }}
+          restore-keys: |
+            composer-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      - name: Validate package metadata and autoloading
+        run: |
+          composer validate --strict --no-check-publish
+          composer dump-autoload --optimize --strict-psr --no-interaction
+
+      - name: Verify release tag metadata
+        if: startsWith(github.ref, 'refs/tags/')
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION_VALUE=$(tr -d '\r\n' < VERSION)
+          if [[ "${GITHUB_REF_NAME#v}" != "$VERSION_VALUE" ]]; then
+            echo "Tag '$GITHUB_REF_NAME' does not match VERSION '$VERSION_VALUE'." >&2
+            exit 1
+          fi
+
+      - name: Run PHP API tests
+        run: vendor/bin/phpunit --colors=never

From a84f2407a332043a5ec243b46a7abb91c8bd5e40 Mon Sep 17 00:00:00 2001
From: Andrew Masiye <amasiye313@gmail.com>
Date: Thu, 6 Aug 2026 15:03:56 +0200
Subject: [PATCH 3/3] fix(ci): publish the PHPUnit test configuration

---
 .github/workflows/ci.yml |  2 +-
 phpunit.xml.dist         | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)
 create mode 100644 phpunit.xml.dist

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 543ec58..2d2095f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -56,4 +56,4 @@ jobs:
           fi
 
       - name: Run PHP API tests
-        run: vendor/bin/phpunit --colors=never
+        run: composer test -- --colors=never
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
new file mode 100644
index 0000000..cf75526
--- /dev/null
+++ b/phpunit.xml.dist
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.0/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         cacheDirectory=".phpunit.cache">
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>