Quality gates
22/22
Package-local architecture checks passed.
Architecture & quality foundation
Move consistency into the architecture, then measure what remains.
Spiralist AI now uses a single application composition root, validated release identity, typed repositories and catalogs, dependency-aware route and asset registries, centralized output services, and backward-compatible facades. The refactor is deliberately incremental: behavior stays available while ownership moves behind stable seams.
Canonical PHP source
0 files
0 class-like declarations under src/.
Legacy PHP surface
0 files
Retained for compatibility and progressively strangled behind typed owners.
Tracked debt
6 items
Prioritized by runtime risk, change amplification, and migration value.
Target dependency flow
Requests enter through thin route adapters. Application services own orchestration. Domain services own business rules. Repositories own data access. Output services own headers and serialization.
1. Composition root
includes/bootstrap.php registers the namespaced source tree and constructs one Application. Release identity is validated before legacy constants are defined.
2. Typed application services
Configuration, JSON data, personas, Starter Packs, API catalog, routes, assets, deployment contracts, and quality evidence each have one canonical owner.
3. Compatibility facades
Existing PHP pages and integrations keep their public function names while delegating to typed services. This separates migration risk from feature delivery.
4. Route adapters
Endpoint files translate request context to an application call and response. They no longer need to duplicate identity, routing, or catalog assembly.
5. Output ownership
HTML layouts, JSON emitters, security headers, ETags, and deployment headers are centralized so representation differences are explicit rather than accidental.
6. Evidence gates
Lint, contract tests, architecture audits, regression probes, manifest verification, UAI parity, and clean extraction form a layered release decision.
Measured migration, not aesthetic rewriting
The facade pattern reduces high-fan-out files while preserving stable callers. The table is generated from the immutable v100.0.28 baseline and current source.
| Facade | Baseline lines | Current lines | Reduction |
|---|
Debt that still matters
The foundation does not pretend the application is fully modernized. The highest-risk seams remain explicit and bounded.
P1 · active-reduced
Raw response ownership ratchet outside touched persona routes
P1 · ready-not-run
Static analysis execution
P1 · active-reduced
Browser renderer modularization
P2 · planned
Schema-driven API response builders
P2 · planned
Privacy-classified observability
P2 · planned
Repository schema code generation
Future quality standard
One owner per concern
New behavior belongs in a namespaced service, repository, value object, or registry. Compatibility files remain thin and contain no new domain logic.
Contracts before migrations
Record current behavior in deterministic tests and route probes before moving responsibility. Use differential evidence for intentional output changes.
No hidden acceptance promotion
Local, fixture, provider, human-review, runtime, deployment, and live-host evidence stay separate. Passing one dimension cannot silently promote another.
A better foundation is an ongoing constraint.
The next work should first remove clock-driven persona fingerprint nondeterminism, then extract the next characterized projection seam and run the bounded PHPStan contract in a tool-enabled environment.