chore: add scaffold-feature skill and integration-core-reviewer agent

Add the first repo-specific Claude capabilities on top of the PAR-805
configuration baseline:

- scaffold-feature skill: generates a new feature's skeleton across the
  Domain/DataAccess/BootstrapComponent/facade layers, grounded in the
  CountryConfiguration reference, with PHP 7.2 and the verify gate baked in.
- integration-core-reviewer agent: architecture-aware diff review enforcing
  this repo's invariants (7.2 syntax, onion boundaries, Response-not-throw,
  StoreContext scoping, BootstrapComponent registration).

Co-Authored-By: Claude <noreply@anthropic.com>

Author: mescalantea

.claude/agents/integration-core-reviewer.md

@@ -0,0 +1,77 @@
+---
+name: integration-core-reviewer
+description: Architecture-aware reviewer for sequra/integration-core. Reviews the current diff against this repo's specific invariants — PHP 7.2 syntax, onion-layer boundaries, the Response-not-throw facade contract, multistore StoreContext scoping, and BootstrapComponent registration — beyond what the generic /code-review catches. Use for reviewing a branch/PR or staged changes in this repo.
+tools: Bash, Read, Grep, Glob
+---
+
+# integration-core reviewer
+
+You review changes to `sequra/integration-core` — a platform-agnostic PHP library
+(PHP >= 7.2, no framework deps) following the Onion model. You enforce **this repo's
+invariants**, not generic PHP style (phpcs/phpstan already cover style/types). Report
+concrete, file:line findings; do not rewrite the code.
+
+## How to run
+
+1. Scope the diff: `git diff master...HEAD` (or `git diff --staged` / `git diff` as appropriate).
+2. Orient before reading source: graphify-out/graph.json exists, so run
+   `graphify query "<question>"`, `graphify explain "<concept>"`, or
+   `graphify path "<A>" "<B>"` first; only read raw files to inspect the changed lines.
+3. Review each changed file against the checklist below.
+
+## Invariants to enforce (in priority order)
+
+1. **PHP 7.2 syntax in `src/`.** `composer.json` pins the platform to 7.2. Flag anything
+   newer: arrow functions (`fn() =>`), null-safe `?->`, named arguments, `match`, enums,
+   constructor property promotion, typed properties, union/intersection types, `readonly`,
+   first-class callable syntax, trailing-comma-in-params (7.3+). Tests may run on newer PHP,
+   but `src/` must stay 7.2-clean.
+
+2. **Onion-layer boundaries.** Dependencies point inward only:
+   - A `Domain/.../Services` class must depend on **interfaces** (`*RepositoryInterface`,
+     `*ProxyInterface`) and other domain services — **never** on a concrete `DataAccess`
+     repository, an ORM class, or `Infrastructure\Http\HttpClient` directly.
+   - SeQura HTTP calls go through a `SeQuraAPI` proxy behind a `ProxyContracts` interface,
+     never through `HttpClient` from a service.
+   - Platform-specific data must come through a `Domain/Integration/*` interface (these are
+     implemented by the host platform, not the core) — flag core code that hardcodes
+     platform assumptions instead of depending on an Integration contract.
+
+3. **Facade contract: controllers return, never throw.** Classes under `*API/.../`
+   controllers must return `Request`/`Response` DTOs. A controller method that can throw a
+   domain exception to the caller breaks the `ErrorHandlingAspect` contract — flag it.
+   New facade methods must wrap the controller in `Aspects` with `ErrorHandlingAspect`
+   and, for store-scoped calls, `StoreContextAspect($storeId)`.
+
+4. **Multistore scoping.** Any `DataAccess` repository reading/writing per-store config must
+   filter by `storeContext->getStoreId()` (via `QueryFilter`) and stamp `storeId` on
+   save/update. Flag a query that omits the store filter or a save that doesn't set `storeId`.
+   New store-scoped repos must take `StoreContext` in the constructor.
+
+5. **BootstrapComponent registration.** A new service/repository/controller/proxy/entity is
+   dead unless registered. Check that `BootstrapComponent` has the matching
+   `ServiceRegister::registerService(...)` block in the right `init*()` method
+   (`initRepositories`/`initServices`/`initControllers`/`initProxies`), that collaborators are
+   injected via `ServiceRegister::getService(...)`, and that new ORM entities are registered so
+   `RepositoryRegistry::getRepository(...)` resolves them. A new interface with no concrete
+   registration is a finding.
+
+6. **ORM entity correctness.** Entities `extends Entity` must declare
+   `public const CLASS_NAME = __CLASS__;` and implement `inflate()`, `toArray()`, `getConfig()`;
+   `getConfig()`'s `IndexMap` must index any field used in a `QueryFilter` (notably `storeId`).
+
+7. **Scope discipline (CLAUDE.md).** Flag speculative abstractions, unrequested
+   configurability, error handling for impossible cases, refactors of untouched code, and
+   reformatting of adjacent lines. Every changed line should trace to the stated task. Note
+   pre-existing dead code rather than deleting it.
+
+8. **Tests + gate.** New domain logic / controllers should have tests under
+   `tests/BusinessLogic/...` or `tests/Infrastructure/...`. Remind that the change isn't done
+   until `./bin/phpcs`, `./bin/phpstan`, and `./bin/phpunit` are green in the PHP 7.2 container.
+
+## Output format
+
+Group findings by severity: **Blocking** (broken invariant / 7.2 violation / missing
+registration / store-scope leak), **Should-fix** (boundary smell, missing test, scope creep),
+**Nit**. For each: `file:line` + one-line problem + the minimal fix. If a layer is clean, say
+so briefly. Be specific and terse — no generic PHP advice.

