docs(#2): add phase 0 assessment findings and TODO

- Add comprehensive FINDINGS.md documenting: - Environment assessment (PHP 8.3.6, missing extensions) - Test suite results (197 tests passing, 11.6% coverage) - Code quality analysis (Pint ✅, PHPStan Level 1 ✅) - Architecture patterns (event-driven, frontages, L1 packages) - Test coverage gaps by package - Security observations and risks - Dependency concerns (PHP version mismatch with psalm) - Add detailed TODO.md with phased improvement plan: - Phase 1: Fix failing tests ✅ COMPLETE - Phase 2: Increase coverage to 80%+ (446 hours) - Phase 3: Increase PHPStan to level 6+ (73 hours) - Phase 4: Security review (113 hours) - Total effort: 632 hours (~16 weeks) All tests passing (197/197), zero lint issues, zero static analysis errors at current configuration. Critical gaps identified in CDN, Media, SEO, Storage, and Config packages. Co-Authored-By: Clotho <clotho@lthn.ai>
2026-02-20 02:02:26 +00:00 · 2026-02-20 02:02:26 +00:00 · 742e53a9e3
commit 742e53a9e3
parent a47f038680
2 changed files with 1374 additions and 9 deletions
--- a/FINDINGS.md
+++ b/FINDINGS.md
@ -0,0 +1,829 @@
+# FINDINGS: Core PHP Framework Assessment
+
+**Repository**: core/php-framework
+**Branch**: dev
+**Assessment Date**: 2026-02-20
+**Agent**: Clotho
+**Issue**: #2
+
+## Executive Summary
+
+The Core PHP Framework is in **good baseline health** with solid fundamentals but significant test coverage gaps. The codebase demonstrates mature architectural patterns with event-driven module loading and lazy instantiation. Quality metrics show zero current failures but identify substantial technical debt in test coverage and static analysis configuration.
+
+### Health Score: 6.5/10
+
+**Strengths**:
+- ✅ All 197 tests passing (100% pass rate)
+- ✅ Zero lint violations (Pint)
+- ✅ Zero static analysis errors (PHPStan Level 1)
+- ✅ Modern architecture (event-driven, lazy loading)
+- ✅ Good code formatting standards
+
+**Weaknesses**:
+- ⚠️ Low test coverage: 11.6% (63/542 files)
+- ⚠️ PHPStan running at minimum level (1 of 9)
+- ⚠️ Critical packages completely untested (CDN, Media, SEO, Storage)
+- ⚠️ Many error categories ignored in static analysis
+- ⚠️ PHP version mismatch (8.3.6 vs 8.3.16+ required by psalm)
+
+---
+
+## 1. Environment Assessment
+
+### 1.1 Initial State
+
+**Branch**: dev (origin/dev)
+**Git Status**: Clean working tree
+**Composer Lock**: Missing (regenerated during install)
+
+### 1.2 PHP Environment
+
+**Version**: PHP 8.3.6
+**Missing Extensions** (initial):
+- ext-dom
+- ext-curl
+- ext-xml
+- ext-mbstring
+- ext-zip
+- ext-sqlite3
+- ext-gd
+
+**Resolution**: All extensions installed successfully via apt-get.
+
+**Issue Identified**: PHP 8.3.6 is below the minimum required by \`vimeo/psalm\` (requires ~8.3.16). This is a Ubuntu package repository limitation - 8.3.6 is the latest available in Ubuntu 24.04 stable repositories.
+
+**Workaround Applied**: Used \`--ignore-platform-req=php\` to complete installation.
+
+**Recommendation**: Either:
+1. Remove or relax psalm version constraint, OR
+2. Use PHP PPA for newer 8.3.x versions, OR
+3. Document this as a known limitation for Ubuntu 24.04 LTS environments
+
+### 1.3 Composer Dependencies
+
+**Status**: ✅ Installed successfully
+**Total Packages**: 176 (lock file created)
+**Framework Version**: Laravel 12.52.0
+**PHPUnit Version**: 11.5.55
+**PHPStan Version**: 2.1.39
+**Psalm Version**: 6.15.1
+
+**Security**: Roave security-advisories already integrated ✅
+
+---
+
+## 2. Test Suite Assessment
+
+### 2.1 Test Execution Results
+
+**Command**: \`vendor/bin/phpunit --testdox\`
+**Result**: ✅ PASS
+
+**Statistics**:
+- **Tests**: 197
+- **Assertions**: 393
+- **Failures**: 0
+- **Errors**: 0
+- **Warnings**: 1 (code coverage driver not available)
+- **Time**: 1.176 seconds
+- **Memory**: 50.50 MB
+
+### 2.2 Test Distribution
+
+**Feature Tests** (tests/Feature/):
+- Activity Log Service: 14 tests
+- Admin Menu Registry: 12 tests
+- Event Audit Log: 10 tests
+- Input: 4 tests
+- Lazy Module Listener: 10 tests
+- Lifecycle Event Provider: 9 tests
+- Lifecycle Events: 21 tests
+- Logs Activity Trait: 12 tests
+- Module Registry: 12 tests
+- Module Scanner: 16 tests
+- Pro: 16 tests
+- Sanitiser: 26 tests
+- Seeder Discovery: 16 tests
+- Seeder Registry: 15 tests
+
+**Co-located Tests**:
+- src/Core/Bouncer/Tests/: 3 test files
+- src/Core/Config/Tests/: 1 test file
+- src/Core/Front/Tests/: 1 test file
+- src/Core/Input/Tests/: 1 test file
+- src/Core/Service/Tests/: 3 test files
+- src/Mod/Trees/Tests/: 9 test files
+
+### 2.3 Test Quality Observations
+
+**Positive Patterns**:
+- Comprehensive assertions (average 2 per test)
+- Good use of test doubles and mocking
+- Feature tests use Orchestra Testbench correctly
+- Tests follow AAA pattern (Arrange, Act, Assert)
+- Good test naming (descriptive, readable)
+
+**Missing Coverage**:
+- No tests for critical business logic (CDN, Media, SEO)
+- No integration tests for cross-module workflows
+- No performance tests for caching/optimisation
+- Limited error path testing
+- No security-specific test suite
+
+---
+
+## 3. Code Quality Assessment
+
+### 3.1 Laravel Pint (Linter)
+
+**Command**: \`vendor/bin/pint --test\`
+**Result**: ✅ PASS
+
+**Output**: \`{"result":"pass"}\`
+
+**Analysis**: Codebase adheres perfectly to Laravel Pint's PSR-12 based coding standards. No formatting issues detected.
+
+### 3.2 PHPStan (Static Analysis)
+
+**Command**: \`vendor/bin/phpstan analyse --memory-limit=512M\`
+**Result**: ✅ PASS (with caveats)
+
+**Configuration** (phpstan.neon):
+```yaml
+level: 1  # Lowest level (0-9 available)
+paths:
+  - src
+```
+
+**Errors**: 0 (at level 1)
+
+**Files Analysed**: 515
+
+**Critical Concerns**:
+
+#### 3.2.1 Ignored Error Categories
+```yaml
+ignoreErrors:
+  - '#Unsafe usage of new static#'
+  - '#env\\(\\).*outside of the config directory#'
+  - identifier: larastan.noEnvCallsOutsideOfConfig
+  - identifier: trait.unused
+  - identifier: class.notFound
+  - identifier: function.deprecated
+  - identifier: method.notFound
+```
+
+**Analysis**: These ignored categories mask potentially serious issues:
+- \`new static\` usage may hide LSP violations
+- \`env()\` calls outside config violate Laravel best practices
+- Unused traits may indicate dead code
+- Deprecated function usage needs tracking
+- Missing class/method references may break at runtime
+
+**Risk Level**: Medium - these could hide real bugs
+
+#### 3.2.2 Excluded Paths
+```yaml
+excludePaths:
+  - src/Core/Activity
+  - src/Core/Config/Tests
+  - src/Core/Input/Tests
+  - src/Core/Tests
+  - src/Core/Bouncer/Tests
+  - src/Core/Bouncer/Gate/Tests
+  - src/Core/Service/Tests
+  - src/Core/Front/Tests
+  - src/Mod/Trees
+```
+
+**Analysis**: Test directories are appropriately excluded, but:
+- \`src/Core/Activity\` exclusion is concerning (production code)
+- \`src/Mod/Trees\` exclusion may hide issues in the best-tested module
+
+**Recommendation**: Review Activity package exclusion reason, consider removing Trees exclusion.
+
+### 3.3 PHPStan Level Analysis
+
+**Current Level**: 1 (out of 9)
+
+**What Level 1 Checks**:
+- Basic unknown classes
+- Unknown functions
+- Unknown methods on \`$this\`
+- Wrong number of arguments passed to methods
+
+**What's NOT Checked** (Levels 2-9):
+- Unknown properties
+- Unknown magic methods
+- Possibly undefined variables
+- Unknown array keys
+- Unreachable code
+- Type checking
+- Strict type checking
+- Mixed type restrictions
+- Strict rules
+
+**Impact**: Running at level 1 provides minimal type safety. Critical type errors, null pointer issues, and unreachable code remain undetected.
+
+---
+
+## 4. Architecture Patterns Discovered
+
+### 4.1 Event-Driven Module Loading
+
+**Pattern**: Modules declare interest in lifecycle events via static \`$listens\` arrays and are only instantiated when those events fire.
+
+**Implementation**:
+```
+LifecycleEventProvider::register()
+  └── ModuleScanner::scan()        # Finds Boot.php with $listens
+  └── ModuleRegistry::register()   # Wires LazyModuleListener for each event
+```
+
+**Benefits**:
+- Web requests don't load admin modules
+- API requests don't load web modules
+- Lazy instantiation reduces memory footprint
+- Clear separation of concerns
+
+**Quality**: ✅ Well-designed, modern Laravel approach
+
+### 4.2 Frontages System
+
+**Pattern**: ServiceProviders in \`src/Core/Front/\` fire context-specific lifecycle events.
+
+**Frontages Discovered**:
+| Frontage | Event | Middleware | Context |
+|----------|-------|------------|---------|
+| Web | \`WebRoutesRegistering\` | \`web\` | Public routes |
+| Admin | \`AdminPanelBooting\` | \`admin\` | Admin panel |
+| Api | \`ApiRoutesRegistering\` | \`api\` | REST endpoints |
+| Client | \`ClientRoutesRegistering\` | \`client\` | Authenticated SaaS |
+| Cli | \`ConsoleBooting\` | - | Artisan commands |
+| Mcp | \`McpToolsRegistering\` | - | MCP tool handlers |
+
+**Quality**: ✅ Excellent separation of concerns, enables selective module loading
+
+### 4.3 L1 Package Structure
+
+**Pattern**: Subdirectories under \`src/Core/\` are self-contained packages with:
+- Own Boot.php (module entry point)
+- Own migrations
+- Own tests (co-located)
+- Own views
+
+**Packages Identified**:
+- Activity (8 files) - Activity logging wrapper for spatie/laravel-activitylog
+- Bouncer (14 files) - Security blocking/redirects
+- Cdn (20 files) - CDN integration (BunnyCDN, Flux)
+- Config (36 files) - Dynamic configuration system
+- Front (266 files) - Frontage system + Blade components
+- Lang (15 files) - Translation system
+- Media (23 files) - Media handling with thumbnails
+- Search (7 files) - Search functionality
+- Seo (19 files) - SEO utilities (OG images, sitemaps)
+- Storage (9 files) - Cache resilience, circuit breakers
+
+**Quality**: ✅ Good modular organisation, follows Laravel package conventions
+
+### 4.4 Actions Pattern
+
+**Pattern**: Single-purpose business logic classes with static \`run()\` helper.
+
+**Example**:
+```php
+class CreateOrder
+{
+    use Action;
+
+    public function __construct(private OrderService $orders) {}
+
+    public function handle(User $user, array $data): Order
+    {
+        return $this->orders->create($user, $data);
+    }
+}
+
+// Usage: CreateOrder::run($user, $validated);
+```
+
+**Quality**: ✅ Clean, testable, follows command pattern
+
+### 4.5 Seeder Ordering System
+
+**Pattern**: Seeders use PHP attributes for dependency ordering.
+
+**Attributes**:
+- \`#[SeederPriority(50)]\` - Lower runs first
+- \`#[SeederAfter(OtherSeeder::class)]\` - Dependency ordering
+- \`#[SeederBefore(OtherSeeder::class)]\` - Reverse dependency
+
+**Quality**: ✅ Elegant solution to seeder ordering problem, prevents circular dependencies
+
+### 4.6 HLCRF Layout System
+
+**Pattern**: Data-driven layouts with five regions (Header, Left, Content, Right, Footer).
+
+**Usage**:
+```php
+$page = Layout::make('HCF')  // Header-Content-Footer
+    ->h(view('header'))
+    ->c($content)
+    ->f(view('footer'));
+```
+
+**Variants**: C, HCF, HLCF, HLCRF
+
+**Quality**: ✅ Flexible, declarative layout system
+
+---
+
+## 5. Test Coverage Analysis
+
+### 5.1 Overall Statistics
+
+**Total PHP Files**: 542
+**Test Files**: 63
+**Coverage**: 11.6%
+
+**Breakdown**:
+- Core packages: 327 files, 9 tests (2.8%)
+- Mod/Trees: 19 files, 9 tests (47.4%)
+- Other: 196 files, 45 tests (22.9%)
+
+### 5.2 Zero Coverage Packages (Critical Risk)
+
+#### CDN Package (20 files, 0%)
+**Business Impact**: HIGH - Infrastructure for global asset delivery
+
+**Untested Components**:
+- \`BunnyCdnService.php\` - BunnyCDN API integration
+- \`FluxCdnService.php\` - FluxCDN integration
+- \`StorageOffload.php\` - Asset offloading logic
+- Console commands: PushAssetCommand, MigrateAssetsCommand
+- Middleware: RewriteCdnUrls, RedirectToCdn
+
+**Risk**: CDN failures could cause widespread asset delivery issues. No automated validation of:
+- API authentication
+- File upload/sync logic
+- URL rewriting correctness
+- Failover behaviour
+
+---
+
+#### Media Package (23 files, 0%)
+**Business Impact**: HIGH - User uploads, image processing
+
+**Untested Components**:
+- \`ImageOptimizer.php\` - Image compression/optimisation
+- Video thumbnail generation
+- Image resizing pipeline
+- Temporary file management
+- Media conversion queue jobs
+
+**Risk**: Image processing bugs could corrupt user uploads, cause data loss, or create security vulnerabilities (malicious file uploads).
+
+---
+
+#### SEO Package (19 files, 0%)
+**Business Impact**: HIGH - Search engine visibility, social sharing
+
+**Untested Components**:
+- OG image generation
+- Schema.org structured data validation
+- Sitemap generation
+- Meta tag controllers
+
+**Risk**: SEO bugs directly impact business visibility and traffic. Broken OG images harm social media sharing. Invalid schema.org markup reduces search rankings.
+
+---
+
+#### Storage Package (9 files, 0%)
+**Business Impact**: HIGH - Performance, reliability
+
+**Untested Components**:
+- \`ResilientRedisStore.php\` - Redis failover logic
+- \`TieredCache.php\` - Multi-tier caching
+- Circuit breaker pattern implementation
+- Cache warming system
+
+**Risk**: Cache failures could cascade to database overload. Circuit breaker bugs could prevent recovery from transient failures. No validation of failover logic.
+
+---
+
+#### Config System (36 files, 3%)
+**Business Impact**: MEDIUM - Dynamic configuration
+
+**Untested Components**:
+- \`ConfigService.php\` - Config CRUD operations
+- \`ConfigResolver.php\` - Config value resolution
+- Console commands (8 commands)
+- Models: ConfigKey, ConfigValue, ConfigProfile, ConfigVersion
+
+**Risk**: Configuration bugs could break multi-tenancy, prevent feature flag changes, or corrupt config state.
+
+---
+
+### 5.3 Partial Coverage Packages
+
+#### Bouncer (14 files, 21%)
+**Current Tests**: 3
+**Missing Tests**: 11
+**Components**: Security blocking, IP filtering, user agent detection
+
+#### Front Package (266 files, 0.4%)
+**Current Tests**: 1 (device detection)
+**Note**: Contains many Blade view components that may not require unit tests
+**Strategy**: Focus on feature tests for key user flows instead of testing every component
+
+#### Service Package (9 files, 33%)
+**Current Tests**: 3
+**Missing Tests**: 6
+**Components**: Core framework services
+
+---
+
+### 5.4 Well-Tested Reference: Trees Module
+
+**Coverage**: 47% (9 tests for 19 files)
+
+**Test Structure**:
+- \`TreePlantingTest.php\` - Feature test for planting functionality
+- \`TreeReferralTest.php\` - Feature test for referral system
+- \`TreeApiTest.php\` - API endpoint tests
+- \`TreeQueueTest.php\` - Queue job tests
+- \`AgentDetectionTest.php\` - User agent detection
+
+**Quality Observations**:
+- Well-structured feature tests
+- Good use of factories and seeders
+- Comprehensive assertions
+- Tests both happy path and error cases
+
+**Recommendation**: Use Trees module as template for implementing tests in Core packages.
+
+---
+
+## 6. Dependency Concerns
+
+### 6.1 PHP Version Mismatch
+
+**Issue**: \`vimeo/psalm ^6.14\` requires PHP ~8.3.16+
+**Environment**: PHP 8.3.6 (Ubuntu 24.04 LTS latest)
+**Impact**: Cannot update psalm without PHP upgrade
+**Workaround**: Using \`--ignore-platform-req=php\`
+
+**Options**:
+1. Use Ondřej Surý PPA for PHP 8.3.16+
+2. Relax psalm version constraint
+3. Remove psalm in favour of PHPStan-only approach
+4. Accept platform requirement override
+
+### 6.2 Missing Curl Extension Warning
+
+**Warning**: "Composer is operating significantly slower than normal because you do not have the PHP curl extension enabled."
+**Resolution**: Installed \`php8.3-curl\`
+**Impact**: Fixed after installation
+
+### 6.3 Missing Unzip Warning
+
+**Warning**: "As there is no 'unzip' nor '7z' command installed zip files are being unpacked using the PHP zip extension."
+**Impact**: Minor - may cause invalid corrupted archive reports, loses UNIX permissions
+**Recommendation**: Install \`unzip\` package
+
+### 6.4 Code Coverage Driver
+
+**Warning**: "No code coverage driver available"
+**Impact**: Cannot generate coverage reports
+**Resolution**: Install Xdebug or PCOV extension
+**Priority**: Medium (needed for Phase 2 coverage assessment)
+
+---
+
+## 7. Quality Issues Identified
+
+### 7.1 Critical
+
+1. **CDN Package Untested** - High business risk
+2. **Media Processing Untested** - Data loss risk, security risk
+3. **SEO System Untested** - Business visibility risk
+4. **Storage/Caching Untested** - Reliability risk
+
+### 7.2 High
+
+5. **Config System Undertested** - 1 test for 36 files
+6. **PHPStan Level Too Low** - Minimal type checking at level 1
+7. **Many Error Categories Ignored** - Masks potential bugs
+8. **PHP Version Mismatch** - Psalm incompatibility
+
+### 7.3 Medium
+
+9. **Front Package Undertested** - 266 files, 1 test (many are Blade components)
+10. **Bouncer Package Partially Tested** - Security component needs full coverage
+11. **Code Coverage Tooling Missing** - Cannot measure actual coverage percentage
+12. **Activity Package Excluded from PHPStan** - Production code not analysed
+
+### 7.4 Low
+
+13. **Missing Unzip Utility** - Minor performance impact
+14. **Helper Functions Untested** - 16 utility files
+15. **Search Functionality Untested** - 7 files
+16. **Language/Translation Untested** - 15 files
+
+---
+
+## 8. Security Observations
+
+### 8.1 Positive Findings
+
+✅ **Input Sanitisation**: \`Sanitiser.php\` has comprehensive tests (26 tests)
+- Strips null bytes
+- Strips control characters
+- Preserves safe characters (newlines, tabs)
+- Unicode normalisation
+- Nested array handling
+
+✅ **Security Advisories**: Roave security-advisories integrated in composer.json
+
+✅ **Activity Logging**: \`LogsActivityTrait\` tested (12 tests) for audit trail
+
+### 8.2 Security Gaps Requiring Review
+
+⚠️ **File Upload Handling** (Media package): Zero tests
+- No validation of file type checking
+- No validation of malicious file detection
+- No validation of path traversal prevention
+
+⚠️ **CDN Security** (Cdn package): Zero tests
+- No validation of signed URL generation
+- No validation of token authentication
+- No validation of access control
+
+⚠️ **Bouncer/Gate** (Security package): 21% coverage
+- Incomplete testing of authorisation logic
+- No tests for privilege escalation prevention
+- No tests for IP blocking/filtering edge cases
+
+⚠️ **Encryption** (Crypt package): Zero tests
+- No validation of encryption algorithm usage
+- No validation of key management
+- No validation of secure random generation
+
+⚠️ **Headers/CORS** (Headers package): Zero tests
+- No validation of CSP configuration
+- No validation of CORS rules
+- No validation of security headers
+
+### 8.3 Security Recommendations
+
+**Immediate Actions**:
+1. Test file upload validation and sanitisation (Phase 4A.2)
+2. Test authorisation logic in Bouncer/Gate (Phase 4B.1)
+3. Review encryption implementation (Phase 4C.1)
+
+**Future Actions**:
+4. Security audit of CDN access controls
+5. Penetration testing of file upload endpoints
+6. Review of all \`env()\` calls outside config (currently ignored by PHPStan)
+
+---
+
+## 9. Architecture Quality Assessment
+
+### 9.1 Strengths
+
+✅ **Event-Driven Design**: Excellent separation of concerns
+✅ **Lazy Loading**: Modules only loaded when needed
+✅ **Frontage System**: Clean context separation (Web/Admin/API/etc)
+✅ **L1 Package Structure**: Self-contained, modular, follows Laravel conventions
+✅ **Actions Pattern**: Testable, single-responsibility business logic
+✅ **Seeder Ordering**: Elegant dependency management with attributes
+✅ **HLCRF Layouts**: Flexible, declarative layout system
+
+### 9.2 Concerns
+
+⚠️ **Front Package Size**: 266 files (49% of codebase) in single package
+- May benefit from further subdivision
+- Many are Blade components (acceptable)
+- Consider extracting major subsystems
+
+⚠️ **Test Co-location**: Inconsistent approach
+- Some packages use \`Tests/\` subdirectory (good)
+- Some have no tests at all
+- Main \`tests/\` directory duplicates structure
+- Recommendation: Standardise on co-located tests
+
+⚠️ **Activity Package Excluded**: Production code excluded from PHPStan
+- Review exclusion reason
+- Consider fixing issues instead of excluding
+
+---
+
+## 10. Compliance & Standards
+
+### 10.1 Coding Standards
+
+✅ **PSR-12**: Full compliance via Laravel Pint
+✅ **UK English**: Specified in CLAUDE.md (colour, organisation, centre)
+✅ **Strict Types**: \`declare(strict_types=1);\` required per CLAUDE.md
+✅ **Type Hints**: All parameters and return types required per CLAUDE.md
+✅ **License**: EUPL-1.2 specified in composer.json
+
+### 10.2 Laravel Standards
+
+✅ **Service Providers**: Properly structured
+✅ **Facades**: Not overused (good)
+✅ **Eloquent Models**: Follow conventions
+✅ **Migrations**: Present in L1 packages
+✅ **Orchestra Testbench**: Correctly integrated
+
+### 10.3 Testing Standards
+
+✅ **PHPUnit 11**: Latest version
+✅ **Test Naming**: Descriptive, follows conventions
+✅ **Test Structure**: AAA pattern (Arrange, Act, Assert)
+⚠️ **Coverage**: Only 11.6% (below industry standard 80%)
+
+---
+
+## 11. Performance Considerations
+
+### 11.1 Positive Patterns
+
+✅ **Lazy Module Loading**: Reduces memory footprint
+✅ **Resilient Redis Store**: Failover support for cache
+✅ **Tiered Caching**: Multi-level cache strategy
+✅ **Circuit Breaker**: Prevents cascade failures
+✅ **CDN Integration**: Offloads static assets
+
+### 11.2 Performance Risks (Untested)
+
+⚠️ **Cache Failover Logic**: No tests for \`ResilientRedisStore\`
+⚠️ **Circuit Breaker**: No tests for circuit breaker pattern
+⚠️ **Image Optimisation**: No tests for \`ImageOptimizer\`
+⚠️ **CDN Offload**: No tests for \`StorageOffload\`
+
+**Impact**: Performance optimisations may have bugs that cause:
+- Cache stampedes
+- Database overload during cache failures
+- Image processing bottlenecks
+- CDN sync failures
+
+**Recommendation**: Prioritise testing Storage and Media packages in Phase 2A.
+
+---
+
+## 12. Recommendations Summary
+
+### 12.1 Immediate Actions (Week 1)
+
+1. ✅ **Install code coverage driver** (Xdebug or PCOV)
+2. ✅ **Install unzip utility** (\`sudo apt-get install unzip\`)
+3. ✅ **Resolve PHP version mismatch** (choose one approach from 6.1)
+4. ✅ **Baseline documentation** (commit TODO.md and FINDINGS.md)
+
+### 12.2 Phase 2 Priorities (Weeks 2-7)
+
+**Critical Packages** (Phase 2A - 210 hours):
+1. CDN Package (40 hours)
+2. Config System (60 hours)
+3. Media Processing (45 hours)
+4. SEO System (35 hours)
+5. Storage/Caching (30 hours)
+
+**Success Criteria**:
+- All critical packages have 80%+ test coverage
+- Business logic fully validated
+- Security vulnerabilities identified and tested
+
+### 12.3 Phase 3 Priorities (Weeks 8-9)
+
+**PHPStan Improvements** (73 hours):
+1. Incrementally increase to level 6
+2. Remove ignored error categories
+3. Remove excluded paths (except tests)
+4. Enable strict type checking
+
+**Success Criteria**:
+- PHPStan level 6+ with zero errors
+- No ignored categories
+- Production code not excluded
+
+### 12.4 Phase 4 Priorities (Weeks 10-12)
+
+**Security Review** (113 hours):
+1. Input validation and file uploads (35 hours)
+2. Authentication and authorisation (25 hours)
+3. Encryption and data security (20 hours)
+4. Infrastructure security (18 hours)
+5. Dependency audit (15 hours)
+
+**Success Criteria**:
+- Security audit report completed
+- Zero high-severity vulnerabilities
+- All inputs validated
+- Encryption properly implemented
+
+---
+
+## 13. Risk Assessment
+
+### 13.1 High Risk
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| CDN failures cause asset delivery issues | High | Medium | Test CDN package (Phase 2A.1) |
+| Image processing corrupts uploads | High | Medium | Test Media package (Phase 2A.3) |
+| Cache failures cause DB overload | High | Low | Test Storage package (Phase 2A.5) |
+| File upload security vulnerabilities | High | Medium | Security review (Phase 4A.2) |
+| Authorisation bypasses | High | Low | Test Bouncer + review (Phase 4B) |
+
+### 13.2 Medium Risk
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| SEO bugs reduce search visibility | Medium | Medium | Test SEO package (Phase 2A.4) |
+| Config errors break multi-tenancy | Medium | Low | Test Config package (Phase 2A.2) |
+| Type errors at runtime | Medium | Medium | Increase PHPStan level (Phase 3) |
+| Dependency vulnerabilities | Medium | Low | Regular audits (Phase 4E) |
+
+### 13.3 Low Risk
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| Helper function bugs | Low | Low | Test helpers (Phase 2B.2) |
+| Search functionality bugs | Low | Low | Test search (Phase 2B.3) |
+| Translation bugs | Low | Low | Test i18n (Phase 2B.4) |
+
+---
+
+## 14. Conclusion
+
+The Core PHP Framework demonstrates **mature architectural design** with event-driven module loading, lazy instantiation, and well-structured L1 packages. The **code quality is high** with zero lint violations and clean formatting.
+
+However, **significant technical debt exists** in test coverage (11.6%) and static analysis configuration (PHPStan level 1). Critical business packages (CDN, Media, SEO, Storage) have **zero test coverage**, creating **high risk** for production deployments.
+
+The **16-week improvement plan** outlined in TODO.md provides a realistic roadmap to:
+1. Achieve 80%+ test coverage
+2. Increase PHPStan to level 6+
+3. Complete security review
+4. Address all high and medium risks
+
+The framework has **solid foundations** and with focused effort on test coverage and security review, can achieve **production-grade quality standards**.
+
+**Overall Assessment**: Good potential, requires investment in testing and security validation.
+
+---
+
+## Appendix A: File Count by Package
+
+| Package | PHP Files | Test Files | Coverage % |
+|---------|-----------|------------|------------|
+| Front | 266 | 1 | 0.4% |
+| Config | 36 | 1 | 2.8% |
+| Media | 23 | 0 | 0% |
+| CDN | 20 | 0 | 0% |
+| Seo | 19 | 0 | 0% |
+| Mod/Trees | 19 | 9 | 47.4% |
+| Events | 16 | 0 | 0% |
+| Helpers | 16 | 0 | 0% |
+| Lang | 15 | 0 | 0% |
+| Bouncer | 14 | 3 | 21.4% |
+| Headers | 11 | 0 | 0% |
+| Storage | 9 | 0 | 0% |
+| Service | 9 | 3 | 33.3% |
+| Activity | 8 | 0 | 0% |
+| Console | 7 | 0 | 0% |
+| Database | 7 | 0 | 0% |
+| Search | 7 | 0 | 0% |
+| Mail | 5 | 0 | 0% |
+| Input | 2 | 1 | 50% |
+| Crypt | 2 | 0 | 0% |
+| Rules | 2 | 0 | 0% |
+| **TOTAL** | **542** | **63** | **11.6%** |
+
+---
+
+## Appendix B: Environment Details
+
+**Operating System**: Ubuntu 24.04 LTS (Noble)
+**Kernel**: Linux 6.8.0-100-generic
+**PHP**: 8.3.6 (cli)
+**Composer**: 2.x
+**Git**: Installed
+**Node**: 22.x (via nodesource)
+**Docker**: Available
+
+**PHP Extensions Installed**:
+- dom, curl, xml, mbstring, zip, sqlite3, gd
+- calendar, ctype, exif, ffi, fileinfo, ftp
+- gettext, iconv, phar, posix, readline, shmop
+- sockets, sysvmsg, sysvsem, sysvshm, tokenizer
+
+**PHP Extensions Missing**:
+- xdebug (for code coverage)
+- pcov (alternative for code coverage)
+
+---
+
+**End of Assessment Report**
--- a/TODO.md
+++ b/TODO.md
@ -1,15 +1,551 @@
-# Core PHP Framework - TODO
+# TODO: Core PHP Framework Quality Improvement Plan

-No pending tasks.
+**Repository**: core/php-framework
+**Branch**: dev
+**Assessment Date**: 2026-02-20
+**Agent**: Clotho
+
+## Executive Summary
+
+The framework is in **good baseline health**:
+- ✅ All 197 tests pass
+- ✅ Zero lint issues (Pint)
+- ✅ Zero static analysis errors (PHPStan Level 1)
+- ⚠️ Test coverage: 11.6% (63 test files / 542 PHP files)
+- ⚠️ PHPStan running at Level 1 (lowest)
+
+## Phase 1: Fix Failing Tests
+
+**Status**: ✅ COMPLETE
+
+All 197 tests pass successfully:
+- 197 tests, 393 assertions
+- No failures, no errors
+- 1 PHPUnit warning (code coverage driver not available)
+
+**Action Items**: None required - all tests passing.

 ---

-## Package Changelogs
+## Phase 2: Increase Coverage to 80%+

-For completed features and implementation details, see each package's changelog:
+**Current Coverage**: 11.6% (63/542 files)
+**Target Coverage**: 80% (434 files need tests)
+**Priority**: High

- `changelog/` (this repo)
- [core-admin changelog](https://github.com/host-uk/core-admin)
- [core-api changelog](https://github.com/host-uk/core-api)
- [core-mcp changelog](https://github.com/host-uk/core-mcp)
- [core-tenant changelog](https://github.com/host-uk/core-tenant)
+### Phase 2A: Critical Business Packages (Priority 1)
+
+These packages are business-critical and require immediate test coverage:
+
+#### 2A.1 CDN Package (20 files, 0% coverage)
+**Impact**: Infrastructure for asset delivery
+**Files**:
+- \`src/Core/Cdn/Services/BunnyCdnService.php\`
+- \`src/Core/Cdn/Services/FluxCdnService.php\`
+- \`src/Core/Cdn/Services/StorageOffload.php\`
+- \`src/Core/Cdn/Console/\` (4 commands)
+- \`src/Core/Cdn/Middleware/\` (2 middleware)
+
+**Test Types Needed**:
+- Unit tests for services
+- Integration tests for storage offload
+- Feature tests for console commands
+- HTTP tests for middleware
+
+**Estimated Effort**: 40 hours
+**Files to Create**: \`src/Core/Cdn/Tests/Feature/\`, \`src/Core/Cdn/Tests/Unit/\`
+
+---
+
+#### 2A.2 Config System (36 files, 3% coverage)
+**Impact**: Core configuration management
+**Current**: 1 test file for 36 files
+**Files**:
+- \`src/Core/Config/Services/ConfigService.php\`
+- \`src/Core/Config/Services/ConfigResolver.php\`
+- \`src/Core/Config/Models/\` (4 models)
+- \`src/Core/Config/Console/\` (8 commands)
+
+**Test Types Needed**:
+- Unit tests for ConfigService and ConfigResolver
+- Model tests for ConfigKey, ConfigValue, ConfigProfile, ConfigVersion
+- Feature tests for console commands
+- Integration tests for config resolution
+
+**Estimated Effort**: 60 hours
+**Files to Create**: Expand \`src/Core/Config/Tests/\`
+
+---
+
+#### 2A.3 Media/Image Processing (23 files, 0% coverage)
+**Impact**: Content handling and user uploads
+**Files**:
+- \`src/Core/Media/Image/ImageOptimizer.php\`
+- \`src/Core/Media/Conversion/\` (5 files)
+- \`src/Core/Media/Thumbnail/\` (4 files)
+- \`src/Core/Media/Temp/\` (2 files)
+
+**Test Types Needed**:
+- Unit tests for image optimisation
+- Integration tests for conversion pipeline
+- Feature tests for thumbnail generation
+- Unit tests for temporary file handling
+
+**Estimated Effort**: 45 hours
+**Files to Create**: \`src/Core/Media/Tests/Feature/\`, \`src/Core/Media/Tests/Unit/\`
+
+---
+
+#### 2A.4 SEO System (19 files, 0% coverage)
+**Impact**: Business visibility and search rankings
+**Files**:
+- \`src/Core/Seo/OgImage/\` (4 files)
+- \`src/Core/Seo/Schema/\` (5 files)
+- \`src/Core/Seo/Sitemap/\` (3 files)
+
+**Test Types Needed**:
+- Unit tests for OG image generation
+- Unit tests for schema validation
+- Integration tests for sitemap generation
+- HTTP tests for controllers
+
+**Estimated Effort**: 35 hours
+**Files to Create**: \`src/Core/Seo/Tests/Feature/\`, \`src/Core/Seo/Tests/Unit/\`
+
+---
+
+#### 2A.5 Storage/Caching (9 files, 0% coverage)
+**Impact**: Performance and reliability
+**Files**:
+- \`src/Core/Storage/Cache/ResilientRedisStore.php\`
+- \`src/Core/Storage/Cache/TieredCache.php\`
+- \`src/Core/Storage/CircuitBreaker/\` (3 files)
+
+**Test Types Needed**:
+- Unit tests for resilient Redis store
+- Integration tests for tiered caching
+- Unit tests for circuit breaker pattern
+- Performance tests for cache warming
+
+**Estimated Effort**: 30 hours
+**Files to Create**: \`src/Core/Storage/Tests/Feature/\`, \`src/Core/Storage/Tests/Unit/\`
+
+---
+
+### Phase 2B: Infrastructure Packages (Priority 2)
+
+#### 2B.1 Activity Logging (8 files, 0% coverage)
+**Impact**: Audit trail and compliance
+**Estimated Effort**: 15 hours
+
+#### 2B.2 Helpers (16 files, 0% coverage)
+**Impact**: Widely used utility functions
+**Estimated Effort**: 25 hours
+
+#### 2B.3 Search (7 files, 0% coverage)
+**Impact**: User-facing functionality
+**Estimated Effort**: 15 hours
+
+#### 2B.4 Language/Translation (15 files, 0% coverage)
+**Impact**: i18n support
+**Estimated Effort**: 20 hours
+
+#### 2B.5 Events System (16 files, 0% coverage)
+**Impact**: Core lifecycle events
+**Estimated Effort**: 25 hours
+
+---
+
+### Phase 2C: Supporting Components (Priority 3)
+
+#### 2C.1 Headers/Security (11 files, 0% coverage)
+**Estimated Effort**: 18 hours
+
+#### 2C.2 Console Commands (7 files, 0% coverage)
+**Estimated Effort**: 12 hours
+
+#### 2C.3 Database/Seeders (7 files, 0% coverage)
+**Estimated Effort**: 12 hours
+
+#### 2C.4 Mail System (5 files, 0% coverage)
+**Estimated Effort**: 10 hours
+
+#### 2C.5 Validation Rules (2 files, 0% coverage)
+**Estimated Effort**: 5 hours
+
+#### 2C.6 Encryption/Crypt (2 files, 0% coverage)
+**Estimated Effort**: 5 hours
+
+---
+
+### Phase 2D: Improve Existing Coverage
+
+#### 2D.1 Bouncer (14 files, 21% coverage)
+**Current**: 3 test files
+**Target**: 11 more test files
+**Estimated Effort**: 20 hours
+
+#### 2D.2 Front Package (266 files, 0.4% coverage)
+**Note**: Many are Blade components that may not need unit tests
+**Strategy**: Focus on feature tests for key flows
+**Estimated Effort**: 40 hours (selective testing)
+
+#### 2D.3 Input (2 files, 50% coverage)
+**Current**: 1 test file
+**Target**: 1 more test file
+**Estimated Effort**: 2 hours
+
+#### 2D.4 Service (9 files, 33% coverage)
+**Current**: 3 test files
+**Target**: 6 more test files
+**Estimated Effort**: 12 hours
+
+---
+
+### Phase 2 Summary
+
+**Total Estimated Effort**: 446 hours (~11 weeks at 40 hrs/week)
+
+**Recommended Approach**:
+1. Start with Phase 2A (critical packages) - 210 hours
+2. Move to Phase 2B (infrastructure) - 100 hours
+3. Complete Phase 2C (supporting) - 62 hours
+4. Finish with Phase 2D (improve existing) - 74 hours
+
+**Success Metrics**:
+- Achieve 80%+ test coverage
+- All critical business logic covered
+- Integration tests for key workflows
+- Performance tests for caching/optimisation
+
+---
+
+## Phase 3: Fix All PHPStan Errors
+
+**Current Level**: 1 (lowest)
+**Current Errors**: 0
+**Target Level**: 6+ (recommended for production)
+**Priority**: Medium
+
+### Phase 3A: Gradually Increase PHPStan Level
+
+#### 3A.1 Run PHPStan at Level 2
+**Action**: Update \`phpstan.neon\` to \`level: 2\` and fix errors
+**Estimated Errors**: 50-100 (typical for level increase)
+**Estimated Effort**: 10 hours
+
+#### 3A.2 Run PHPStan at Level 3
+**Action**: Update to \`level: 3\` and fix errors
+**Estimated Errors**: 30-60
+**Estimated Effort**: 8 hours
+
+#### 3A.3 Run PHPStan at Level 4
+**Action**: Update to \`level: 4\` and fix errors
+**Estimated Errors**: 20-40
+**Estimated Effort**: 8 hours
+
+#### 3A.4 Run PHPStan at Level 5
+**Action**: Update to \`level: 5\` and fix errors
+**Estimated Errors**: 15-30
+**Estimated Effort**: 10 hours
+
+#### 3A.5 Run PHPStan at Level 6+
+**Action**: Update to \`level: 6\` or higher and fix errors
+**Estimated Errors**: 10-25
+**Estimated Effort**: 12 hours
+
+---
+
+### Phase 3B: Remove Ignored Error Categories
+
+**Current Ignored Errors**:
+\`\`\`
+- '#Unsafe usage of new static#'
+- '#env\\(\\).*outside of the config directory#'
+- identifier: larastan.noEnvCallsOutsideOfConfig
+- identifier: trait.unused
+- identifier: class.notFound
+- identifier: function.deprecated
+- identifier: method.notFound
+\`\`\`
+
+**Action Items**:
+1. Review each ignored category
+2. Fix underlying issues
+3. Remove from ignore list
+4. Re-enable strict checking
+
+**Estimated Effort**: 15 hours
+
+---
+
+### Phase 3C: Remove Excluded Paths
+
+**Current Excluded Paths**:
+\`\`\`
+- src/Core/Activity
+- src/Core/Config/Tests
+- src/Core/Input/Tests
+- src/Core/Tests
+- src/Core/Bouncer/Tests
+- src/Core/Bouncer/Gate/Tests
+- src/Core/Service/Tests
+- src/Core/Front/Tests
+- src/Mod/Trees
+\`\`\`
+
+**Action**: Remove exclusions and fix errors in excluded paths
+**Estimated Effort**: 10 hours
+
+---
+
+### Phase 3 Summary
+
+**Total Estimated Effort**: 73 hours (~2 weeks)
+
+**Recommended Approach**:
+1. Complete Phase 2A (critical test coverage) first
+2. Incrementally increase PHPStan levels
+3. Fix errors at each level before proceeding
+4. Remove ignored categories and exclusions last
+
+**Success Metrics**:
+- PHPStan Level 6+ with zero errors
+- No ignored error categories
+- No excluded paths
+- Strict type checking enabled
+
+---
+
+## Phase 4: Security Review
+
+**Priority**: High
+**Prerequisites**: Phase 2A complete (critical packages tested)
+
+### Phase 4A: Input Validation & Sanitisation
+
+#### 4A.1 Review Input Handling
+**Files to Review**:
+- \`src/Core/Input/Sanitiser.php\` ✅ (has tests)
+- All controllers and form requests
+- API endpoints
+
+**Security Checks**:
+- XSS prevention
+- SQL injection prevention
+- Command injection prevention
+- Path traversal prevention
+- Mass assignment protection
+
+**Estimated Effort**: 20 hours
+
+---
+
+#### 4A.2 Review File Upload Handling
+**Files to Review**:
+- \`src/Core/Media/\` (all file handling)
+- Upload controllers
+- Storage configuration
+
+**Security Checks**:
+- File type validation
+- File size limits
+- Malicious file detection
+- Storage path security
+- CDN upload security
+
+**Estimated Effort**: 15 hours
+
+---
+
+### Phase 4B: Authentication & Authorisation
+
+#### 4B.1 Review Bouncer/Gate System
+**Files to Review**:
+- \`src/Core/Bouncer/\` (all files)
+- \`src/Core/Bouncer/Gate/\` (all files)
+
+**Security Checks**:
+- Authorisation logic correctness
+- Privilege escalation prevention
+- Session security
+- CSRF protection
+
+**Estimated Effort**: 15 hours
+
+---
+
+#### 4B.2 Review Authentication Flows
+**Files to Review**:
+- Login controllers
+- Password reset flows
+- API authentication
+
+**Security Checks**:
+- Brute force protection
+- Password strength requirements
+- Token expiration
+- Multi-factor authentication support
+
+**Estimated Effort**: 10 hours
+
+---
+
+### Phase 4C: Data Security
+
+#### 4C.1 Review Encryption
+**Files to Review**:
+- \`src/Core/Crypt/\` (all files)
+- Any encrypted data storage
+
+**Security Checks**:
+- Encryption algorithm strength
+- Key management
+- Secure random generation
+- No hardcoded secrets
+
+**Estimated Effort**: 8 hours
+
+---
+
+#### 4C.2 Review Data Exposure
+**Files to Review**:
+- API responses
+- Error messages
+- Log files
+- Debug output
+
+**Security Checks**:
+- No sensitive data in logs
+- No stack traces in production
+- API response sanitisation
+- Database query obfuscation
+
+**Estimated Effort**: 12 hours
+
+---
+
+### Phase 4D: Infrastructure Security
+
+#### 4D.1 Review Headers & CORS
+**Files to Review**:
+- \`src/Core/Headers/\` (all files)
+- CORS middleware
+- CSP configuration
+
+**Security Checks**:
+- Security headers present
+- CSP properly configured
+- CORS restrictions
+- XSS protection headers
+
+**Estimated Effort**: 8 hours
+
+---
+
+#### 4D.2 Review CDN Security
+**Files to Review**:
+- \`src/Core/Cdn/\` (all files)
+
+**Security Checks**:
+- Signed URLs for private assets
+- Token validation
+- Rate limiting
+- Hotlink protection
+
+**Estimated Effort**: 10 hours
+
+---
+
+### Phase 4E: Dependency Security
+
+#### 4E.1 Review Composer Dependencies
+**Action**: Run \`composer audit\` and review
+**Files**: \`composer.json\`, \`composer.lock\`
+
+**Security Checks**:
+- Known vulnerabilities in dependencies
+- Outdated packages
+- Security advisories
+- Roave security-advisories integration ✅ (already present)
+
+**Estimated Effort**: 5 hours
+
+---
+
+#### 4E.2 Update Vulnerable Dependencies
+**Action**: Update packages with known vulnerabilities
+**Estimated Effort**: 10 hours
+
+---
+
+### Phase 4 Summary
+
+**Total Estimated Effort**: 113 hours (~3 weeks)
+
+**Recommended Approach**:
+1. Start with Phase 4A (input validation) - critical
+2. Move to Phase 4B (auth/authz) - high priority
+3. Complete Phase 4C (data security)
+4. Review Phase 4D (infrastructure)
+5. Finish with Phase 4E (dependencies)
+
+**Success Metrics**:
+- All inputs validated and sanitised
+- No authorisation bypasses
+- Encryption properly implemented
+- Security headers configured
+- Zero high-severity vulnerabilities
+- Security audit report created
+
+---
+
+## Phase 5: Performance Optimisation (Future)
+
+**Priority**: Low
+**Prerequisites**: Phases 1-4 complete
+
+### Potential Areas:
+- Cache optimisation (already has resilient Redis)
+- Query optimisation
+- Asset optimisation
+- CDN configuration tuning
+- Database indexing review
+
+**Estimated Effort**: TBD (requires profiling first)
+
+---
+
+## Appendix: Reference Implementation
+
+The **Trees Module** (\`src/Mod/Trees/\`) serves as an excellent reference for test implementation:
+- **Coverage**: 47% (9 tests for 19 files)
+- **Test Types**: Feature tests, API tests, queue tests, integration tests
+- **Pattern**: Co-located tests in \`Tests/Feature/\` directory
+- **Quality**: Well-structured, comprehensive assertions
+
+**Recommendation**: Use Trees module as template when implementing tests for Core packages.
+
+---
+
+## Summary Timeline
+
+| Phase | Effort | Duration | Priority |
+|-------|--------|----------|----------|
+| Phase 1 | 0 hrs | ✅ Complete | High |
+| Phase 2A | 210 hrs | 5-6 weeks | High |
+| Phase 2B | 100 hrs | 2-3 weeks | Medium |
+| Phase 2C | 62 hrs | 1-2 weeks | Medium |
+| Phase 2D | 74 hrs | 2 weeks | Low |
+| Phase 3 | 73 hrs | 2 weeks | Medium |
+| Phase 4 | 113 hrs | 3 weeks | High |
+| **Total** | **632 hrs** | **~16 weeks** | - |
+
+**Recommended Execution Order**:
+1. Phase 2A (Critical coverage) - 6 weeks
+2. Phase 4A-4B (Critical security) - 2 weeks
+3. Phase 3 (PHPStan improvements) - 2 weeks
+4. Phase 2B-2D (Complete coverage) - 5 weeks
+5. Phase 4C-4E (Complete security) - 1 week
+
+**Total Realistic Timeline**: ~16 weeks (4 months) with one full-time developer.