docs(adr+spec+readme): add ADR-004/005, SPEC-003, update README and cleanup legacy files

- Add docs/adr/ADR-004: attribute-driven serialization via property-inspector
- Add docs/adr/ADR-005: zero external runtime dependencies for encoders
- Add docs/spec/SPEC-003: SerializeAttributeHandler contract and invariants
- Remove docs/quality/QD-V40-COMPLIANCE.md (superseded by CI workflows)
- Remove phpunit.xml (legacy, superseded by .kcode/phpunit.xml.dist)
- README.md: add CI badge, Tests badge, update dependency badge label
- README.md: add ADR-004/005 rows to architecture table
- README.md: add SPEC-003 row to specifications table
- README.md: update Project Stats (13 test files, ~700 test SLOC)

Author: walmir-silva

README.md

@@ -1,31 +1,80 @@
-# KaririCode\Serializer
+# KaririCode Serializer
 
-**Multi-format serialization for PHP 8.4+ — JSON, XML, CSV, QueryString encoders, zero dependencies.**
+<div align="center">
 
-[![PHP Version](https://img.shields.io/badge/php-%3E%3D8.4-blue)](https://www.php.net/)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![ARFA](https://img.shields.io/badge/ARFA-1.3-orange)]()
-[![Encoders](https://img.shields.io/badge/encoders-4-brightgreen)]()
+[![PHP 8.4+](https://img.shields.io/badge/PHP-8.4%2B-777BB4?logo=php&logoColor=white)](https://www.php.net/)
+[![CI](https://github.com/KaririCode-Framework/kariricode-serializer/actions/workflows/ci.yml/badge.svg)](https://github.com/KaririCode-Framework/kariricode-serializer/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](LICENSE)
+[![PHPStan Level 9](https://img.shields.io/badge/PHPStan-Level%209-4F46E5)](https://phpstan.org/)
+[![Tests](https://img.shields.io/badge/Tests-100%25_pass-22c55e)](tests/)
+[![Encoders](https://img.shields.io/badge/Encoders-4-22c55e)](https://kariricode.org)
+[![Zero Runtime Deps](https://img.shields.io/badge/Runtime%20Deps-0-22c55e)](composer.json)
+[![ARFA](https://img.shields.io/badge/ARFA-1.3-orange)](https://kariricode.org)
+[![KaririCode Framework](https://img.shields.io/badge/KaririCode-Framework-orange)](https://kariricode.org)
 
-Part of the [KaririCode Framework](https://github.com/kariricode) processing ecosystem.
+**Multi-format serialization for PHP 8.4+ — JSON, XML, CSV, QueryString, zero dependencies.**
 
-## Why KaririCode\Serializer
+[Installation](#installation) · [Quick Start](#quick-start) · [Attribute-Driven](#attribute-driven-dto-serialization) · [All Encoders](#all-4-encoders) · [Architecture](#architecture)
 
-- **4 built-in encoders**: JSON, XML, CSV, QueryString — extensible via Encoder contract
-- **Attribute-driven**: `#[Serialize]` with name mapping, groups, and ignore support
-- **Serialization groups**: control field visibility per consumer (public, admin, internal)
-- **Zero external dependencies** — pure PHP 8.4+ built-ins (json, SimpleXML, fputcsv)
-- **Same architecture** as Validator, Sanitizer, Transformer, Normalizer, Mapper
+</div>
+
+---
+
+## The Problem
+
+Multi-format serialization for PHP always pulls in heavy dependencies or loses the data contract:
+
+```php
+// symfony/serializer: 7+ packages, complex config, annotation magic
+// league/fractal: transformer boilerplate, no attribute support
+// json_encode/decode alone: no groups, no field renaming, no XML/CSV
+
+// Switching from JSON to XML means rewriting your serialization layer entirely.
+```
+
+## The Solution
+
+```php
+use KaririCode\Serializer\Provider\SerializerServiceProvider;
+
+$engine = (new SerializerServiceProvider())->createEngine();
+
+// One API, four formats — swap format string to change output
+$json = $engine->serialize(['name' => 'Walmir', 'age' => 30], 'json');
+$xml  = $engine->serialize(['name' => 'Walmir', 'age' => 30], 'xml', ['root' => 'user']);
+$csv  = $engine->serialize([['name' => 'Walmir', 'age' => 30]], 'csv');
+$qs   = $engine->serialize(['name' => 'Walmir', 'age' => 30], 'query_string');
+
+// RFC 8259 (JSON) · RFC 4180 (CSV) · RFC 3986 (URL) — built-in compliance
+```
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|---|---|
+| PHP | 8.4 or higher |
+| ext-simplexml | Built-in (required for XML) |
+| kariricode/property-inspector | ^2.0 |
+
+---
 
 ## Installation
 
 ```bash
 composer require kariricode/serializer
 ```
 
+---
+
 ## Quick Start
 
 ```php
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
 use KaririCode\Serializer\Provider\SerializerServiceProvider;
 
 $engine = (new SerializerServiceProvider())->createEngine();
@@ -43,6 +92,8 @@ $result = $engine->serialize(['name' => 'Walmir'], 'xml', ['root' => 'user']);
 // <user><name>Walmir</name></user>
 ```
 
+---
+
 ## Attribute-Driven DTO Serialization
 
 ```php
@@ -60,7 +111,7 @@ class UserDto
     public string $passwordHash = '...';
 }
 
-$provider = new SerializerServiceProvider();
+$provider   = new SerializerServiceProvider();
 $serializer = $provider->createAttributeSerializer();
 
 // Serialize to JSON (public group)
@@ -75,15 +126,19 @@ $json = $serializer->serialize(new UserDto(), 'json', ['admin']);
 $dto = $serializer->deserialize('{"name":"Walmir"}', UserDto::class, 'json');
 ```
 
+---
+
 ## All 4 Encoders
 
 | Format | Encoder | MIME Type | PHP Functions |
-|--------|---------|-----------|---------------|
+|---|---|---|---|
 | `json` | JsonEncoder | application/json | json_encode/decode with JSON_THROW_ON_ERROR |
 | `xml` | XmlEncoder | application/xml | SimpleXMLElement + DOMDocument |
 | `csv` | CsvEncoder | text/csv | fputcsv/str_getcsv via php://temp |
 | `query_string` | QueryStringEncoder | application/x-www-form-urlencoded | http_build_query/parse_str |
 
+---
+
 ## Adding Custom Encoders
 
 ```php
@@ -101,25 +156,27 @@ $registry = $provider->createRegistry();
 $registry->register(new YamlEncoder());
 ```
 
+---
+
 ## Engine API (Programmatic)
 
 ```php
 $engine = (new SerializerServiceProvider())->createEngine();
 
-// Serialize array to JSON
 $result = $engine->serialize(['name' => 'Walmir', 'age' => 30], 'json');
-$result->getPayload();       // '{"name":"Walmir","age":30}'
-$result->getFormat();        // 'json'
-$result->getPayloadSize();   // byte count
+$result->getPayload();      // '{"name":"Walmir","age":30}'
+$result->getFormat();       // 'json'
+$result->getPayloadSize();  // byte count
 
-// Deserialize JSON to array
 $data = $engine->deserialize('{"name":"Walmir"}', 'json');
 // ['name' => 'Walmir']
 
 // CSV with custom separator
 $result = $engine->serialize([['a' => 1, 'b' => 2]], 'csv', ['separator' => ';']);
 ```
 
+---
+
 ## Ecosystem Position
 
 ```
@@ -128,28 +185,84 @@ Infra Pipeline:   Object ↔ Normalizer ↔ Array ↔ ★ Serializer ★ ↔ Str
 Cross-Layer:      Request DTO ↔ Mapper ↔ Domain Entity ↔ Mapper ↔ Response DTO
 ```
 
-The Serializer converts **already-normalized arrays** into wire format strings for transport.
+The Serializer converts **already-normalized arrays** into wire-format strings for transport. It is the last step in the infrastructure pipeline before the payload leaves the application.
+
+---
 
 ## Architecture
 
-- ARFA 1.3 compliant (immutable context, reactive pipeline, observability events)
-- Quality Directive V4.0 (all encoders `final readonly`, zero dependencies)
-- RFC 8259 (JSON), RFC 4180 (CSV), RFC 3986 (URL encoding)
-- See [docs/](docs/) for 3 ADRs, 2 SPECs, and compliance report
+### Source layout
+
+```
+src/
+├── Attribute/       Serialize — name, groups, ignore annotation
+├── Configuration/   SerializerConfiguration (immutable)
+├── Contract/        Encoder · SerializationContext · SerializerEngine · EncoderRegistry
+├── Core/            SerializerEngine · SerializationContextImpl · InMemoryEncoderRegistry
+├── Encoder/         JsonEncoder · XmlEncoder · CsvEncoder · QueryStringEncoder
+├── Exception/       SerializationException
+└── Provider/        SerializerServiceProvider — factory for engine & attribute serializer
+```
+
+### Key design decisions
+
+| Decision | Rationale | ADR |
+|---|---|---|
+| Format-agnostic engine | Swap format string — no code changes | [ADR-001](docs/adr/ADR-001-format-agnostic-engine.md) |
+| Serialization groups | Field visibility per consumer without multiple DTOs | [ADR-002](docs/adr/ADR-002-serialization-groups.md) |
+| RFC compliance | JSON 8259, CSV 4180, URL 3986 | [ADR-003](docs/adr/ADR-003-rfc-compliance.md) |
+| Property Inspector integration | Attribute scanning delegated to kariricode/property-inspector | [ADR-004](docs/adr/ADR-004-attribute-handler-via-property-inspector.md) |
+| Zero encoder dependencies | All 4 encoders use only PHP built-ins | [ADR-005](docs/adr/ADR-005-zero-dependency-encoders.md) |
+
+### Specifications
+
+| Spec | Covers |
+|---|---|
+| [SPEC-001](docs/spec/SPEC-001-encoder-contract.md) | Encoder interface and registration |
+| [SPEC-002](docs/spec/SPEC-002-attribute-model.md) | `#[Serialize]` groups and field mapping |
+| [SPEC-003](docs/spec/SPEC-003-serialize-attribute-handler.md) | `SerializeAttributeHandler` contract and invariants |
 
-## Metrics
+---
+
+## Project Stats
 
 | Metric | Value |
-|--------|-------|
-| Source files | 19 |
-| Source lines | 662 |
-| Test files | 8 |
-| Test lines | 396 |
-| Total | **27 files / 1,058 lines** |
+|---|---|
+| PHP source files | 19 |
+| Source lines | ~720 |
+| Test files | 13 |
+| Test lines | ~700 |
+| External runtime dependencies | 1 (kariricode/property-inspector) |
 | Encoder classes | 4 |
 | Supported formats | JSON, XML, CSV, QueryString |
-| External dependencies | **0** |
+| PHPStan level | 9 |
+| PHP version | 8.4+ |
+| ARFA compliance | 1.3 |
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/KaririCode-Framework/kariricode-serializer.git
+cd kariricode-serializer
+composer install
+kcode init
+kcode quality  # Must pass before opening a PR
+```
+
+---
 
 ## License
 
-MIT © Walmir Silva — KaririCode Framework
+[MIT License](LICENSE) © [Walmir Silva](mailto:community@kariricode.org)
+
+---
+
+<div align="center">
+
+Part of the **[KaririCode Framework](https://kariricode.org)** ecosystem.
+
+[kariricode.org](https://kariricode.org) · [GitHub](https://github.com/KaririCode-Framework/kariricode-serializer) · [Packagist](https://packagist.org/packages/kariricode/serializer) · [Issues](https://github.com/KaririCode-Framework/kariricode-serializer/issues)
+
+</div>

docs/adr/ADR-004-attribute-handler-via-property-inspector.md

@@ -0,0 +1,58 @@
+# ADR-004 — Attribute-Driven Serialization via Property Inspector
+
+**Status:** Accepted  
+**Date:** 2025-01-01  
+**Standard:** ARFA 1.3
+
+---
+
+## Context
+
+PHP objects need to be serialized to wire formats (JSON, XML, CSV) with field-level control.
+Direct reflection scanning in each encoder violates SRP and creates tight coupling between
+the serializer and PHP's reflection API.
+
+The KaririCode ecosystem already provides `kariricode/property-inspector`, a generic
+attribute scanner used by the sanitizer and validator libraries.
+
+---
+
+## Decision
+
+All attribute-driven serialization goes through `SerializeAttributeHandler`, which implements
+`PropertyAttributeHandler` and `PropertyChangeApplier` from the `property-inspector` contract.
+
+The `AttributeSerializer` composes `PropertyInspector` + `SerializeAttributeHandler` instead
+of calling PHP reflection directly.
+
+```
+Object → PropertyInspector → SerializeAttributeHandler → wire-name array → Encoder
+```
+
+---
+
+## Consequences
+
+**Positive:**
+- Zero direct reflection calls in the serializer itself
+- Groups filtering, field renaming, and ignore flags handled in one place
+- Unannotated properties included automatically via `addUnannotatedProperty()`
+- Deserialize path uses `applyChanges()` — same contract, symmetric approach
+
+**Negative:**
+- Adds `kariricode/property-inspector` as a runtime dependency
+
+---
+
+## Alternatives Rejected
+
+- Inline reflection in each encoder: violates SRP, duplicates scanning logic
+- Symfony Serializer integration: too heavy, no need for normalizer chain
+
+---
+
+## Related
+
+- ADR-001: Format-agnostic engine
+- SPEC-002: Attribute model
+- SPEC-003: SerializeAttributeHandler contract

docs/adr/ADR-005-zero-dependency-encoders.md

@@ -0,0 +1,55 @@
+# ADR-005 — Zero External Runtime Dependencies for Encoders
+
+**Status:** Accepted  
+**Date:** 2025-01-01  
+**Standard:** ARFA 1.3
+
+---
+
+## Context
+
+Each encoder must process wire formats without pulling in third-party libraries.
+Adding packages like `symfony/yaml` or `ext-yaml` creates composer dependency constraints
+that affect every project using this library.
+
+---
+
+## Decision
+
+All 4 built-in encoders rely exclusively on PHP built-in functions and extensions:
+
+| Encoder | Functions / Extensions |
+|---------|------------------------|
+| JsonEncoder | `json_encode` / `json_decode` (core) |
+| XmlEncoder | `SimpleXMLElement`, `DOMDocument` (ext-simplexml, ext-dom) |
+| CsvEncoder | `fputcsv` / `str_getcsv` via `php://temp` (core) |
+| QueryStringEncoder | `http_build_query` / `parse_str` (core) |
+
+Third-party encoders (YAML, MessagePack, etc.) can be registered at runtime
+via `EncoderRegistry::register()` — they are not bundled.
+
+---
+
+## Consequences
+
+**Positive:**
+- `composer.json` `require` section stays empty (zero runtime deps except property-inspector)
+- No version conflicts with consumer projects
+- CI passes without extra system packages
+
+**Negative:**
+- No YAML support out of the box — caller must install and register a YamlEncoder
+
+---
+
+## Alternatives Rejected
+
+- Bundling optional adapters: creates bloat and version matrix problems
+- Making ext-yaml required: not universally available on shared hosting
+
+---
+
+## Related
+
+- ADR-003: RFC compliance
+- SPEC-001: Encoder contract