chore: adopt pinned standards and complete compliance work unit

.github/workflows/ci.yml

@@ -2,8 +2,6 @@ name: CI
 
 on:
   pull_request:
-    branches:
-      - main
   push:
     branches:
       - main
@@ -69,6 +67,7 @@ jobs:
             --prefer-dist \
             --no-progress
           composer check-platform-reqs
+          composer dump-autoload --optimize --strict-psr
           composer audit \
             --no-interaction \
             --abandoned=fail
@@ -102,6 +101,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
+          git diff --check
           git diff --exit-code
 
   unit-regression:
@@ -153,13 +153,14 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          vendor/bin/phpunit --testsuite unit
-          vendor/bin/phpunit --testsuite regression
+          composer test:unit
+          composer test:regression
 
       - name: Repository integrity
         shell: bash
         run: |
           set -euo pipefail
+          git diff --check
           git diff --exit-code
 
   lowest-dependencies:
@@ -256,11 +257,10 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          vendor/bin/phpunit --testsuite unit
-          vendor/bin/phpunit --testsuite regression
-          vendor/bin/phpunit --testsuite integration
-          vendor/bin/phpunit --testsuite integration
-          vendor/bin/phpunit
+          composer test:unit
+          composer test:regression
+          composer test:integration
+          composer test:integration
 
       - name: Verify MySQL residue
         if: ${{ always() && !cancelled() && steps.setup-php.outcome == 'success' }}
@@ -325,6 +325,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
+          git diff --check
           git diff --exit-code
 
   integration:
@@ -414,13 +415,18 @@ jobs:
             exit 1
           fi
 
-      - name: Run Integration and full suites
+      - name: Run Consumer Verification Harness
+        shell: bash
+        run: |
+          set -euo pipefail
+          composer test:consumer
+
+      - name: Run Integration and repeatability suites
         shell: bash
         run: |
           set -euo pipefail
-          vendor/bin/phpunit --testsuite integration
-          vendor/bin/phpunit --testsuite integration
-          vendor/bin/phpunit
+          composer test:integration
+          composer test:integration
 
       - name: Verify MySQL residue
         if: ${{ always() && !cancelled() && steps.setup-php.outcome == 'success' }}
@@ -485,6 +491,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
+          git diff --check
           git diff --exit-code
 
   ci-gate:

AGENTS.md

@@ -0,0 +1,19 @@
+# تعليمات مستودع maatify/persistence
+
+## التفعيل المعياري
+
+قبل التخطيط أو التنفيذ أو المراجعة، يجب قراءة [ملف معيار الاعتماد المثبت](docs/php-engineering-standards/standards/STANDARDS_ADOPTION_STANDARD_AR.md) كاملًا، ثم قراءة المعايير المنطبقة المسجلة في [STANDARDS_MANIFEST.md](docs/php-engineering-standards/STANDARDS_MANIFEST.md) بحسب نطاق المهمة.
+
+يسجل [STANDARDS_MANIFEST.md](docs/php-engineering-standards/STANDARDS_MANIFEST.md) مجموعة الاعتماد المحلية ونتيجة الحل، ولا يجوز استخدام مرجع upstream عائم أو نسخ معايير إضافية خارج المجموعة المسجلة.
+
+## قواعد خاصة بالمشروع
+
+- هذه الحزمة مكتبة Composer مستقلة، framework-agnostic وhost-agnostic، وتستخدم PDO المباشر مع SQL متوافق مع ملف MySQL/MariaDB. التحقق التشغيلي في هذا المستودع يتم على MySQL الحقيقي فقط، وMariaDB ليست مدخلة تحقق مستقلة في مصفوفة CI الحالية.
+- يجب الحفاظ على عقد v1.4.0 العام، بما في ذلك ملكية المعاملات، ودعم المعاملة الخارجية، ودلالات savepoint المعتمدة؛ لا يُجرى تغيير breaking public API.
+- اختبارات قاعدة البيانات تتطلب MySQL حقيقيًا؛ لا يجوز استخدام SQLite أو mocks لإثبات سلوك persistence الحقيقي.
+- لا يُتتبّع composer.lock، ولا يُضاف حقل Composer باسم version، ولا تُنشأ Tag أو GitHub Release ضمن أعمال هذا المستودع ما لم يصدر تصريح صريح بذلك.
+- يجب أن تبقى تغييرات Work Unit داخل نطاقها، وأن تمر عبر بوابات التحقق الفعلية الموثقة في [CONTRIBUTING.md](CONTRIBUTING.md) قبل النشر أو فتح Pull Request.
+
+## تعليمات إضافية
+
+لا توجد ملفات AGENTS.md إضافية خاصة بمسارات فرعية في هذا المستودع.

CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.4.0] - 2026-09-17
+## [1.4.0] - 2026-09-18
 
 ### Added
 * Transaction savepoint orchestration capability (`SavepointTransactionRunnerInterface`, `PdoSavepointTransactionRunner`) for safe, operation-local rollback boundaries within caller-owned PDO transactions.

CONTRIBUTING.md

@@ -30,7 +30,7 @@ Contributions should respect the current directory structure:
 
 * `src/`: Contains the production source code.
 * `tests/`: Contains the test suites (`unit`, `regression`, and `integration`).
-* `docs/`: Contains internal documentation and standards.
+* `docs/`: Contains internal documentation, architecture decisions, and the pinned engineering standards.
 
 ## Local Verification
 
@@ -39,12 +39,24 @@ Before submitting a Pull Request, please ensure all local verification steps pas
 ```bash
 composer install
 composer validate --strict
+composer dump-autoload --optimize --strict-psr
+composer check-platform-reqs
+composer audit --no-interaction --abandoned=fail
 composer analyse
 composer test:unit
 composer test:regression
+composer test:integration
+composer test:consumer
 vendor/bin/php-cs-fixer fix --dry-run --diff
+git diff --check
 ```
 
+The commands above are the local parity sequence for the CI quality and test
+gates. `composer test:integration` and `composer test:consumer` require the
+real MySQL service configured below. The consumer harness must be run from the
+package root; it creates and removes its own clean consumer root and test
+table twice.
+
 ### Integration Testing
 
 Integration tests require a real MySQL database. SQLite is explicitly **not** supported as a substitute for these tests.
@@ -69,6 +81,13 @@ Or to run the full test suite:
 composer test
 ```
 
+Workflow syntax is verified locally with actionlint `v1.7.12`, using the
+checksum pinned in `.github/workflows/ci.yml`:
+
+```bash
+actionlint -color
+```
+
 ## Architectural Contribution Rules
 
 When contributing code, you must adhere to the following architectural rules:
@@ -85,7 +104,7 @@ When contributing code, you must adhere to the following architectural rules:
 * **No Global Normalization**: Do not perform global normalization of gaps as a side effect of a scoped operation.
 * **Rollback Behavior**: Rollbacks must preserve the original error/exception.
 * **Exception Handling**: Do not catch every `\PDOException` or external `\Throwable` randomly to wrap it in a package exception. `PersistenceException` is strictly for package-defined exceptions.
-* **Composer Lock**: This reusable library does not track `composer.lock`, in accordance with the [Composer Package Standard](docs/standards/COMPOSER_PACKAGE_STANDARD.md). Remove any locally generated `composer.lock` before submitting changes.
+* **Composer Lock**: This reusable library does not track `composer.lock`, in accordance with the [Composer Package Standard](docs/php-engineering-standards/standards/packages/COMPOSER_PACKAGE_STANDARD.md). Remove any locally generated `composer.lock` before submitting changes.
 
 ## Pull Request Rules
 

PERSISTENCE_PACKAGE_REFERENCE.md

@@ -13,6 +13,18 @@
 * **Boundaries**: Framework-agnostic and host-agnostic. No HTTP API, no generic application repository, no ORM, no container bindings.
 * **Note**: PDO Pagination was introduced in v1.1.0.
 
+## Persistence and Schema Ownership
+
+The package owns the reusable PDO ordering, transaction, savepoint, and
+pagination behavior, but it does not own a persistent business entity or a
+production table. Consumers provide their own trusted table and column
+identifiers, SQL, scopes, and mapping. The package does not create migrations,
+foreign keys, or joins to Host tables. The persistence profile is
+MySQL/MariaDB-compatible SQL through direct PDO. Repository integration and
+Consumer verification run against real MySQL, with MySQL 8.4.10 as the current
+CI baseline; MariaDB is not independently verified by the current CI matrix.
+The package-level schema notes are in [schema/README.md](schema/README.md).
+
 ## Public API Inventory
 
 ### `Maatify\Persistence\Pdo\Ordering\ScopedOrderingConfig`
@@ -401,7 +413,11 @@ Renaming the marker MAY be reconsidered only as part of a separately approved, m
   * `PERSISTENCE_TEST_MYSQL_USER`
   * `PERSISTENCE_TEST_MYSQL_PASSWORD`
 * **Test Database Isolation**: Assumes isolated test tables and requires local package privileges (trigger/table cleanup). Tests include trigger failure injection.
-* **Current CI MySQL Baseline**: 8.4.10.
+* **Current CI MySQL Baseline**: MySQL 8.4.10. MariaDB is not independently verified by the current CI matrix.
+* **Consumer Verification Harness**: `composer test:consumer` installs the
+  package into a separate non-symlinked Composer root and verifies a public
+  ordering, savepoint, and pagination workflow against real MySQL twice from
+  clean consumer/database state.
 
 ## Verification Model
 

README.md

@@ -309,9 +309,10 @@ Other important documentation:
 * [Contributing Guide](CONTRIBUTING.md)
 * [Code of Conduct](CODE_OF_CONDUCT.md)
 * [Architecture Decision Records](docs/adr/README.md)
-* [Package Building Standard](docs/standards/PACKAGE_BUILDING_STANDARD.md)
-* [CI Workflow Standard](docs/standards/CI_WORKFLOW_STANDARD.md)
-* [Library Presentation Standard](docs/standards/LIBRARY_PRESENTATION_STANDARD.md)
+* [Standards Manifest](docs/php-engineering-standards/STANDARDS_MANIFEST.md)
+* [Package Building Standard](docs/php-engineering-standards/standards/packages/PACKAGE_BUILDING_STANDARD.md)
+* [CI Workflow Standard](docs/php-engineering-standards/standards/packages/CI_WORKFLOW_STANDARD.md)
+* [Library Presentation Standard](docs/php-engineering-standards/standards/packages/LIBRARY_PRESENTATION_STANDARD.md)
 
 ## ✅ Quality Status
 
@@ -330,19 +331,33 @@ Other important documentation:
 
 ```bash
 composer validate --strict
