Phred/MILESTONES.md

# Phred Framework Milestones
Phred supports REST and JSON:API via env setting; batteries-included defaults, swappable components.
## ~~M0 — Project bootstrap (repo readiness)~~
* ~~Tasks:~~
  * ~~Finalize `composer.json` (namespaces, scripts, suggests) and `LICENSE`.~~
  * ~~Add `.editorconfig`, `.gitattributes`, `.gitignore`, example `.env.example`.~~
  * ~~Set up CI (lint, static analysis, unit tests) and basic build badge.~~
* ~~Acceptance:~~
  * ~~Fresh clone installs (without running suggested packages) and passes linters/analysis/tests.~~
## ~~M1 — Core HTTP kernel and routing~~
* ~~Tasks:~~
  * ~~Implement the HTTP kernel: `PSR-15` pipeline via `Relay`.~~
  * ~~Wire `nyholm/psr7(-server)` factories and server request creation.~~
  * ~~Integrate `nikic/fast-route` with a RouteCollector and dispatcher.~~
  * ~~Define route → controller resolution (invokable controllers).~~
  * ~~Add minimal app bootstrap (front controller) and DI container wiring (`PHP-DI`).~~
  * ~~Addendum: Route groups (prefix only) via `Router::group()`~~
* ~~Acceptance:~~
  * ~~Sample route returning a JSON 200 via controller.~~
  * ~~Controllers are invokable (`__invoke(Request)`), one route per controller.~~
  * ~~Route groups (prefix only) work and are tested.~~
## ~~M2 — Configuration and environment~~
* ~~Tasks:~~
  * ~~Load `.env` via `vlucas/phpdotenv` and expose `Phred\Support\Config`.~~
  * ~~Define configuration precedence and document keys (e.g., `API_FORMAT`, `APP_ENV`, `APP_DEBUG`).~~
* ~~Acceptance:~~
  * ~~App reads config from `.env`; unit test demonstrates override behavior.~~
## M3 — API formats and content negotiation
* Tasks:
  * Finalize `ContentNegotiationMiddleware` using `.env` and `Accept` header.
  * Bind `ApiResponseFactoryInterface` to `RestResponseFactory` or `JsonApiResponseFactory` based on format.
  * Provide developer‑facing helpers for common responses (`ok`, `created`, `error`).
* Acceptance:
  * Demo endpoints respond correctly as REST or JSON:API depending on `API_FORMAT` and `Accept`.
## M4 — Error handling and problem details
* Tasks:
  * Finalize `ProblemDetailsMiddleware` with RFC7807 (REST) and JSON:API error documents.
  * Integrate `filp/whoops` for dev mode (`APP_DEBUG=true`).
  * Map common exceptions to HTTP status codes; include correlation/request IDs in responses/logs.
* Acceptance:
  * Throwing an exception yields a standards‑compliant error response; debug mode shows Whoops page.
## M5 — Dependency Injection and Service Providers
* Tasks:
  * Define Service Provider interface and lifecycle (register, boot).
  * Module discovery loads providers in order (core → app → module).
  * Add examples for registering controllers, services, config, and routes via providers.
  * Define contracts: `Phred\Contracts\Template\RendererInterface`, `Phred\Contracts\Orm\*`, `Phred\Contracts\Flags\FeatureFlagClientInterface`, `Phred\Contracts\Testing\TestRunnerInterface` (optional).
  * Define config/env keys for driver selection (e.g., `TEMPLATE_DRIVER`, `ORM_DRIVER`, `FLAGS_DRIVER`, `TEST_RUNNER`).
  * Provide “default adapter” Service Providers for the shipped packages and document swap procedure.
* Acceptance:
  * Providers can contribute bindings and routes; order is deterministic and tested.
  * A sample module can switch template/ORM/flags provider by changing `.env` and provider registration, without touching controllers/services.
## M6 — MVC: Controllers, Views, Templates
* Tasks:
  * Controller base class and conventions (request/response helpers).
  * View layer (data preparation) with `getphred/eyrie` template engine integration.
  * Template rendering helper: `$this->render(<template>, <data>)`.
* Acceptance:
  * Example page rendered through View → Template; API coexists with full‑site rendering.
  * Rendering works via RendererInterface and can be swapped (e.g., Eyrie → Twig demo) with only configuration/provider changes.
## M7 — Modules (Django‑style app structure)
* Tasks:
  * Define module filesystem layout (Nested Controllers/Views/Services/Models/Templates/Routes/Tests).
  * Module loader: auto‑register providers, routes, templates.
  * Namespacing and autoload guidance.
* Acceptance:
  * Creating a module with the CLI makes it discoverable; routes/templates work without manual wiring.
## M8 — Database access, migrations, and seeds
* Tasks:
  * Integrate `getphred/pairity` for ORM/migrations/seeds.
  * Define config (`DB_*`), migration paths (app and modules), and seeder conventions.
  * CLI commands: `migrate`, `migration:rollback`, `seed`, `seed:rollback`.
  * All persistence usage in examples goes through Orm contracts; can be swapped (Pairity → Doctrine adapter demo optional).
