PHPUnit suite refactor + CI overhaul

.claude/CLAUDE.md

@@ -1,94 +1,9 @@
-# CLAUDE.md
+## Working agreements
 
-## Core Principles
+- Plans → `.claude/plans/YYYY-MM-DD-<topic>.md`
+- Project memory → `.claude/memory/YYYY-MM-DD-<topic>.md` (also indexed in `.claude/memory/MEMORY.md`)
 
-### Skills-First Workflow
-
-**EVERY user request follows this sequence:**
-
-Request → Load Skills → Gather Context → Execute
-
-Skills contain critical workflows and protocols not in base context.
-Loading them first prevents missing key instructions.
-
-### Planning
-
-When creating plans, always save them to: ./claude/plans/YYYY-MM-DD-<topic>.md
-Never use the default plan location. Use the ./claude/plans/ directory.
-
-### Context Management Strategy
-
-**Central AI should conserve context to extend pre-compaction capacity**:
-
-- Delegate file explorations and low-lift tasks to sub-agents
-- Reserve context for coordination, user communication, and strategic decisions
-- For straightforward tasks with clear scope: skip heavy orchestration, execute directly
-
-**Sub-agents should maximize context collection**:
-
-- Sub-agent context windows are temporary
-- After execution, unused capacity = wasted opportunity
-- Instruct sub-agents to read all relevant files, load skills, and gather examples
-
-### Routing Decision
-
-**Direct Execution**:
-
-- Simple/bounded task with clear scope
-- Single-component changes
-- Quick fixes and trivial modifications
-
-**Sub-Agent Delegation**:
-
-- Complex/multi-phase implementations
-- Tasks requiring specialized domain expertise
-- Work that benefits from isolated context
-
-**Master Orchestrator**:
-
-- Ambiguous requirements needing research
-- Architectural decisions with wide impact
-- Multi-day features requiring session management
-
-### Operational Protocols
-
-#### Agent Coordination
-
-**Parallel** (REQUIRED when applicable):
-
-- Multiple Task tool invocations in single message
-- Independent tasks execute simultaneously
-- Bash commands run in parallel
-
-**Sequential** (ENFORCE for dependencies):
-
-- Database → API → Frontend
-- Research → Planning → Implementation
-- Implementation → Testing → Security
-
-#### Quality Self-Checks
-
-Before finalizing code, verify:
-
-- All inputs have validation
-- Authentication/authorization checks exist
-- All external calls have error handling
-- Import paths verified against existing codebase examples
-
-### Coding Best Practices
-
-**Priority Order** (when trade-offs arise):
-Correctness > Maintainability > Performance > Brevity
-
-#### Task Complexity Assessment
-
-Before starting, classify:
-
-- **Trivial** (single file, obvious fix) → execute directly
-- **Moderate** (2-5 files, clear scope) → brief planning then execute
-- **Complex** (architectural impact, ambiguous requirements) → full research first
-
-Match effort to complexity. Don't over-engineer trivial tasks or under-plan complex ones.
+@.claude/memory/MEMORY.md
 
 ## Project Overview
 
@@ -114,17 +29,17 @@ yarn format           # Auto-fix JS/CSS/PHP formatting
 
 ### PHP
 
+PHP tests run inside a Docker container via `wp-env` — you cannot run PHPUnit directly. Start the environment first with `yarn wp-env:integration start`.
+
 ```bash
-yarn test:php                           # Run PHPUnit in Docker (`yarn wp-env:integration start` required)
+yarn test:php                           # Run PHPUnit in Docker
 yarn test:php -- --filter TestClassName # Run single test class
 yarn test:php -- --filter testMethod    # Run single test method
 yarn test:php:multisite                 # Run multisite PHPUnit tests
-composer lint                              # PHPCS check
-composer lint:fix                          # PHPCS auto-fix
+composer lint                           # PHPCS check
+composer lint:fix                       # PHPCS auto-fix
 ```
 
-PHP tests run inside a Docker container via `wp-env` — you cannot run PHPUnit directly. Start the environment first with `yarn wp-env:integration start`.
-
 ### E2E Tests (Playwright)
 
 ```bash
@@ -144,11 +59,11 @@ Artifacts (screenshots, traces) are written to `tmp/artifacts/`.
 ### Environment
 
 ```bash
