Merge feature/phparkitect: PHPArkitect integration + SSoT rule migration

Adds PHPArkitect as the on-by-default architecture-rules tool (generic-safe
default tier + opt-in optional/symfony tiers), migrates structural type-suffix
naming out of PHPStan into arkitect (SSoT), documents the PHPArkitect-vs-PHPStan
placement decision, and lands all multi-lens audit fixes. Self-test green.

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

Author: LTSCommerce

.claude/agents/php-qa-ci_phpstan-rule-creator.md

@@ -9,6 +9,15 @@ tools: Read, Edit, Glob, Grep, Write
 You are a PHPStan rule creator agent. Your job is to create custom PHPStan rules that detect
 specific bug patterns at static analysis level, preventing entire classes of bugs from recurring.
 
+## Precondition — confirm the engine first
+
+Before authoring a PHPStan rule, confirm the pattern is NOT a structural naming /
+namespace-layering / dependency-direction convention — those belong in PHPArkitect
+(`qaConfig/phparkitect.php` or a shipped tier), never PHPStan. If it IS structural, STOP
+and tell the caller to use PHPArkitect instead; do not write the rule. Only proceed for
+method-level / semantic detection arkitect cannot express. See the README decision guide
+"Where does a rule belong — PHPArkitect or PHPStan?".
+
 ## Your Role
 
 You create custom PHPStan rules as part of the "Defence Before Fix" strategy:

.claude/skills/defence-before-fix/SKILL.md

@@ -108,7 +108,22 @@ This phase is primarily manual/guided. Help the user by:
 
 ## Phase 2: DETECT (Static Analysis)
 