* Acceptance:
  * Running migrations modifies a test database; seeds populate sample data; CRUD demo works.
  * All persistence usage in examples goes through Orm contracts; can be swapped (Pairity → Doctrine adapter demo optional).
## M9 — CLI (phred) and scaffolding
* Tasks:
  * Implement Symfony Console app in `bin/phred`.
  * Generators: `create:module`, `create:<module>:controller`, `create:<module>:model`, `create:<module>:migration`, `create:<module>:seed`, `create:<module>:test`, `create:<module>:view`.
  * Utility commands: `test[:<module>]`, `run`, `db:backup`, `db:restore`.
* Acceptance:
  * Commands generate files with correct namespaces/paths and pass basic smoke tests.
## M10 — Security middleware and auth primitives
* Tasks:
  * Add CORS, Secure Headers middlewares; optional CSRF for template routes.
  * JWT support (lcobucci/jwt) with simple token issue/verify service.
  * Configuration for CORS origins, headers, methods.
  * Bind FeatureFlagClientInterface with a default adapter (Flagpole); add small sample usage and env config.
* Acceptance:
  * CORS preflight and secured endpoints behave as configured; JWT‑protected route example works.
## M11 — Logging, HTTP client, and filesystem
* Tasks:
  * Monolog setup with handlers and processors (request ID, memory, timing).
  * Guzzle PSR‑18 client exposure; DI binding for HTTP client interface.
  * Flysystem integration with local adapter; abstraction for storage disks.
* Acceptance:
  * Logs include correlation IDs; sample outbound HTTP call via client; file upload/storage demo works.
## M12 — Serialization/validation utilities and pagination
* Tasks:
  * REST default: Symfony Serializer normalizers/encoders; document extension points.
  * Add simple validation layer (pick spec or integrate later if preferred; at minimum, input filtering and error shape alignment with Problem Details).
  * Pagination helpers (links/meta), REST and JSON:API compatible outputs.
* Acceptance:
  * Example endpoint validates input, returns 422 with details; paginated listing includes links/meta.
## M13 — OpenAPI and documentation
* Tasks:
  * Integrate `zircote/swagger-php` annotations.
  * CLI/task to generate OpenAPI JSON; optional serve route and Redoc UI pointer.
  * Document auth, pagination, error formats.
* Acceptance:
  * Generated OpenAPI document validates; matches sample endpoints.
## M14 — Testing, quality, and DX
* Tasks:
  * Establish testing structure with Codeception (unit, integration, API suites).
  * Add fixtures/factories via Faker for examples.
  * PHPStan level selection and baseline; code style via php-cs-fixer ruleset.
  * Pre‑commit hooks (e.g., GrumPHP) optional.
  * Define TestRunnerInterface and a Codeception adapter; otherwise, state tests are run via Composer script only.
* Acceptance:
  * `composer test` runs green across suites; static analysis passes.
  * CLI tests run via TestRunnerInterface;
  * CLI tests run green per module and across suites.
## M15 — Caching and performance (optional default)
* Tasks:
  * Provide `PSR-16` cache interface binding; suggest `symfony/cache` when enabled.
  * Simple response caching middleware and ETag/Last‑Modified helpers.
  * Rate limiting middleware (token bucket) suggestion/integration point.
* Acceptance:
  * Sample endpoint demonstrates cached responses and conditional requests.
## M16 — Production hardening and deployment
* Tasks:
  * Config for envs (dev/test/stage/prod), error verbosity, trusted proxies/hosts.
  * Docker example, PHP‑FPM + Nginx config templates.
  * Healthcheck endpoint, readiness/liveness probes.
* Acceptance:
  * Containerized demo serves both API and template pages; healthchecks pass.
## M17 — JSON:API enhancements (optional package)
* Tasks:
  * If enabled, integrate `neomerx/json-api` fully: includes, sparse fieldsets, relationships, sorting, filtering, pagination params.
  * Adapters/Schema providers per resource type.
* Acceptance:
  * JSON:API conformance tests for selected endpoints pass; docs updated.
## M18 — Examples and starter template
* Tasks:
  * Create `examples/blog` module showcasing controllers, views, templates, ORM, auth, pagination, and both API formats.
  * Provide `composer create-project` skeleton template instructions.
* Acceptance:
  * New users can scaffold a working app in minutes following README.
## M19 — Documentation site
* Tasks:
  * Expand README into a docs site (MkDocs or similar): getting started, concepts, reference, guides.
  * Versioned docs and upgrade notes.
* Acceptance:
  * Docs published; links in README; examples maintained.
## M20 — Governance and roadmap tracking
* Tasks:
  * Define contribution guide, issue templates, RFC process for changes.
  * Public roadmap (this milestone list) tracked as GitHub Projects/Issues.
* Acceptance:
  * Contributors can propose features via RFC; roadmap is visible and updated.
## Notes on sequencing and parallelization
* M0–M4 are critical path for the HTTP core and should be completed sequentially.
* M5–M8 can progress in parallel with M9 (CLI) once the kernel is stable.
* Optional tracks (M15, M17) can be deferred without blocking core usability.