+composer dump-autoload --optimize --strict-psr
+composer check-platform-reqs
+composer audit --no-interaction --abandoned=fail
 composer analyse
 composer test:unit
 composer test:regression
+composer test:integration
+composer test:consumer
 vendor/bin/php-cs-fixer fix --dry-run --diff
+git diff --check
 ```
 
-`composer test:integration` and `composer test` require a real MySQL database. SQLite is explicitly **not** an integration substitute.
+`composer test:integration`, `composer test:consumer`, and `composer test` require a real MySQL database. SQLite is explicitly **not** an integration substitute. The Consumer Verification Harness creates a separate Composer root, installs this package as a non-symlinked dependency, and performs two clean runs.
 
 Set the following environment variables for Integration tests:
 * `PERSISTENCE_TEST_MYSQL_DSN`
 * `PERSISTENCE_TEST_MYSQL_USER`
 * `PERSISTENCE_TEST_MYSQL_PASSWORD`
 
+For workflow syntax validation, install actionlint `v1.7.12` with the checksum pinned in `.github/workflows/ci.yml`, then run:
+
+```bash
+actionlint -color
+```
+
+The CI `workflow-lint` job and this local command cover every workflow under `.github/workflows/`.
+
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

composer.json

@@ -57,7 +57,8 @@
     "test": "phpunit",
     "test:unit": "phpunit --testsuite unit",
     "test:regression": "phpunit --testsuite regression",
-    "test:integration": "phpunit --testsuite integration"
+    "test:integration": "phpunit --testsuite integration",
+    "test:consumer": "php tests/Consumer/run.php"
   },
   "config": {
     "optimize-autoloader": true,

docs/php-engineering-standards/STANDARDS_MANIFEST.md

@@ -0,0 +1,77 @@
+# سجل اعتماد معايير Maatify
+
+## حالة الحل
+
+- Resolution Status: VALID
+- Exception State: NONE
+- Upstream Repository: Maatify/php-engineering-standards
+- Adoption Commit: 44c8827095ab4007c355aa21c56b853f3b49d795
+- Adoption Date: 2026-09-17
+- Mixed-Commit Adoption: No
+- Scope: /
+
+## Pinned Adoption Control Set
+
+الملفات التالية نسخ مثبتة من Adoption Commit المذكور أعلاه:
+
+- [standards/STANDARDS_ADOPTION_STANDARD_AR.md](standards/STANDARDS_ADOPTION_STANDARD_AR.md) — Standard ID std-standards-adoption, Version 2.0.0
+- [standards/profiles/COMPOSER_PACKAGE_PROFILE.md](standards/profiles/COMPOSER_PACKAGE_PROFILE.md) — Profile ID composer-package, Version 1.0.0
+- [standards/profiles/REPOSITORY_GOVERNANCE_PROFILE.md](standards/profiles/REPOSITORY_GOVERNANCE_PROFILE.md) — Profile ID repository-governance, Version 1.0.0
+
+لا توجد Profiles غير مفعلة أو موروثة ضمن Control Set.
+
+## Active Profile Activations
+
+### composer-package
+
+- Profile Version: 1.0.0
+- Scope: /
+- Artifact Facts: مكتبة PHP/Composer مستقلة قابلة لإعادة الاستخدام، وتملك سلوك SQL/PDO واختبارات MySQL حقيقية.
+- Structural Resolution: VALID
+- Exception State: NONE
+
+### repository-governance
+
+- Profile Version: 1.0.0
+- Scope: /
+- Artifact Facts: مستودع يتبع دورة Work Unit وPhase Stack وPull Request في Maatify.
+- Structural Resolution: VALID
+- Exception State: NONE
+
+## Stage 1 — Candidate Standard References
+
+بعد حل المراجع المباشرة لكل Profile، تكون مجموعة المرشحين البنيوية التالية صحيحة ومثبتة من نفس Adoption Commit:
+
+- standards/packages/PACKAGE_BUILDING_STANDARD.md
+- standards/packages/COMPOSER_PACKAGE_STANDARD.md
+- standards/packages/CI_WORKFLOW_STANDARD.md
+- standards/packages/LIBRARY_PRESENTATION_STANDARD.md
+- standards/testing/TESTING_STANDARD.md
+- standards/ai/AI_COLLABORATION_WORKFLOW_AR.md
+- standards/GITHUB_PHASE_STACK_WORKFLOW_AR.md
+
+لا توجد مراجع Extends أو Explicit Additional Standards إضافية.
+
+## Resolved Applicable Standards Set
+
+جميع المرشحين أعلاه منطبقة بصورة حاسمة على Scope / وحقائق الحزمة الفعلية، ولذلك تمثل هذه القائمة المجموعة النهائية فقط:
+
+- [standards/packages/PACKAGE_BUILDING_STANDARD.md](standards/packages/PACKAGE_BUILDING_STANDARD.md) — Standard ID std-package-building, Version 1.4.0
+- [standards/packages/COMPOSER_PACKAGE_STANDARD.md](standards/packages/COMPOSER_PACKAGE_STANDARD.md) — Standard ID std-composer-package, Version 2.0.0
+- [standards/packages/CI_WORKFLOW_STANDARD.md](standards/packages/CI_WORKFLOW_STANDARD.md) — Standard ID std-ci-workflow, Version 1.1.0
+- [standards/packages/LIBRARY_PRESENTATION_STANDARD.md](standards/packages/LIBRARY_PRESENTATION_STANDARD.md) — Standard ID std-library-presentation, Version 1.0.1
+- [standards/testing/TESTING_STANDARD.md](standards/testing/TESTING_STANDARD.md) — Standard ID std-testing, Version 1.1.0
+- [standards/ai/AI_COLLABORATION_WORKFLOW_AR.md](standards/ai/AI_COLLABORATION_WORKFLOW_AR.md) — Standard ID std-ai-collaboration-workflow, Version 6.0.0
+- [standards/GITHUB_PHASE_STACK_WORKFLOW_AR.md](standards/GITHUB_PHASE_STACK_WORKFLOW_AR.md) — Standard ID std-github-phase-stack-workflow, Version 2.2.0
+
+## Additional Standards and Exceptions
+
+- Explicit Additional Standards: None
+- Explicit Exceptions/Overrides: None
+
+## Resolver Evidence
+
+- تم تنفيذ Structural / Transitive Resolution من ملفات Profile المحلية المثبتة.
+- تم تطبيق Canonical Standard Applicability على Scope / وحقائق أن الحزمة مستقلة وتملك سلوك PDO/SQL واختبارات MySQL ودورة Phase Stack.
+- لم تُستخدم ملفات standards عائمة أو نسخة كاملة من مستودع المعايير.
+- تم التحقق من كل ملف مثبت byte-for-byte مقابل Adoption Commit المسجل.