-**Goal:** Create a PHPStan rule that catches ALL instances of the bug pattern.
+**Goal:** Create a rule that catches ALL instances of the bug pattern.
+
+### Step 0: Choose the engine first
+
+Before writing a PHPStan rule, decide which engine owns the convention:
+
+- **Structural conventions** — class/interface/enum/trait **NAMING**, namespace
+  **LAYERING**, **DEPENDENCY** direction — belong in **PHPArkitect** (extend a tier or
+  the project's `qaConfig/phparkitect.php`), NOT PHPStan.
+- Only **finer-grained / method-level / semantic** patterns (which PHPArkitect cannot
+  express) become PHPStan rules.
+- **NEVER enforce one convention in both engines** — migrate, don't duplicate.
+
+Decision guide (SSoT): [README "Where does a rule belong"](../../../README.md#where-does-a-rule-belong--phparkitect-or-phpstan).
+If the pattern is structural, do the rest of this phase against arkitect; only continue to
+the PHPStan rule creator below for patterns arkitect cannot express.
 
 ### Step 1: Launch the Rule Creator Agent
 

CLAUDE.md

@@ -92,7 +92,8 @@ The pipeline runs tools in 4 distinct phases:
 ### Phase 3: Static Analysis Tools
 
 10. **PHPStan** (`phpstan`) - Static analysis tool
-11. **SensitiveParameter Usage** (`sensitiveParameterUsage`) - Always-on security baseline: fails if `#[\SensitiveParameter]` is used nowhere in `src/`. Opt out per-project with `export useSensitiveParameterCheck=0`.
+11. **PHPArkitect** (`phpArkitect`) - Architecture rules (class naming, namespace layering, dependency direction). On by default; applies a generic-safe baseline and is composable/overridable per project. Opt out with `export useArkitect=0`. See the [PHPArkitect section in README.md](README.md#phparkitect-architecture-rules).
+12. **SensitiveParameter Usage** (`sensitiveParameterUsage`) - Always-on security baseline: fails if `#[\SensitiveParameter]` is used nowhere in `src/`. Opt out per-project with `export useSensitiveParameterCheck=0`.
 
 ### Phase 4: Testing Tools
 
@@ -514,6 +515,18 @@ cp vendor/lts/php-qa-ci/configDefaults/generic/php_cs.php qaConfig/
   - Extensible with custom rules
   - Understands PHPDoc annotations
 
+### PHPArkitect
+
+- **Purpose**: Enforce architectural/structural rules — class-naming conventions, namespace layering, dependency direction — that PHPStan expresses awkwardly
+- **Tool**: [@includes/generic/phpArkitect.inc.bash](includes/generic/phpArkitect.inc.bash)
+- **PHAR**: `vendor-phar/phparkitect.phar` (PHIVE, key `47CD54B6398FE21B3709D0A4D9C905CED1932CA2`, short id `D9C905CED1932CA2`)
+- **Entry config (default)**: [@configDefaults/generic/phparkitect.php](configDefaults/generic/phparkitect.php) — applies the default tier to the detected source dir when a project has no `qaConfig/phparkitect.php`
+- **Rule tiers**: `phparkitect-rules-default.php` (on by default), `phparkitect-rules-optional.php` + `phparkitect-rules-optional-symfony.php` (opt-in) under [@configDefaults/generic](configDefaults/generic)
+- **Project template**: [@templates/qaConfig-phparkitect.php](templates/qaConfig-phparkitect.php)
+- **How it works**: parses each class into an AST and matches expressions (naming, dependencies); rules and the paths to scan are defined inside the config (so `-p` does not apply). The pipeline passes `--autoload` and exports the tier paths + detected `srcDir` as env vars
+- **Where a rule belongs (PHPArkitect vs PHPStan)**: arkitect by default for structural rules; upgrade to a PHPStan rule only for finer-grained / method-level / semantic detection arkitect cannot express. **Never enforce one convention in both engines** — migrate, don't duplicate (SSoT). Full decision guide: [README.md "Where does a rule belong"](README.md#where-does-a-rule-belong--phparkitect-or-phpstan)
+- **Full usage** (tiers, extend/replace/customise, disable): see the [PHPArkitect section in README.md](README.md#phparkitect-architecture-rules)
+
 ### PHPUnit
 
 - **Purpose**: Unit testing framework

README.md

@@ -71,10 +71,11 @@ PHP-QA-CI orchestrates multiple PHP quality tools across four phases:
 
 **Phase 3 -- Static Analysis:**
 9\. PHPStan (level max)
+10\. PHPArkitect (architecture rules; on by default, `useArkitect=0` to disable)
 
 **Phase 4 -- Testing:**
-10\. PHPUnit
-11\. Infection (mutation testing, optional, requires Xdebug)
+11\. PHPUnit
+12\. Infection (mutation testing, optional, requires Xdebug)
 
 **Post-Success:** PHPLoc (stats only, cannot fail)
 
@@ -84,12 +85,87 @@ See [Pipeline Architecture](./docs/pipeline.md) for full details.
 
 PHP-QA-CI uses a hybrid approach to tool delivery:
 
-- **PHARs** (via [PHIVE](https://phar.io/)): PHPStan, PHP CS Fixer, Infection, Composer Require Checker -- delivered in `vendor-phar/`
+- **PHARs** (via [PHIVE](https://phar.io/)): PHPStan, PHP CS Fixer, Infection, Composer Require Checker, PHPArkitect (PHIVE key `D9C905CED1932CA2` — the trailing 16 chars of the full fingerprint `47CD54B6398FE21B3709D0A4D9C905CED1932CA2`, which is what `tool-install.bash` pins) -- delivered in `vendor-phar/`
 - **Composer dependencies**: PHPUnit, phpstan-strict-rules, phpstan-phpunit, parallel-lint
 - **Isolated Composer project**: Rector -- in `tools/rector/` with its own `composer.json` to prevent dependency conflicts
 
 The `phpstan/phpstan` package is in the `replace` section of `composer.json` since PHPStan is provided via PHAR. This prevents version conflicts when consuming projects also require PHPStan extensions.
 
+## PHPArkitect (architecture rules)
+
+[PHPArkitect](https://github.com/phparkitect/arkitect) enforces *structural*
+rules that PHPStan expresses awkwardly: class-naming conventions, namespace
+layering, and dependency direction. It runs in Phase 3 and is **on by default**.
+
+### Where does a rule belong — PHPArkitect or PHPStan?
+
+**Default to PHPArkitect for structural rules. Upgrade to a PHPStan rule only when
+you need finer-grained, method-level, or semantic detection that arkitect cannot
+express.**
+
+- **PHPArkitect (the default)** reasons about a class's *identity*: its kind
+  (interface / enum / trait / class), its name, the namespace it sits in, and its
+  ancestry. Reach for it for naming conventions, namespace layering, and
+  dependency direction.
+- **PHPStan (the upgrade)** reasons about *code*. Move up to a PHPStan rule only
+  when the check needs something arkitect cannot see or say:
+  - a **method-level** predicate — e.g. "the class has a public `__invoke`";
+  - **"any of N name patterns, except an allow-list"** — arkitect's
+    `HaveNameMatching` is a single glob with no OR / except composite;
+  - a **type-kind carve-out** in a dependency rule — e.g. allow generated *enums*
+    but forbid generated *objects*; `NotDependsOnTheseNamespaces` has no type-kind
+    awareness;
+  - any **behavioural / semantic** check — type bans, call-site shape,
+    docblock-driven rules, loose comparison, nested ternary.
+
+**Single Source of Truth — never enforce one convention in both engines.** Adding
+arkitect is *not* purely additive: when a structural convention already lives in a
+PHPStan rule, **migrate** it to arkitect (and delete the PHPStan rule) rather than
+running both. Two engines enforcing one rule is a defect — duplicated failure
+messages, drift between them, and double maintenance. (The shipped Interface / Enum /
+Trait suffix convention was migrated exactly this way: it used to be the PHPStan
+`RequireTypeSuffixRule` and is now owned solely by the default arkitect tier.)
+
+Rules are organised in tiers (mirroring the `rules-default` / `rules-optional`
+PHPStan neon split). php-qa-ci ships each as a file returning a list of arkitect
+`ArchRule` objects, and the pipeline exports the resolved path of each so a
+project config can compose them without knowing the vendor layout:
+
+| Tier                                 | Env var                                   | Default               | Contents                                |
+| ------------------------------------ | ----------------------------------------- | --------------------- | --------------------------------------- |
+| `phparkitect-rules-default`          | `PHPQACI_ARKITECT_RULES_DEFAULT`          | **on**, every project | Interface / Enum / Trait name suffixes  |
+| `phparkitect-rules-optional`         | `PHPQACI_ARKITECT_RULES_OPTIONAL`         | opt-in                | `*Exception` suffix, `Abstract*` prefix |
+| `phparkitect-rules-optional-symfony` | `PHPQACI_ARKITECT_RULES_OPTIONAL_SYMFONY` | opt-in                | `*Command`, `*Subscriber`               |
+
+The default tier matches on AST node *kind*, so it never forces arkitect to
+resolve class ancestry — that keeps it safe for any project. Ancestry-resolving
+rules (`IsA`/`Extend`/`Implement`, e.g. the `*Exception` convention) need a
+complete autoloader, so they live in the optional tier.
+
+### Troubleshooting: optional/symfony tiers need a complete autoloader
+
+The optional and symfony tiers use ancestry rules (`IsA`) that resolve a class's
+parents by **reflecting** it — so the analysed classes must be autoloadable. The
+pipeline runs arkitect with `--autoload=vendor/autoload.php`, so this is normally
+fine. But if you opt into these tiers and your autoloader is incomplete, `IsA`
+rules **silently match nothing** — arkitect reports "No violations" (a false
+green) rather than failing. (A genuine crash — exit > 1 — instead means a broken
+config or an unparseable file.) If an opted-in `*Exception`/`*Command`/`*Subscriber`
+rule never seems to fire, run `composer dump-autoload` and confirm your classes
+load.
+
+**Project usage.** With no project config, the default tier is applied to the
+detected source dir automatically. To go further, add `qaConfig/phparkitect.php`
+(copy `templates/qaConfig-phparkitect.php`) where you can:
+
+- **extend** the default tier (`require getenv('PHPQACI_ARKITECT_RULES_DEFAULT')`),
+- **opt in** to the optional / symfony tiers (their env vars),
+- **add** project-bespoke rules,
+- **replace** a tier wholesale by dropping your own `qaConfig/phparkitect-rules-*.php` (resolved ahead of the shipped copy by `configPath`).
+
+Disable arkitect for a project with `export useArkitect=0` in
+`qaConfig/qaConfig.inc.bash`. Run it alone with `vendor/bin/qa -t arch`.
+
 ## Custom PHPStan Rules
 
 ### Always-on rules (auto-loaded)

configDefaults/generic/phparkitect-rules-default.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * php-qa-ci PHPArkitect — GENERIC DEFAULT ruleset (the "rules-default" tier).
+ *
+ * Generic, safe-everywhere naming conventions. This tier is applied
+ * BY DEFAULT to every consuming project (the shipped configDefaults entry
+ * config `phparkitect.php` adds it to the detected source dir), exactly the way
+ * rules-default.neon is the PHPStan baseline. Keep it conservative — anything
+ * that is not safe across every project belongs in the optional tiers
+ * (phparkitect-rules-optional.php, phparkitect-rules-optional-symfony.php).
+ *
+ * This file returns a list of ArchRule objects; it is NOT a runnable config (no
+ * ClassSet). Projects compose it from qaConfig/phparkitect.php:
+ *
+ *   $default = require getenv('PHPQACI_ARKITECT_RULES_DEFAULT');
+ *   $config->add($classSet, ...$default, ...$projectRules);   // EXTEND
+ *
+ * To CUSTOMISE the baseline itself, copy this file to
+ * qaConfig/phparkitect-rules-default.php and edit it — configPath resolves the
+ * project copy first, and both the entry config and the
+ * PHPQACI_ARKITECT_RULES_DEFAULT env var follow it.
+ *
+ * @return list<\Arkitect\Rules\ArchRule>
+ */
+
+use Arkitect\Expression\ForClasses\HaveNameMatching;
+use Arkitect\Expression\ForClasses\IsEnum;
+use Arkitect\Expression\ForClasses\IsInterface;
+use Arkitect\Expression\ForClasses\IsTrait;
+use Arkitect\Rules\Rule;
+
+// These rules match on AST node KIND (interface/enum/trait keyword) and so do
+// NOT force PHPArkitect to resolve class ancestry — that keeps them robust even
+// when a project references a base type that is not in the autoloader. Rules
+// that DO resolve ancestry (IsA/Extend/Implement, e.g. the *Exception
+// convention) live in the optional tier, because they require a complete
+// autoloader and are therefore not safe-everywhere.
+return [
+    // Interfaces / enums / traits carry their kind in the suffix.
+    // This tier is the SINGLE SOURCE OF TRUTH for type-suffix naming: the former
+    // PHPStan RequireTypeSuffixRule was migrated here (structural naming belongs
+    // in PHPArkitect, not PHPStan), so do not re-introduce a PHPStan equivalent.
+    Rule::allClasses()
+        ->that(new IsInterface())
+        ->should(new HaveNameMatching('*Interface'))
+        ->because('an Interface suffix makes the symbol kind obvious at every use site'),
+    Rule::allClasses()
+        ->that(new IsEnum())
+        ->should(new HaveNameMatching('*Enum'))
+        ->because('an Enum suffix makes the symbol kind obvious at every use site'),
+    Rule::allClasses()
+        ->that(new IsTrait())
+        ->should(new HaveNameMatching('*Trait'))
+        ->because('a Trait suffix makes the symbol kind obvious at every use site'),
+];

configDefaults/generic/phparkitect-rules-optional-symfony.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * php-qa-ci PHPArkitect — OPTIONAL Symfony ruleset (the
+ * "rules-optional-symfony" tier).
+ *
+ * Symfony-specific naming conventions, OPT-IN (mirrors
+ * rules-optional-symfony.neon for PHPStan). A Symfony project composes it into
+ * its qaConfig/phparkitect.php:
+ *
+ *   $default = require getenv('PHPQACI_ARKITECT_RULES_DEFAULT');
+ *   $symfony = require getenv('PHPQACI_ARKITECT_RULES_OPTIONAL_SYMFONY');
+ *   $config->add($classSet, ...$default, ...$symfony, ...$projectRules);
+ *
+ * Rules key off framework base types (resolved via the project's --autoload),
+ * so they stay namespace-agnostic and work in any Symfony project.
+ *
+ * @return list<\Arkitect\Rules\ArchRule>
+ */
+
+use Arkitect\Expression\ForClasses\HaveNameMatching;
+use Arkitect\Expression\ForClasses\IsA;
+use Arkitect\Rules\Rule;
+
+return [
+    // Console commands are suffixed *Command.
+    Rule::allClasses()
+        ->that(new IsA('Symfony\\Component\\Console\\Command\\Command'))
+        ->should(new HaveNameMatching('*Command'))
+        ->because('a Command suffix makes console commands obvious and consistent'),
+
+    // Event subscribers are suffixed *Subscriber.
+    Rule::allClasses()
+        ->that(new IsA('Symfony\\Component\\EventDispatcher\\EventSubscriberInterface'))
+        ->should(new HaveNameMatching('*Subscriber'))
+        ->because('a Subscriber suffix makes event subscribers obvious and consistent'),
+];

configDefaults/generic/phparkitect-rules-optional.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * php-qa-ci PHPArkitect — OPTIONAL generic ruleset (the "rules-optional" tier).
+ *
+ * Stricter, opinionated naming conventions that are NOT safe to force on every
+ * project, so they are OPT-IN — a project enables them by composing this file
+ * into its qaConfig/phparkitect.php (mirrors rules-optional.neon for PHPStan):
+ *
+ *   $default  = require getenv('PHPQACI_ARKITECT_RULES_DEFAULT');
+ *   $optional = require getenv('PHPQACI_ARKITECT_RULES_OPTIONAL');
+ *   $config->add($classSet, ...$default, ...$optional, ...$projectRules);
+ *
+ * This is a curated set meant to grow. Keep each rule generic (no project
+ * namespaces); project-specific rules belong in the project's own config.
+ *
+ * NOTE: the *Exception rule below keys off `IsA(\Throwable)`, which makes
+ * PHPArkitect resolve each class's ancestry — so it requires a COMPLETE
+ * autoloader (a class implementing/extending a type missing from
+ * vendor/autoload.php aborts the run). That fragility is exactly why it is
+ * opt-in here rather than in the safe-everywhere default tier.
+ *
+ * @return list<\Arkitect\Rules\ArchRule>
+ */
+
+use Arkitect\Expression\ForClasses\HaveNameMatching;
+use Arkitect\Expression\ForClasses\IsA;
+use Arkitect\Expression\ForClasses\IsAbstract;
+use Arkitect\Rules\Rule;
+
+return [
+    // Every \Throwable is suffixed *Exception, so throw/catch sites and
+    // signatures are unambiguous. (Ancestry-resolving — see NOTE above.)
+    Rule::allClasses()
+        ->that(new IsA(\Throwable::class))
+        ->should(new HaveNameMatching('*Exception'))
+        ->because('a consistent Exception suffix makes throw/catch sites and signatures unambiguous'),
+
+    // Abstract classes are prefixed Abstract*, so the abstract-ness of a base
+    // type is obvious at the use site without opening the file.
+    Rule::allClasses()
+        ->that(new IsAbstract())
+        ->should(new HaveNameMatching('Abstract*'))
+        ->because('an Abstract prefix signals a non-instantiable base type at every use site'),
+];

configDefaults/generic/phparkitect.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * php-qa-ci PHPArkitect — DEFAULT ENTRY CONFIG (on by default).
+ *
+ * configPath resolves this file whenever a project has NOT supplied its own
+ * qaConfig/phparkitect.php, so every consuming project gets the generic-safe
+ * default baseline (phparkitect-rules-default.php) applied to its detected
+ * source directory — no per-project setup required. This is the arkitect
+ * equivalent of the rules-default PHPStan baseline.
+ *
+ * A project takes over by adding qaConfig/phparkitect.php (use the template at
+ * templates/qaConfig-phparkitect.php), where it can extend the defaults, opt
+ * into the optional/symfony tiers, and add bespoke rules. To turn arkitect off
+ * for a project entirely, set `export useArkitect=0` in qaConfig/qaConfig.inc.bash.
+ *
+ * The wrapper exports PHPQACI_ARKITECT_SRC_DIR (the pipeline's detected srcDir)
+ * and PHPQACI_ARKITECT_RULES_DEFAULT (the resolved default ruleset path).
+ */
+
+use Arkitect\ClassSet;
+use Arkitect\CLI\Config;
+
+return static function (Config $config): void {
+    $srcDir = getenv('PHPQACI_ARKITECT_SRC_DIR') ?: (getcwd() . '/src');
+
+    // Nothing to analyse (e.g. a project without a conventional src/) — pass cleanly.
+    if (!\is_dir($srcDir)) {
+        return;
+    }
+
+    $defaultRulesFile = getenv('PHPQACI_ARKITECT_RULES_DEFAULT')
+        ?: __DIR__ . '/phparkitect-rules-default.php';
+    $defaultRules = \is_file($defaultRulesFile) ? require $defaultRulesFile : [];
+
+    if ([] === $defaultRules) {
+        fwrite(STDERR, "PHPArkitect: default ruleset resolved empty (looked at {$defaultRulesFile}) — NO rules applied.\n");
+
+        return;
+    }
+
+    // Generated code is regenerated and cannot be renamed — never check it.
+    $config->add(ClassSet::fromDir($srcDir)->excludePath('Generated'), ...$defaultRules);
+};

includes/functions.inc.bash

@@ -277,7 +277,7 @@ function findTestsDir() {
 
 function findSrcDir() {
   srcDir="$projectRoot/src"
-  if [[ "" == "$srcDir" ]]; then
+  if [[ ! -d "$srcDir" ]]; then
     echo "
 
 

includes/generic/allStaticAnalysisTools.inc.bash

@@ -19,6 +19,13 @@ fi
 
 echo "
 
+Running PHPArkitect (architecture rules)
+----------------------------------------
+"
+runTool phpArkitect
+
+echo "
+
 Checking SensitiveParameter Usage
 ---------------------------------
 "