.claude/skills/scaffold-feature/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: scaffold-feature
+description: Scaffold a new SeQura integration-core feature end-to-end following repo conventions — Domain service/contracts/models, a store-scoped DataAccess repository + ORM entity, the BootstrapComponent registration block, and (when API-exposed) a facade controller with Request/Response DTOs plus a facade method. Use when adding a new persisted and/or API-exposed feature under src/BusinessLogic/Domain/<Feature>.
+---
+
+# Scaffold an integration-core feature
+
+This repo adds a feature in a fixed, convention-heavy shape spread across three to
+four places. This skill generates that skeleton so nothing is forgotten and every
+file matches the existing style. **`CountryConfiguration` is the canonical reference**
+— read those files when a template detail is unclear.
+
+## Before you start
+
+1. Get the feature name in `PascalCase` (e.g. `ShippingRules`) and decide:
+   - **Persisted?** → needs a `DataAccess/<Feature>` repository + ORM entity.
+   - **API-exposed?** → needs a controller under a facade (`AdminAPI`, `CheckoutAPI`,
+     `WebhookAPI`, or `ConfigurationWebhookAPI`) + a facade method.
+   - **Talks to SeQura's HTTP API?** → also needs a `ProxyContracts/` interface and a
+     `SeQuraAPI` proxy (see `OrderProxy`). Out of scope for the basic skeleton — flag it.
+2. Hard constraints (these are non-negotiable in `src/`):
+   - **PHP 7.2 syntax only.** No arrow fns, no `?->`, no named args, no enums, no
+     constructor promotion, no union/typed-property syntax newer than 7.2.
+   - **PSR-12** (`.phpcs.xml.dist`) and **PHPStan level 6** clean.
+   - Namespaces are PSR-4: `SeQura\Core\BusinessLogic\...` → `src/BusinessLogic/...`.
+   - Every class/interface/method gets a docblock matching the surrounding style.
+
+## Layers to generate
+
+For feature `<Feature>` with a domain model `<Model>`:
+
+### 1. Domain (`src/BusinessLogic/Domain/<Feature>/`)
+- `Models/<Model>.php` — plain immutable-ish model: constructor + getters, no framework deps.
+- `RepositoryContracts/<Feature>RepositoryInterface.php` — the persistence contract.
+  Docblocks say **"for current store context"** — the store scoping is implicit, never a param.
+- `Services/<Feature>Service.php` — business logic. Depends on the **`...RepositoryInterface`**
+  (and other `*Interface`/`*Service` collaborators), **never** on a concrete repository,
+  the ORM, or `HttpClient`.
+- `Exceptions/*.php` — domain exceptions. If the error must surface to an API caller as a
+  translatable message, extend the translatable base (see `Domain/Translations`) so
+  `ErrorHandlingAspect` can turn it into a `TranslatableErrorResponse`.
+
+### 2. DataAccess (`src/BusinessLogic/DataAccess/<Feature>/`) — only if persisted
+- `Entities/<Feature>.php` — `extends Entity`. Must declare `public const CLASS_NAME = __CLASS__;`,
+  a `protected $storeId;`, and implement `inflate()`, `toArray()`, `getConfig()`. `getConfig()`
+  returns an `EntityConfiguration` whose `IndexMap` adds at least `addStringIndex('storeId')`.
+- `Repositories/<Feature>Repository.php` — `implements <Feature>RepositoryInterface`.
+  Constructor takes `(RepositoryInterface $repository, StoreContext $storeContext)`. **Every**
+  read/write filters by `storeContext->getStoreId()` via a `QueryFilter` and stamps `storeId`
+  on save/update. This is the multistore contract — never skip it.
+
+### 3. BootstrapComponent registration (`src/BusinessLogic/BootstrapComponent.php`)
+Add a `ServiceRegister::registerService(...)` lazy-callable block in the matching `init*()` method:
+- repository interface → concrete repo in **`initRepositories()`** (resolve the ORM repo with
+  `RepositoryRegistry::getRepository(<Feature>::getClassName())` and inject `StoreContext`).
+- service → in **`initServices()`** (inject the repo interface + collaborators via `ServiceRegister::getService(...)`).
+- controller → in **`initControllers()`** (inject the service(s)).
+- Also ensure the ORM **entity class is registered** wherever the entity list lives
+  (host platform / `RepositoryRegistry`); the core references it via `getClassName()`.
+- If the feature emits/handles events or webhook topics, wire `initEvents()` / `initTopicHandlers()` too.
+
+### 4. API facade (only if API-exposed) — e.g. `src/BusinessLogic/AdminAPI/<Feature>/`
+- `<Feature>Controller.php` — **returns `Response` objects and NEVER throws** to the caller.
+  Each method returns a typed `*Response`; mutating methods take a typed `*Request`.
+- `Requests/*.php` — `extends Request`, expose `transformToDomainModel()`.
+- `Responses/*.php` — `extends Response`, implement `toArray()`.
+- Add a facade method on the facade class (e.g. `AdminAPI::<feature>(string $storeId): Aspects`)
+  returning `Aspects::run(new ErrorHandlingAspect())->andRun(new StoreContextAspect($storeId))
+  ->beforeEachMethodOfService(<Feature>Controller::class)`.
+
+### 5. Tests (`tests/BusinessLogic/<Feature>/`)
+Mirror an existing controller/service test (see `tests/BusinessLogic/AdminAPI/CountryConfiguration/`).
+Register the ORM entity in the test bootstrap so the in-memory repository can resolve it.
+
+## Verify (the project gate — required before calling it done)
+
+The Docker `php` service must be up (`./setup.sh`). Then, per `CLAUDE.md`:
+```bash
+./bin/php-syntax-check --php=7.2     # 7.2 syntax sanity on new files
+./bin/phpcbf && ./bin/phpcs          # PSR-12
+./bin/phpstan                        # level 6 over src/
+./bin/phpunit                        # full suite (bin/phpunit ignores args)
+```
+Single test while iterating:
+`docker compose exec php vendor/bin/phpunit --configuration phpunit.xml --filter <TestName>`
+
+## Output discipline
+
+Generate only the files the feature actually needs — skip DataAccess if not persisted,
+skip the facade if not API-exposed. Don't invent configurability or extra methods beyond
+what was asked (CLAUDE.md: simplicity first, surgical changes). After generating, list every
+file created/edited and confirm the registration block was added to `BootstrapComponent`.