From 6a48b585585e8941b274b8737c51a1df111339e0 Mon Sep 17 00:00:00 2001
From: Funky Waddle <paul@funkywaddle.com>
Date: Sun, 22 Feb 2026 02:23:24 -0600
Subject: [PATCH] chore: clear SPECS.md and MILESTONES.md for fresh Idea phase

---
 MILESTONES.md | 262 --------------------------------------------------
 SPECS.md      | 158 ------------------------------
 2 files changed, 420 deletions(-)

diff --git a/MILESTONES.md b/MILESTONES.md
index 78be08d..b2ec105 100644
--- a/MILESTONES.md
+++ b/MILESTONES.md
@@ -1,265 +1,3 @@
 # Phred Framework Milestones
 
 [← Back to README](./README.md) | [SPECS.md](./SPECS.md)
-
-Phred supports REST and JSON:API via env setting; batteries-included defaults, swappable components.
-
-[↑ Back to Top](#table-of-contents)
-## Table of Contents
-- [M0 — Project bootstrap (repo readiness)](#m0-project-bootstrap-repo-readiness)
-- [M1 — Core HTTP kernel and routing](#m1-core-http-kernel-and-routing)
-- [M2 — Configuration and environment](#m2-configuration-and-environment)
-- [M3 — API formats and content negotiation](#m3-api-formats-and-content-negotiation)
-- [M4 — Error handling and problem details](#m4-error-handling-and-problem-details)
-- [M5 — Dependency Injection and Service Providers](#m5-dependency-injection-and-service-providers)
-- [M6 — MVC: Controllers, Views, Templates](#m6-mvc-controllers-views-templates)
-- [M7 — Modules (Django‑style app structure)](#m7-modules-django-style-app-structure)
-- [M8 — Database access, migrations, and seeds](#m8-database-access-migrations-and-seeds)
-- [M9 — CLI (phred) and scaffolding](#m9-cli-phred-and-scaffolding)
-- [M10 — Security middleware and auth primitives](#m10-security-middleware-and-auth-primitives)
-- [M11 — Logging, HTTP client, and filesystem](#m11-logging-http-client-and-filesystem)
-- [M12 — Serialization/validation utilities and pagination](#m12-serialization-validation-utilities-and-pagination)
-- [M13 — OpenAPI and documentation](#m13-openapi-and-documentation)
-- [M14 — Testing, quality, and DX](#m14-testing-quality-and-dx)
-- [M15 — Caching and performance (optional default)](#m15-caching-and-performance-optional-default)
-- [M16 — Production hardening and deployment](#m16-production-hardening-and-deployment)
-- [M17 — JSON:API enhancements (optional package)](#m17-json-api-enhancements-optional-package)
-- [M18 — Examples and starter template](#m18-examples-and-starter-template)
-- [M19 — Documentation site](#m19-documentation-site)
-- [M20 — Dynamic Command Help](#m20-dynamic-command-help)
-- [M21 — Governance and roadmap tracking](#m21-governance-and-roadmap-tracking)
-
-## M0 — Project bootstrap (repo readiness)
-* Tasks:
-  - [x] Finalize `composer.json` (namespaces, scripts, suggests) and `LICENSE`.
-  - [x] Add `.editorconfig`, `.gitattributes`, `.gitignore`, example `.env.example`.
-  - [x] Set up CI (lint, static analysis, unit tests) and basic build badge.
-* Acceptance:
-  - [x] Fresh clone installs (without running suggested packages) and passes linters/analysis/tests.
-
-[↑ Back to Top](#table-of-contents)
-## M1 — Core HTTP kernel and routing
-* Tasks:
-  - [x] Implement the HTTP kernel: `PSR-15` pipeline via `Relay`.
-  - [x] Wire `nyholm/psr7(-server)` factories and server request creation.
-  - [x] Integrate `nikic/fast-route` with a RouteCollector and dispatcher.
-  - [x] Define route → controller resolution (invokable controllers).
-  - [x] Add minimal app bootstrap (front controller) and DI container wiring (`PHP-DI`).
-  - [x] Addendum: Route groups (prefix only) via `Router::group()`
-* Acceptance:
-  - [x] Sample route returning a JSON 200 via controller.
-  - [x] Controllers are invokable (`__invoke(Request)`), one route per controller.
-  - [x] Route groups (prefix only) work and are tested.
-
-[↑ Back to Top](#table-of-contents)
-## M2 — Configuration and environment
-* Tasks:
-  - [x] Load `.env` via `vlucas/phpdotenv` and expose `Phred\Support\Config`.
-  - [x] Define configuration precedence and document keys (e.g., `API_FORMAT`, `APP_ENV`, `APP_DEBUG`).
-* Acceptance:
-  - [x] App reads config from `.env`; unit test demonstrates override behavior.
-
-[↑ Back to Top](#table-of-contents)
-## M3 — API formats and content negotiation
-* Tasks:
-  - [x] Finalize `ContentNegotiationMiddleware` using `.env` and `Accept` header.
-  - [x] Bind `ApiResponseFactoryInterface` to `RestResponseFactory` or `JsonApiResponseFactory` based on format.
-  - [x] Provide developer‑facing helpers for common responses (`ok`, `created`, `error`).
-* Acceptance:
-  - [x] Demo endpoints respond correctly as REST or JSON:API depending on `API_FORMAT` and `Accept`.
-
-[↑ Back to Top](#table-of-contents)
-## M4 — Error handling and problem details
-* Tasks:
-  - [x] Finalize `ProblemDetailsMiddleware` with RFC7807 (REST) and JSON:API error documents.
-  - [x] Integrate `filp/whoops` for dev mode (`APP_DEBUG=true`).
-  - [x] Map common exceptions to HTTP status codes; include correlation/request IDs in responses/logs.
-* Acceptance:
-  - [x] Throwing an exception yields a standards‑compliant error response; debug mode shows Whoops page.
-
-[↑ Back to Top](#table-of-contents)
-## M5 — Dependency Injection and Service Providers
-* Tasks:
-  - [x] Define Service Provider interface and lifecycle (register, boot).
-  - [x] Module discovery loads providers in order (core → app → module).
-  - [x] Add examples for registering controllers, services, config, and routes via providers.
-  - [x] Define contracts: `Template\Contracts\RendererInterface`, `Orm\Contracts\*`, `Flags\Contracts\FeatureFlagClientInterface`, `Testing\Contracts\TestRunnerInterface`.
-  - [x] Define config/env keys for driver selection (e.g., `TEMPLATE_DRIVER`, `ORM_DRIVER`, `FLAGS_DRIVER`, `TEST_RUNNER`).
-  - [x] Provide “default adapter” Service Providers for the shipped packages and document swap procedure.
-* Acceptance:
-  - [x] Providers can contribute bindings and routes; order is deterministic and tested.
-  - [x] Drivers can be switched via `.env`/config without changing controllers/services; example provider route covered by tests.
-
-[↑ Back to Top](#table-of-contents)
-## M6 — MVC: Controllers, Views, Templates
-* Tasks:
-  - [x] Controller base class and conventions (request/response helpers).
-  - [x] View layer (data preparation) with `getphred/eyrie` template engine integration.
-  - [x] Template rendering helper: `$this->render(<template>, <data>)`.
-* Acceptance:
-  - [x] Example page rendered through View → Template; API coexists with full‑site rendering.
-  - [x] Rendering works via RendererInterface and can be swapped (e.g., Eyrie → Twig demo) with only configuration/provider changes.
-
-[↑ Back to Top](#table-of-contents)
-## M7 — Modules (Django‑style app structure)
-* Tasks:
-  - [x] Define module filesystem layout (Nested Controllers/Views/Services/Models/Templates/Routes/Tests).
-  - [x] Module loader: auto‑register providers, routes, templates.
-  - [x] Namespacing and autoload guidance.
-  - [x] Core CLI: add `create:module <name>` command to scaffold a module with nested resources.
-  - [x] ORM‑agnostic module layout (to support Pairity DAO/DTO and Eloquent Active Record):
-    - [x] `Modules/<X>/Models/` — domain models (pure PHP, ORM‑neutral)
-    - [x] `Modules/<X>/Repositories/` — repository interfaces (DI targets for services)
-    - [x] `Modules/<X>/Persistence/Pairity/` — DAOs, DTOs, mappers, repository implementations
-    - [x] `Modules/<X>/Persistence/Eloquent/` — Eloquent models, scopes, repository implementations
-    - [x] `Modules/<X>/Database/Migrations/*` — canonical migrations for the module (no duplication per driver)
-* Acceptance:
-  - [x] Creating a module with the CLI makes it discoverable; routes/templates work without manual wiring.
-  - [x] Switching `ORM_DRIVER` between `pairity` and `eloquent` requires no changes to services/controllers; providers bind repository interfaces to driver implementations.
-
-[↑ Back to Top](#table-of-contents)
-## M8 — Database access, migrations, and seeds
-* Tasks:
-  - [x] Integrate `getphred/pairity` for ORM/migrations/seeds.
-  - [x] Define config (`DB_*`), migration paths (app and modules), and seeder conventions.
-  - [x] CLI commands: `migrate`, `migration:rollback`, `seed`, `seed:rollback`.
-  - [x] All persistence usage in examples goes through Orm contracts; can be swapped (Pairity → Doctrine adapter demo optional).
-  - [x] Add `register:orm <driver>` command:
-    - [x] Verify or guide installation of the ORM driver package.
-    - [x] Update `.env` (`ORM_DRIVER=<driver>`) safely.
-    - [x] Create `modules/*/Persistence/<Driver>/` directories for existing modules.
-* Acceptance:
-  - [x] Running migrations modifies a test database; seeds populate sample data; CRUD demo works.
-  - [x] All persistence usage in examples goes through Orm contracts; can be swapped (Pairity → Doctrine adapter demo optional).
-
-[↑ Back to Top](#table-of-contents)
-## M9 — CLI (phred) and scaffolding
-* Tasks:
-  - [x] Implement Symfony Console app in `bin/phred`.
-  - [x] Generators: `create:<module>:controller`, `create:<module>:model`, `create:<module>:migration`, `create:<module>:seed`, `create:<module>:test`, `create:<module>:view`.
-  - [x] Utility commands: `test[:<module>]`, `run`, `db:backup`, `db:restore`.
-* Acceptance:
-  - [x] Commands generate files with correct namespaces/paths and pass basic smoke tests.
-
-[↑ Back to Top](#table-of-contents)
-## M10 — Security middleware and auth primitives
-* Tasks:
-  - [x] Add CORS, Secure Headers middlewares; optional CSRF for template routes.
-  - [x] JWT support (lcobucci/jwt) with simple token issue/verify service.
-  - [x] Configuration for CORS origins, headers, methods.
-  - [x] Bind FeatureFlagClientInterface with a default adapter (Flagpole); add small sample usage and env config.
-* Acceptance:
-  - [x] CORS preflight and secured endpoints behave as configured; JWT‑protected route example works.
-
-[↑ Back to Top](#table-of-contents)
-## M11 — Logging, HTTP client, and filesystem
-* Tasks:
-  - [x] Monolog setup with handlers and processors (request ID, memory, timing).
-  - [x] Guzzle PSR‑18 client exposure; DI binding for HTTP client interface.
-  - [x] Flysystem integration with local adapter; abstraction for storage disks.
-  - [x] Standardize all core service providers with robust driver validation (similar to OrmServiceProvider).
-  - [x] Opportunity Radar: Multiple storage disks, log channel management, and HTTP client middleware.
-  - [x] Opportunity Radar 2: Storage Disk "Cloud" Adapters (S3), Advanced HTTP Middleware (Circuit Breaker), and Log Alerting (Slack/Sentry).
-  - [x] Opportunity Radar 3: Githook Integration, Breadcrumb Automation, and TOC for MILESTONES.md.
-  - [x] Opportunity Radar 4: Middleware Groups and Centralized Route List Command.
-  - [x] Opportunity Radar 5: FeatureTestCase, Middleware Group Auto-Mounting, and Route Caching.
-* Acceptance:
-  - [x] Logs include correlation IDs; sample outbound HTTP call via client; file upload/storage demo works.
-
-[↑ Back to Top](#table-of-contents)
-## M12 — Serialization/validation utilities and pagination
-* Tasks:
-  - [x] REST default: Symfony Serializer normalizers/encoders; document extension points.
-  - [x] Add simple validation layer using `Phred\Http\Middleware\Middleware` base.
-  - [x] Pagination helpers (links/meta), REST and JSON:API compatible outputs.
-  - [x] URL extension negotiation: add XML support
-    - [x] Provide `XmlResponseFactory` (or encoder) and integrate with negotiation.
-    - [x] Enable `xml` in `URL_EXTENSION_WHITELIST` by default.
-  - [x] Opportunity Radar: Storage URL generation, Circuit Breaker persistence (PSR-16), and HTTP client profiling.
-* Acceptance:
-  - [x] Example endpoint validates input, returns 422 with details; paginated listing includes links/meta.
-
-[↑ Back to Top](#table-of-contents)
-## M13 — OpenAPI and documentation
-* Tasks:
-  - [x] Integrate `zircote/swagger-php` annotations.
-  - [x] CLI/task to generate OpenAPI JSON; optional serve route and Redoc UI pointer.
-  - [x] Document auth, pagination, error formats.
-* Acceptance:
-  - [x] Generated OpenAPI document validates; matches sample endpoints.
-
-[↑ Back to Top](#table-of-contents)
-## M14 — Testing, quality, and DX
-* Tasks:
-  - [x] Establish testing structure with Codeception (unit, integration, API suites).
-  - [x] Add fixtures/factories via Faker for examples.
-  - [x] PHPStan level selection and baseline; code style via php-cs-fixer ruleset.
-  - [x] Pre‑commit hooks (e.g., GrumPHP) or custom git hooks for staged files.
-  - [x] Define TestRunnerInterface and a Codeception adapter; otherwise, state tests are run via Composer script only.
-* Acceptance:
-  - [x] `composer test` runs green across suites; static analysis passes.
-  - [x] CLI tests run via TestRunnerInterface;
-  - [x] CLI tests run green per module and across suites.
-
-[↑ Back to Top](#table-of-contents)
-## M15 — Caching and performance (optional default)
-* Tasks:
-  - [x] Provide `PSR-16` cache interface binding; suggest `symfony/cache` when enabled.
-  - [x] Simple response caching middleware and ETag/Last‑Modified helpers.
-  - [x] Rate limiting middleware (token bucket) suggestion/integration point.
-* Acceptance:
-  - [x] Sample endpoint demonstrates cached responses and conditional requests.
-
-[↑ Back to Top](#table-of-contents)
-## M16 — Production hardening and deployment
-* Tasks:
-  - [x] Config for envs (dev/test/stage/prod), error verbosity, trusted proxies/hosts.
-  - [x] Docker example, PHP‑FPM + Nginx config templates.
-  - [x] Healthcheck endpoint, readiness/liveness probes.
-* Acceptance:
-  - [x] Containerized demo serves both API and template pages; healthchecks pass.
-
-[↑ Back to Top](#table-of-contents)
-## M17 — JSON:API enhancements (optional package)
-* Tasks:
-  - [x] If enabled, integrate `neomerx/json-api` fully: includes, sparse fieldsets, relationships, sorting, filtering, pagination params.
-  - [x] Adapters/Schema providers per resource type.
-* Acceptance:
-  - [x] JSON:API conformance tests for selected endpoints pass; docs updated.
-
-[↑ Back to Top](#table-of-contents)
-## M18 — Examples and starter template
-* Tasks:
-  - [x] Create `examples/shop` module showcasing controllers, views, templates, ORM, auth, pagination, and both API formats.
-  - [x] Ensure examples use the external stubs and module-specific CLI command conventions.
-  - [x] Provide `composer create-project` skeleton template instructions.
-* Acceptance:
-  - [x] New users can scaffold a working app in minutes following README.
-
-[↑ Back to Top](#table-of-contents)
-## M19 — Documentation site
-* Tasks:
-  - [x] Build the official documentation site (getphred.com) using the Phred framework.
-  - [x] Internal Documentation API: Design a "Documentation Module" that parses Markdown files from the repo to serve them dynamically.
-  - [x] Automated TOC Generation: Script to regenerate SPECS.md Table of Contents.
-  - [x] Versioned docs and upgrade notes.
-* Acceptance:
-  - [x] Docs published; links in README; examples maintained.
-
-[↑ Back to Top](#table-of-contents)
-## M20 — Dynamic Command Help
-* Tasks:
-  - [x] Implement a `docs` command in `phred` (e.g., `php phred docs <command>`) that opens the relevant documentation page in the user's browser.
-  - [x] Build the `docs` command logic after the documentation site (getphred.com) is functional.
-* Acceptance:
-  - [x] `php phred docs create:module` opens the correct URL in the default browser.
-
-[↑ Back to Top](#table-of-contents)
-## M21 — Governance and roadmap tracking
-* Tasks:
-  - [x] Define contribution guide, issue templates, RFC process for changes.
-  - [x] Public roadmap (this milestone list) tracked as GitHub Projects/Issues.
-* Acceptance:
-  - [x] Contributors can propose features via RFC; roadmap is visible and updated.
-
-[↑ Back to Top](#table-of-contents)
diff --git a/SPECS.md b/SPECS.md
index 2da94be..8c81632 100644
--- a/SPECS.md
+++ b/SPECS.md
@@ -1,161 +1,3 @@
 # Phred Technical Specifications
 
 [← Back to README](./README.md) | [MILESTONES.md](./MILESTONES.md)
-
-## Table of Contents
-- [1. Core Framework](#1-core-framework)
-  - [1.1 API Formats and Content Negotiation](#1-1-api-formats-and-content-negotiation)
-  - [1.2 Pluggability Model (M5)](#1-2-pluggability-model-m5)
-  - [1.3 URL Extension Negotiation](#1-3-url-extension-negotiation)
-  - [1.4 Dependencies](#1-4-dependencies)
-- [2. MVC Components](#2-mvc-components)
-  - [2.1 Controllers](#2-1-controllers)
-  - [2.2 Views (M6)](#2-2-views-m6)
-  - [2.3 Services](#2-3-services)
-- [3. Modular Architecture (M7)](#3-modular-architecture-m7)
-  - [3.1 Module Layout (ORM-Agnostic)](#3-1-module-layout-orm-agnostic)
-  - [3.2 Modular Separation](#3-2-modular-separation)
-- [4. Infrastructure](#4-infrastructure)
-  - [4.1 Service Providers (M5)](#4-1-service-providers-m5)
-  - [4.2 Configuration and Environment](#4-2-configuration-and-environment)
-  - [4.3 Command Discovery](#4-3-command-discovery)
-- [5. Technical Examples](#5-technical-examples)
-  - [5.1 Configuration Access](#5-1-configuration-access)
-  - [5.2 API Negotiation](#5-2-api-negotiation)
-  - [5.3 Route Group Inclusion](#5-3-route-group-inclusion)
-
-This document outlines the technical specifications and architectural standards of the Phred framework.
-
-## 1. Core Framework
-
-### 1.1 API Formats and Content Negotiation
-Phred supports two primary API formats:
-* **Pragmatic REST (default)**: Plain JSON responses using RFC 7807 for error handling.
-* **JSON:API**: Compliant with the JSON:API specification for documents and error objects.
-
-Negotiation can be set globally via `.env`:
-* `API_FORMAT=rest`
-* `API_FORMAT=jsonapi`
-
-Clients can override the format per request using the `Accept` header:
-* `Accept: application/vnd.api+json` forces JSON:API.
-* `Accept: application/xml` or `text/xml` (M12+).
-
-### 1.2 Pluggability Model (M5)
-The framework is fully pluggable. Core components depend on Phred contracts and PSRs; concrete implementations are provided by Service Providers.
-* Providers implement `Phred\Support\Contracts\ServiceProviderInterface`.
-* Lifecycle methods: `register(ContainerBuilder)` and `boot(Container)`.
-* Loading order: Core → App → Modules (defined in `config/providers.php`).
-
-**Primary Contracts:**
-* `Template\Contracts\RendererInterface`
-* `Orm\Contracts\ConnectionInterface`
-* `Flags\Contracts\FeatureFlagClientInterface`
-* `Testing\Contracts\TestRunnerInterface`
-
-### 1.3 URL Extension Negotiation
-Optional middleware that hints content negotiation based on URL suffix.
-* Enabled via `URL_EXTENSION_NEGOTIATION=true` (default).
-* Whitelist via `URL_EXTENSION_WHITELIST` (default: "json|xml|php|none").
-* **Mappings:**
-    * `.json` → `application/json`
-    * `.xml` → `application/xml`
-    * `.php` or none → `text/html` (View convention)
-
-### 1.4 Dependencies
-Phred leverages several industry-standard packages:
-* **Dependency Injection**: `php-di/php-di`
-* **Static Analysis**: `phpstan/phpstan`
-* **Code Style**: `friendsofphp/php-cs-fixer`
-* **Logging**: `monolog/monolog`
-* **Environment**: `vlucas/phpdotenv`
-* **HTTP Client**: `guzzlehttp/guzzle`
-* **CORS**: `middlewares/cors`
-* **Authentication**: `lcobucci/jwt`
-* **Feature Flags**: `getphred/flagpole`
-* **ORM**: `getphred/pairity`
-* **Template Engine**: `getphred/eyrie`
-* **Router**: `nikic/fast-route`
-* **PSR-7/15**: `relay/relay`, `nyholm/psr7`
-
-## 2. MVC Components
-
-### 2.1 Controllers
-* **Invokable**: Controllers are "Actions" with a single entry point: `public function __invoke(Request $request)`.
-* **Response Factories**: Injected via `Phred\Http\Contracts\ApiResponseFactoryInterface`.
-* **Base Classes (M6)**:
-    * `Phred\Mvc\APIController`: For API-only endpoints.
-    * `Phred\Mvc\ViewController`: For HTML/Template endpoints.
-
-### 2.2 Views (M6)
-* Classes dedicated to data preparation before rendering.
-* Extend `Phred\Mvc\View`.
-* Methods:
-    * `transformData(array $data)`: Manipulate data before it hits the template.
-    * `defaultTemplate()`: Define the default template for the view.
-* **Conventions**: Controllers call `renderView($view, $data, ?$templateOverride)`. If no override is provided, the View decides the template.
-
-### 2.3 Services
-* Business logic should reside in Service classes to keep controllers lean and models ORM-neutral.
-
-## 3. Modular Architecture (M7)
-
-Phred follows a Django-style modular structure where all user code lives inside modules.
-
-### 3.1 Module Layout (ORM-Agnostic)
-* `modules/<Module>/Controllers/`
-* `modules/<Module>/Views/`
-* `modules/<Module>/Templates/`
-* `modules/<Module>/Services/`
-* `modules/<Module>/Models/` (Domain models, pure PHP)
-* `modules/<Module>/Repositories/` (Interfaces consumed by services)
-* `modules/<Module>/Persistence/Pairity/` (Driver-specific implementations)
-* `modules/<Module>/Persistence/Eloquent/` (Driver-specific implementations)
-* `modules/<Module>/Database/Migrations/` (Canonical migrations)
-* `modules/<Module>/Routes/web.php` and `api.php`
-* `modules/<Module>/Providers/*ServiceProvider.php`
-
-### 3.2 Modular Separation
-Modules encapsulate their own:
-* Models, Controllers, Views, Services, Migrations, Providers, Routes, Templates, and Tests.
-
-## 4. Infrastructure
-
-### 4.1 Service Providers (M5)
-Providers are the glue of the framework.
-* **Configuration**: `config/providers.php`
-* **Route Registration**: Use `RouteRegistry::add(static function($collector, $router) { ... })`.
-
-### 4.2 Configuration and Environment
-* **Dotenv**: Loads `.env` from the project root.
-* **Config Facade**: `Phred\Support\Config::get(<key>, <default>)`.
-* **Precedence**: Environment variables > Config files (`config/*.php`) > Defaults.
-* **Notation**: Supports both `UPPER_SNAKE` and `dot.notation`.
-
-### 4.3 Command Discovery
-* **Core Commands**: Discovered from `src/commands`.
-* **User Commands**: Discovered from `console/commands`.
-* Custom commands must return an instance of `Phred\Console\Command`.
-
-## 5. Technical Examples
-
-### 5.1 Configuration Access
-```php
-use Phred\Support\Config;
-
-$env = Config::get('APP_ENV', 'local');      // environment check
-$tz  = Config::get('app.timezone', 'UTC');   // dotted notation from config/app.php
-```
-
-### 5.2 API Negotiation
-The chosen format is stored on the request as `phred.api_format` and used by the `ApiResponseFactoryInterface` to determine the response shape.
-
-### 5.3 Route Group Inclusion
-```php
-use Phred\Http\Routing\RouteGroups;
-use Phred\Http\Router;
-
-RouteGroups::include($router, '/prefix', function (Router $router) {
-    require __DIR__ . '/../path/to/routes.php';
-});
-```