Add AGENTS.md, point CLAUDE.md files at it

Merge pull request 'Bump version to 1.5.6' (#196 ) from release/bump-1.5.6 into main
Reviewed-on: #196
2026-09-16 11:58:19 -03:00 · 2026-08-25 02:22:10 +00:00 · 2026-08-25 02:20:56 +00:00 · 2026-08-25 02:18:36 +00:00 · 2026-08-24 23:17:33 -03:00 · 2026-08-24 23:15:01 -03:00
12 changed files with 2757 additions and 164 deletions
@@ -7,56 +7,31 @@ on:
      - develop
  pull_request:

+# Jobs that need PHP run inside the shared CI images maintained in the
+# Unsupervised/ci-php repository. PHP, Composer, the intl and zip extensions
+# and the GNU CLI tools are already in the image, so there is no toolchain
+# setup step in any job here.
+#
+# The registry path is written out at each use because
+# jobs.<id>.container.image cannot read the `env` context.
+
 jobs:
-  # PHPCS and PHPStan share a job so the two of them draw once on Setup PHP
-  # rather than twice. That step is slow and intermittently fails on 8.3
-  # (see #178), so every job that can be folded into another is one less
-  # chance for a run to fall over. They run as separate steps, and PHPCS
-  # failing stops the job before PHPStan reports.
-  quality:
-    name: Coding Standards & Static Analysis
+  phpcs:
+    name: Coding Standards
    runs-on: ubuntu-latest
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:8.3
    steps:
      - uses: actions/checkout@v4

-      # setup-php installs PHP 8.3+ through php-builder, which apt-installs ~70
-      # -dev packages before unpacking the build (#178). Ubuntu's image deletes
-      # the .debs after install, so every job re-downloads them. Keeping them
-      # and restoring them from the cache server, which lives in the cluster,
-      # turns a WAN download into a local one.
-      #
-      # Keyed per PHP version because the install path differs by version and
-      # the package sets are not interchangeable: 8.3+ pulls the ~70 -dev
-      # packages through php-builder, while 8.1 and 8.2 come from the ondrej
-      # PPA as a handful of runtime packages. Sharing one key across both lets
-      # whichever job finishes first decide what the others restore, and 8.1 is
-      # always first.
-      #
-      # Only the .debs are cached, never /var/lib/apt/lists — a stale index is
-      # how you get 404s mid-install.
-      - name: Keep downloaded .debs
-        run: |
-          sudo rm -f /etc/apt/apt.conf.d/docker-clean
-          echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' \
-            | sudo tee /etc/apt/apt.conf.d/99keep-downloaded-packages >/dev/null
-
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: /var/cache/apt/archives/*.deb
-          key: apt-php8.3-${{ runner.arch }}-v1
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.3'
-          tools: composer:v2
-
+      # COMPOSER_HOME is /composer in the image, so that is where the
+      # download cache lives. composer.lock is what fingerprints the
+      # dependency set.
      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
-          path: ~/.composer/cache
-          key: composer-${{ hashFiles('composer.json') }}
+          path: /composer/cache
+          key: composer-${{ hashFiles('composer.lock') }}

      - name: Install dependencies
        run: composer install --prefer-dist --no-progress --no-interaction
@@ -64,15 +39,36 @@ jobs:
      - name: Run PHPCS
        run: composer cs

+  phpstan:
+    name: Static Analysis
+    runs-on: ubuntu-latest
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:8.3
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache Composer packages
+        uses: actions/cache@v4
+        with:
+          path: /composer/cache
+          key: composer-${{ hashFiles('composer.lock') }}
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+
      - name: Run PHPStan
        run: composer lint

  test:
    name: Tests (PHP ${{ matrix.php }})
    runs-on: ubuntu-latest
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:${{ matrix.php }}
    strategy:
      fail-fast: false
      matrix:
+        # A version can only be added here once ci-php publishes the matching
+        # tag.
        php:
          - '8.1'
          - '8.2'
@@ -81,46 +77,11 @@ jobs:
    steps:
      - uses: actions/checkout@v4

-      # setup-php installs PHP 8.3+ through php-builder, which apt-installs ~70
-      # -dev packages before unpacking the build (#178). Ubuntu's image deletes
-      # the .debs after install, so every job re-downloads them. Keeping them
-      # and restoring them from the cache server, which lives in the cluster,
-      # turns a WAN download into a local one.
-      #
-      # Keyed per PHP version because the install path differs by version and
-      # the package sets are not interchangeable: 8.3+ pulls the ~70 -dev
-      # packages through php-builder, while 8.1 and 8.2 come from the ondrej
-      # PPA as a handful of runtime packages. Sharing one key across both lets
-      # whichever job finishes first decide what the others restore, and 8.1 is
-      # always first.
-      #
-      # Only the .debs are cached, never /var/lib/apt/lists — a stale index is
-      # how you get 404s mid-install.
-      - name: Keep downloaded .debs
-        run: |
-          sudo rm -f /etc/apt/apt.conf.d/docker-clean
-          echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' \
-            | sudo tee /etc/apt/apt.conf.d/99keep-downloaded-packages >/dev/null
-
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: /var/cache/apt/archives/*.deb
-          key: apt-php${{ matrix.php }}-${{ runner.arch }}-v1
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php }}
-          extensions: mbstring, intl
-          coverage: none
-          tools: composer:v2
-
      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
-          path: ~/.composer/cache
-          key: ${{ matrix.php }}-composer-${{ hashFiles('composer.json') }}
+          path: /composer/cache
+          key: ${{ matrix.php }}-composer-${{ hashFiles('composer.lock') }}

      - name: Install dependencies
        run: composer install --prefer-dist --no-progress --no-interaction
@@ -128,6 +89,8 @@ jobs:
      - name: Run PHPUnit
        run: composer test

+  # Runs on the runner image rather than a container: it needs no PHP, and it
+  # uses GNU grep's --include.
  no-debug:
    name: No Debug Code
    runs-on: ubuntu-latest
@@ -144,46 +107,15 @@ jobs:
  build:
    name: Build Plugin Zip
    runs-on: ubuntu-latest
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:8.3
    # Only build a shippable artifact once changes land on main, and only
    # after the quality gates pass.
-    needs: [quality, test, no-debug]
+    needs: [phpcs, phpstan, test, no-debug]
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4

-      # setup-php installs PHP 8.3+ through php-builder, which apt-installs ~70
-      # -dev packages before unpacking the build (#178). Ubuntu's image deletes
-      # the .debs after install, so every job re-downloads them. Keeping them
-      # and restoring them from the cache server, which lives in the cluster,
-      # turns a WAN download into a local one.
-      #
-      # Keyed per PHP version because the install path differs by version and
-      # the package sets are not interchangeable: 8.3+ pulls the ~70 -dev
-      # packages through php-builder, while 8.1 and 8.2 come from the ondrej
-      # PPA as a handful of runtime packages. Sharing one key across both lets
-      # whichever job finishes first decide what the others restore, and 8.1 is
-      # always first.
-      #
-      # Only the .debs are cached, never /var/lib/apt/lists — a stale index is
-      # how you get 404s mid-install.
-      - name: Keep downloaded .debs
-        run: |
-          sudo rm -f /etc/apt/apt.conf.d/docker-clean
-          echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' \
-            | sudo tee /etc/apt/apt.conf.d/99keep-downloaded-packages >/dev/null
-
-      - name: Cache apt packages
-        uses: actions/cache@v4
-        with:
-          path: /var/cache/apt/archives/*.deb
-          key: apt-php8.3-${{ runner.arch }}-v1
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.3'
-          tools: composer:v2
-
      - name: Build plugin zip
        run: composer build

@@ -15,15 +15,13 @@ jobs:
  release:
    name: Build and Publish Release
    runs-on: ubuntu-latest
+    # The shared CI image carries composer, curl, jq and the GNU coreutils
+    # the steps below shell out to. See docs/ci.md.
+    container:
+      image: git.unsupervised.ca/unsupervised/ci-php:8.3
    steps:
      - uses: actions/checkout@v4

-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.3'
-          tools: composer:v2
-
      # A tag that disagrees with the plugin header would make sites see a
      # phantom update forever (or never see a real one), so fail fast.
      - name: Verify tag matches plugin version
@@ -37,6 +35,14 @@ jobs:
          fi
          echo "version=${header_version}" >> "$GITHUB_OUTPUT"

+      # COMPOSER_HOME is /composer in the image, so that is where the
+      # download cache lives.
+      - name: Cache Composer packages
+        uses: actions/cache@v4
+        with:
+          path: /composer/cache
+          key: composer-${{ hashFiles('composer.lock') }}
+
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress --no-interaction

@@ -1,5 +1,4 @@
 vendor/
-composer.lock
 coverage/
 .phpunit.result.cache
 *.log
@@ -0,0 +1,47 @@
+# AGENTS.md
+
+## Commands
+
+```bash
+composer install
+composer test                     # PHPUnit — run after every code change
+composer lint                     # PHPStan (level 10, `src/` only)
+composer cs                       # PHPCS (WordPress standard + exclusions in phpcs.xml.dist)
+composer cs:fix                   # auto-fix coding standards
+composer build                    # -> dist/unsupervised-schedular-<version>.zip
+
+./vendor/bin/phpunit tests/Unit/Offering/OfferingRepositoryTest.php
+./vendor/bin/phpunit --filter testInsertReturnsId
+```
+
+CI (`.gitea/workflows/ci.yml`): `phpcs`, `phpstan`, `test` (PHP 8.1/8.2/8.3/8.5), `no-debug`. Write only PHP 8.1-compatible syntax. No `var_dump|var_export|print_r|error_log|dd|dump(` in `src/` — CI greps and fails.
+
+## Architecture
+
+- WordPress plugin, no front-end build (vanilla JS/CSS in `assets/`). PSR-4 `Unsupervised\Schedular\` -> `src/`.
+- **Package-by-domain:** `src/<Domain>/` (Auth, Availability, Booking, GroupClass, Guardian, Offering, Payment, Policy, Registration) owns its repos, services, endpoints, pages. Cross-cutting wiring lives directly in `src/`: `Plugin`, `Installer`, `Schema`, `AdminMenu`, `RestRegistrar`, `ShortcodeRegistrar`, `BlockRegistrar`, `Val`.
+- Entry: `unsupervised-schedular.php` -> `Plugin::boot()` (wires all dependencies). **Slug is `schedular`, not `scheduler`** — filename, text domain (`unsupervised-schedular`), option `us_schedular_version`, table prefix `us_`. Never "fix" the spelling.
+- REST: `/wp-json/us-scheduler/v1/`, `permission_callback` uses capability checks, never role names.
+- DB: custom `us_*` tables via `dbDelta`; `Schema::tables()` is the source of truth. **All `$wpdb` access inside repository classes only.**
+- `src/Val.php` coerces untyped WP input (`Val::int()`, `Val::string()`, `...OrNull`, etc.). For PHPCS, `Val::int/float/bool/...` count as unslashing passthrough only — still wrap with a real sanitizer: `absint( Val::int( $_GET['id'] ?? 0 ) )`.
+
+## Schema changes (gotcha)
+
+- `Plugin::boot()` only re-runs `Installer`/migrations when stored `us_schedular_version !== USC_VERSION`. **Bump both the `Version:` header and `USC_VERSION` in `unsupervised-schedular.php` or the change never reaches existing sites.**
+- `dbDelta` does not reliably relax column NULL-ability. Follow the existing pattern in `Plugin::boot()`: repository repair method + own `us_*` option flag (e.g. `us_questions_offering_nullable`), not the version gate.
+
+## Tests
+
+- Brain Monkey + Mockery, no live WP. All test classes extend `tests/Unit/TestCase.php` (handles `Monkey\setUp/tearDown`, stubs translations/escaping/`checked`/`selected`).
+- Mirror layout: `tests/Unit/<Domain>/` mirrors `src/<Domain>/`.
+  - `Functions\when('fn')->alias(fn() => ...)` (never `returnUsing()`); `->justReturn($v)` for constants.
+  - Use `when()` not `expect()` for argument-dependent routing.
+  - No `\Mockery::type()` inside plain arrays passed to `with()` — use `\Mockery::on()` or `\Mockery::any()`.
+  - `$wpdb` mock needs `$mock->prefix = 'wp_'` as a property.
+
+## Adding a feature
+
+1. Spec first: `docs/features/<feature-name>.md` (data model, API, classes, test paths).
+2. Code in `src/<Domain>/`; templates in `templates/` if needed.
+3. Tests in `tests/Unit/<Domain>/`.
+4. `composer test` must pass (also `composer lint` + `composer cs` before finishing).
@@ -11,6 +11,13 @@ When a `v*` tag is pushed, `.gitea/workflows/release.yml` publishes the matching
 the plugin to the next patch version and adds a fresh section here for it. Record
 each change under the current top section as you work.

+## [1.5.6]
+
+## [1.5.5]
+
+### Changed
+- **Payments moved up to version 21 of Stripe's PHP library**, from version 17. Being four major versions behind also meant asking Stripe to behave like an older version of its API; the plugin now uses API version `2026-07-29.dahlia`. Taking a card payment and handling a webhook are unchanged — the same charge is raised, the same events are honoured, and a forged webhook is still rejected. Nothing to do on your side.
+
 ## [1.5.4]

 ### Fixed
@@ -1,31 +1,3 @@
 # CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Commands
-
-**Run `composer test` after every code change before considering a task complete.**
-
-## Architecture
-
-### Code organisation
-**Code is organised package-by-domain.** Each domain package under `src/<Domain>/` contains everything related to that domain: value objects, repositories, controllers, REST endpoints, and shortcode pages. Cross-cutting wiring classes (Plugin, AdminMenu, RestRegistrar, ShortcodeRegistrar, Schema) live directly under `src/`.
-
-### Data Storage
-Custom database tables are created via `dbDelta` on activation; `Schema.php` holds the SQL.
-
-All database access goes through repository classes within their domain package. No direct `$wpdb` calls outside repositories.
-
-### REST API Namespace
-All endpoints live under `/wp-json/us-scheduler/v1/`. Permissions are enforced via `permission_callback` using capability checks (`manage_availability`, `book_lesson`), never role name checks.
-
-### Testing Approach
-Tests stub WordPress with Brain\Monkey rather than booting a real WP install. The setup and the Brain\Monkey/Mockery API gotchas are in `tests/CLAUDE.md`.
-
-### Adding a Feature
-0. **If the feature touches `Schema.php`, bump both the `Version:` header and `USC_VERSION` in `unsupervised-schedular.php`.** `Plugin::boot()` only re-runs `Installer`/`dbDelta` when the stored `us_schedular_version` differs, so a schema change without a version bump never reaches existing sites and inserts into new columns fail silently.
-1. Write the feature doc in `docs/features/<feature-name>.md` (data model, API, classes, test paths).
-2. Create a domain package under `src/<Domain>/` containing all classes for that feature.
-3. Add template(s) under `templates/` if needed.
-4. Write unit tests under `tests/Unit/<Domain>/` mirroring the `src/<Domain>/` structure.
-5. Run `composer test` — all tests must pass before the feature is complete.
+See `AGENTS.md` — it is the single source of truth for working in this repo.
@@ -23,6 +23,10 @@ INCLUDE=(
 	"$SLUG.php"
 	"uninstall.php"
 	"composer.json"
+	# Staged so the production install below resolves to the locked versions
+	# rather than whatever is newest that day. Both are deleted again before
+	# the zip is written.
+	"composer.lock"
 	"src"
 	"templates"
 	"assets"
@@ -5,7 +5,7 @@
    "license": "GPL-2.0-or-later",
    "require": {
        "php": ">=8.1",
-        "stripe/stripe-php": "^17.0"
+        "stripe/stripe-php": "^21.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^10.5",
@@ -36,6 +36,9 @@
        "build": "bash bin/build-zip.sh"
    },
    "config": {
+        "platform": {
+            "php": "8.1"
+        },
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
@@ -0,0 +1,45 @@
+# CI
+
+CI and release jobs do not install PHP. They run inside the shared images
+maintained in [Unsupervised/ci-php](https://git.unsupervised.ca/Unsupervised/ci-php):
+
+```
+git.unsupervised.ca/unsupervised/ci-php:8.1
+git.unsupervised.ca/unsupervised/ci-php:8.2
+git.unsupervised.ca/unsupervised/ci-php:8.3
+git.unsupervised.ca/unsupervised/ci-php:8.5
+```
+
+The `Unsupervised` org is public, so they pull anonymously — no registry
+credentials in any job here. What the images contain, how they are published,
+and how to add a PHP version are documented in that repository's README.
+
+## Which job runs where
+
+| Job | Runs in |
+|---|---|
+| Coding Standards (PHPCS) | `ci-php:8.3` |
+| Static Analysis (PHPStan) | `ci-php:8.3` |
+| Tests | `ci-php:${{ matrix.php }}` |
+| Build Plugin Zip | `ci-php:8.3` |
+| No Debug Code | runner image — no PHP, and it uses GNU `grep --include` |
+| Open next-version bump PR (release.yml) | runner image — no PHP |
+
+PHPCS and PHPStan are separate jobs so a coding-standards failure still lets
+the static analysis result through. They run in parallel.
+
+## Composer
+
+`composer.lock` is committed, so every job installs the same dependency set
+and two builds of the same tag ship the same vendor tree. `bin/build-zip.sh`
+stages the lock into its build directory for the same reason, then removes it
+before writing the zip.
+
+The Composer download cache lives at `/composer/cache` — `COMPOSER_HOME` is
+`/composer` in the image — and is keyed on `composer.lock`.
+
+## Adding a PHP version to the test matrix
+
+The image has to exist first. Add the version to the `php` matrix in
+`ci-php`'s `.gitea/workflows/publish.yml` and merge, then add it to the `test`
+matrix in `.gitea/workflows/ci.yml` here.
@@ -1,14 +1,3 @@
 # Writing tests

-Tests use [Brain\Monkey](https://brain-wp.github.io/BrainMonkey/) to stub WordPress functions without a full WP installation, and Mockery to mock `$wpdb` and other dependencies.
-
-All test classes extend `tests/Unit/TestCase.php`, which handles `Monkey\setUp()` / `Monkey\tearDown()` and stubs all WP translation/escape functions automatically.
-
-**Brain\Monkey API notes:**
-
- `Functions\when('fn')->alias(fn() => ...)` — stub with a closure (NOT `returnUsing()`)
- `Functions\when('fn')->justReturn($val)` — stub returning a fixed value
- `Functions\expect('fn')->once()->with(...)` — assert call count and arguments
- Use `Functions\when()` (not `Functions\expect()`) when you need argument-routing (e.g. `get_role` returning different values per argument) to avoid chaining ambiguity
- Mockery matchers (e.g. `\Mockery::type()`) inside plain PHP arrays do not work with `with()` — use `\Mockery::on(fn($arr) => ...)` or `\Mockery::any()` instead
- When mocking `$wpdb`, set `$mock->prefix = 'wp_'` explicitly — it is a public property, not a method
+See `../../AGENTS.md` (Tests section) — it is the single source of truth for working in this repo.
@@ -3,7 +3,7 @@
 * Plugin Name: Unsupervised Scheduler
 * Plugin URI:  https://git.unsupervised.ca/Unsupervised/unsupervised-scheduler
 * Description: Instructor/student lesson scheduling for WordPress.
- * Version:     1.5.4
+ * Version:     1.5.6
 * Requires at least: 6.2
 * Requires PHP: 8.1
 * Author:      Unsupervised
@@ -21,7 +21,7 @@ if (! defined('ABSPATH')) {
    exit;
 }

-define('USC_VERSION', '1.5.4');
+define('USC_VERSION', '1.5.6');
 define('USC_PLUGIN_FILE', __FILE__);
 define('USC_PLUGIN_DIR', plugin_dir_path(__FILE__));
 define('USC_PLUGIN_URL', plugin_dir_url(__FILE__));