-yarn wp-env start                 # Start dev environment (port 8700)
-yarn wp-env:integration start     # Start PHP test environment (port 8701)
-yarn wp-env:e2e start             # Start E2E test environment (port 8702)
+yarn wp-env start                 # Dev environment (port 8700)
+yarn wp-env:integration start     # PHP test environment (port 8701)
+yarn wp-env:e2e start             # E2E test environment (port 8702)
 yarn wp-env stop                  # Stop the default dev environment
-yarn start                        # Start dev environment + hot reload dev server
+yarn start                        # Dev environment + hot reload dev server
 ```
 
 ## Architecture
@@ -157,10 +72,10 @@ yarn start                        # Start dev environment + hot reload dev serve
 
 The plugin follows an MVC pattern bootstrapped by the `Router` class in `src/bootstrap.php`, which acts as the dependency injection container. Entry point is `pdf.php` → `src/bootstrap.php`.
 
-- **`src/Controller/`** — Request handlers (18+ controllers: forms, PDF generation, settings, fonts, templates, activation, etc.)
+- **`src/Controller/`** — Request handlers (forms, PDF generation, settings, fonts, templates, activation, etc.)
 - **`src/Model/`** — Business logic (PDF rendering via mPDF, settings management, merge tags, templates)
 - **`src/View/`** — Admin UI rendering; HTML templates live in `src/templates/`
-- **`src/Helper/`** — 47+ helpers including abstract base classes for options, fields, forms, logging, and fonts
+- **`src/Helper/`** — Abstract base classes for options, fields, forms, logging, and fonts
 - **`vendor_prefixed/`** — Composer dependencies namespaced via `php-scoper` to avoid conflicts with other plugins
 
 Namespacing: all plugin code is under the `GFPDF\` namespace with PSR-4 autoloading.
@@ -188,10 +103,10 @@ Legacy jQuery code coexists with the React app; they are separate bundles and do
 ### Testing
 
 - **PHP tests**: `tests/phpunit/` mirrors `src/` structure. Extends `WP_UnitTestCase`. Mock data in `tests/phpunit/unit-tests/Mocks/`.
-- **JS tests**: `tests/js-unit/` mirrors React source structure. Uses Jest + Enzyme. Coverage threshold: 75%.
-- **E2E tests (Playwright)**: `yarn test:e2e` — config at `tools/playwright/config.ts`. Use `yarn test:e2e:playwright` for the interactive UI mode.
+- **JS tests**: `tests/js-unit/` mirrors React source structure. Uses Jest + Enzyme. Coverage threshold: 75% (branches/functions/lines/statements).
+- **E2E tests (Playwright)**: `yarn test:e2e` — config at `tools/playwright/config.ts`. Use `yarn test:e2e:debug` for the interactive UI mode.
 
-### Key Constraints
+## Key Constraints
 
 - PRs must target the `development` branch (not `main`)
 - Each PR should contain a single commit

.claude/memory/2026-05-28-pr-description-format.md

@@ -0,0 +1,32 @@
+---
+name: PR descriptions stay human-friendly
+description: Lead with prose Summary paragraphs (not bulleted Highlights with bold prefixes), "Test it", and a Test plan. Push technical details and the Claude Code attribution into a collapsed `<details><summary>More info</summary>` block. Avoid em dashes and stock LLM filler in the Summary.
+type: feedback
+---
+
+When generating or updating a PR description, the visible body should read like a human wrote it for a human reviewer:
+
+1. **Summary** as plain prose paragraphs explaining what the PR does and why it matters. Not a bulleted "Highlights:" list with `**Bold Label**` prefixes — that pattern reads as AI-written. No nested matrices, no per-file hook lists.
+2. **Try it** — a copy-pasteable code block showing how to exercise the change locally.
+3. **Test plan** — a short checklist a reviewer can tick off.
+
+Everything else — coverage tables, technical hook breakdowns, architecture notes, the `🤖 Generated with AI` attribution line — goes inside a `<details>` toggle:
+
+```markdown
+<details>
+<summary>More info</summary>
+
+...all the AI-dense detail here...
+
+🤖 Generated with AI
+
+</details>
+```
+
+**Why:** PR reviewers should be able to skim the body and know what's going on without wading through an LLM-style breakdown of every file touched. The detail is useful to *have* (especially when triaging later) but not useful *on the surface*. Hiding it inside `<details>` keeps both audiences happy.
+
+**How to apply:**
+- Applies to any `gh pr create` / `gh pr edit --body` output you generate, both at PR creation time and when updating the description later.
+- Re-flow the existing body when a PR description is already AI-dense — collapse the technical content into the toggle and write a human-friendly opener above it.
+- Don't move the Test Plan checklist into the toggle — reviewers tick it off without expanding the section.
+- In Summary text, prefer periods/colons over em dashes (`—`) and use direct verbs ("adds", "fixes", "replaces") instead of LLM filler like "proper support for" or "in lock-step with". Em dashes and richer prose are fine inside the `<details>` toggle.

.claude/memory/2026-05-28-pr-link-fixed-issues.md

@@ -0,0 +1,16 @@
+---
+name: Link fixed issues when opening a PR
+description: Before running `gh pr create`, search the repo's issues for any the PR fixes/closes and add `Closes #N` / `Fixes #N` / `Resolves #N` lines so GitHub auto-closes them on merge.
+type: feedback
+---
+
+When opening a PR, first check whether any open issues in the repo are resolved by the change. If so, link them with GitHub's closing keywords (`Closes #N`, `Fixes #N`, `Resolves #N`) in the PR body so the issues auto-close on merge.
+
+**Why:** Issues that get fixed quietly in a PR stay open after merge, clog the backlog, and need a manual cleanup pass later. Linking at open-time also tells reviewers what user-visible problem the PR is solving, which often shapes their review.
+
+**How to apply:**
+- Before `gh pr create`, run `gh issue list --repo <owner>/<repo> --state open --search "<keywords>"` (or filter by label) using terms drawn from the diff / commit messages / PR topic to surface candidates. Read the candidate issue bodies to confirm the PR genuinely resolves them (not just touches the same code area).
+- Add the closing line at the **end of the Summary section**, before "Try it" / "Test plan" / the `<details>` toggle. Format: `Closes #N — <one-line description of the issue>` (or `Fixes` / `Resolves`). One per line if there are several.
+- If the PR *relates to* but doesn't *close* an issue, use `Refs #N` (no closing keyword) so it shows up cross-linked without being auto-closed.
+- Applies to every new PR regardless of branch or scope. For existing PRs that missed this at open-time, retro-add via `gh pr edit --body` rather than dropping a separate comment — the closing keyword only works from the PR body or commit messages, not from comments.
+- This is purely about GitHub issues. Don't auto-close sibling PRs or external trackers.

.claude/memory/MEMORY.md

@@ -0,0 +1,4 @@
+# Project Memory Index
+
+- [PR Description Format](2026-05-28-pr-description-format.md) — Human-friendly Summary/Try it/Test plan up top; collapse AI-dense detail and attribution into `<details>More info</details>`
+- [Link Fixed Issues in PRs](2026-05-28-pr-link-fixed-issues.md) — Before `gh pr create`, find issues the PR resolves and add `Closes #N` lines to the Summary

.github/README.md

@@ -1,8 +1,6 @@
 Gravity PDF
 ==========================
 
-[![codecov](https://codecov.io/gh/GravityPDF/gravity-pdf/branch/development/graph/badge.svg)](https://codecov.io/gh/GravityPDF/gravity-pdf)
-
 Gravity PDF is a GPLv2-licensed WordPress plugin that allows you to automatically generate, email and download PDF documents using the popular form-builder plugin, [Gravity Forms](https://gpdf.us/gf) (affiliate link). Find out more about Gravity PDF at [https://gravitypdf.com](https://gravitypdf.com/).
 
 # About
@@ -64,8 +62,8 @@ The automated test suite can only be run using Docker.
 Useful commands include:
 
 ```
-yarn test:e2e
-yarn test:e2e:headless
+yarn test:e2e            # headless run
+yarn test:e2e:debug      # interactive Playwright UI
 ```
 
 ### PHPUnit