# Code-quality debt register — v100.0.29-consistency-architecture-quality-foundation-wip

Immutable baseline: `v100.0.28-deployment-attestation-evidence-gate-wip`

This is an active migration register, not a claim that the whole legacy system has been rewritten. The release establishes boundaries that allow debt to be reduced without a flag-day conversion.

| ID | Priority | Area | Path | Next bounded action |
|---|---|---|---|---|
| `DEBT-PHP-001` | P0 | persona-generation | `includes/agent-persona-service.php` | Introduce immutable PersonaDraft and PersonaProfile value objects plus snapshot tests around the existing generator before moving one concern at a time. |
| `DEBT-PHP-002` | P0 | psychosis-domain | `includes/psychosis-character-service.php` | Create typed epistemic-layer records and migrate the evidence ledger first because it has the clearest invariant boundary. |
| `DEBT-PHP-003` | P0 | espionage-domain | `includes/espionage-persona-service.php` | Extract deterministic chronology normalization and test it across adult creator variants. |
| `DEBT-HTTP-001` | P1 | adult-api | `includes/adult-creator-api.php` | Migrate one read-only discovery/status endpoint as a reference controller before random/batch generation. |
| `DEBT-HTTP-002` | P1 | response-ownership | `includes/` | Add a policy check that rejects new raw header()/exit usage outside an allowlisted legacy boundary. |
| `DEBT-TOOLS-001` | P1 | release-engineering | `tools/` | Move package building, UAI synchronization, changed-file calculation, and validation onto release_core beginning with v100.0.29. |
| `DEBT-DATA-001` | P1 | schema-governance | `assets/data/ and includes/` | Add JSON Schema checks for Starter Packs, featured personas, personality types, and representation routes. |
| `DEBT-JS-001` | P1 | front-end-modules | `assets/js/` | Use the new AssetRegistry as the source of truth, then migrate one page family to ES modules without changing rendered behavior. |
| `DEBT-QUALITY-001` | P2 | static-analysis | `repository` | Start PHPStan on src/, config/, and tests/ at a strict level before touching legacy includes. |
| `DEBT-OBS-001` | P2 | observability | `HTTP and generation paths` | Define event names and privacy classifications before adding any sink. |

## Detailed records

### DEBT-PHP-001 — persona-generation

**Problem.** One procedural module owns catalog interpretation, random assembly, prompt/output composition, policy defaults, and presentation-shaped arrays.

**Risk.** High regression radius, difficult isolated tests, implicit contracts, and expensive future schema changes.

**Target.** Domain services split by identity, biography, worldview, memory, relationship, output projection, and invariant validation behind one facade.

**Next step.** Introduce immutable PersonaDraft and PersonaProfile value objects plus snapshot tests around the existing generator before moving one concern at a time.

Acceptance: legacy function signatures remain stable; golden fixture parity; no provider/runtime acceptance claim; each extracted service has direct tests.

### DEBT-PHP-002 — psychosis-domain

**Problem.** State construction, chronology, evidence-layer language, output projection, and support/safety boundaries share one procedural owner.

**Risk.** A content edit can change runtime shape or safety behavior outside the intended layer.

**Target.** Separate authoritative fictional facts, character reports, interpretation, support state, chronology, and renderer DTOs.

**Next step.** Create typed epistemic-layer records and migrate the evidence ledger first because it has the clearest invariant boundary.

Acceptance: authoritative facts never inferred from character intensity; existing JSON keys preserved; fixture comparison passes.

### DEBT-PHP-003 — espionage-domain

**Problem.** Career chronology, cover identity, tradecraft vocabulary, relationships, and output assembly are coupled.

**Risk.** Chronology and competency constraints can drift between UI, API, and exports.

**Target.** CareerTimeline, CoverIdentity, RelationshipGraph, AssignmentContext, and PersonaProjection services.

**Next step.** Extract deterministic chronology normalization and test it across adult creator variants.

Acceptance: chronology monotonicity; bounded expertise; no operational cyber guidance; API/export parity.

### DEBT-HTTP-001 — adult-api

**Problem.** Request parsing, consent enforcement, response headers, domain generation, error translation, and serialization remain interleaved.

**Risk.** Transport changes can alter domain behavior and vice versa.

**Target.** Thin controllers using Request DTOs, use-case services, typed Results, and ResponseEmitter.

**Next step.** Migrate one read-only discovery/status endpoint as a reference controller before random/batch generation.

Acceptance: RFC 9457 parity; HEAD/OPTIONS parity; same response digests; same error codes.

### DEBT-HTTP-002 — response-ownership

**Problem.** 144 PHP files still own raw header calls and 36 own exit/die behavior.

**Risk.** Inconsistent cache, security, content-negotiation, and testing behavior.

**Target.** ResponseEmitter and PageSecurity are the only new-code owners; legacy endpoints migrate incrementally.

**Next step.** Add a policy check that rejects new raw header()/exit usage outside an allowlisted legacy boundary.

Acceptance: no increase in raw-header owner count; new endpoints use typed emitter; CLI tests can invoke controllers without process termination.

### DEBT-TOOLS-001 — release-engineering

**Problem.** Historical release scripts repeat identity, hashing, Windows path, UAI, OpenAPI, and packaging logic.

**Risk.** Fixes land in one release script but not another; evidence semantics drift.

**Target.** Shared tools/release_core package with thin release wrappers and immutable historical scripts preserved as evidence.

**Next step.** Move package building, UAI synchronization, changed-file calculation, and validation onto release_core beginning with v100.0.29.

Acceptance: historical files unchanged; new wrappers under 150 lines where practical; one canonical Windows path validator; one canonical hash implementation.

### DEBT-DATA-001 — schema-governance

**Problem.** Some catalog invariants are encoded in consuming functions rather than machine-readable schemas and constructors.

**Risk.** Malformed content fails late or renders partially.

**Target.** Schema validation at repository boundaries plus typed catalog adapters.

**Next step.** Add JSON Schema checks for Starter Packs, featured personas, personality types, and representation routes.

Acceptance: fail-fast validation; path-specific errors; catalog counts retained; no silent defaults for required fields.

### DEBT-JS-001 — front-end-modules

**Problem.** The large JavaScript surface has dependency knowledge partly represented by page flags and historical bundles.

**Risk.** Duplicate execution, ordering bugs, and hidden cross-page coupling.

**Target.** Manifest-driven entry points with explicit dependencies and browser contract tests.

**Next step.** Use the new AssetRegistry as the source of truth, then migrate one page family to ES modules without changing rendered behavior.

Acceptance: no duplicate script URLs; stable load order; no new globals; keyboard/accessibility parity.

### DEBT-QUALITY-001 — static-analysis

**Problem.** Custom tests and lint exist, but there is no repository-wide PHPStan/Psalm baseline, JavaScript type check, or complexity budget.

**Risk.** Type and control-flow defects are discovered only through runtime tests.

**Target.** Incremental static-analysis baselines with ratcheting no-new-error rules.

**Next step.** Start PHPStan on src/, config/, and tests/ at a strict level before touching legacy includes.

Acceptance: zero new errors in typed tree; complexity budget for new code; CI-readable reports; legacy baseline explicit.

### DEBT-OBS-001 — observability

**Problem.** Trace/request identifiers exist, but structured application events and invariant failures are not emitted through one interface.

**Risk.** Production diagnosis would depend on ad hoc logs and HTTP responses.

**Target.** PSR-3-compatible structured logging boundary with redaction and no persona/private-text logging by default.

**Next step.** Define event names and privacy classifications before adding any sink.

Acceptance: no persona text in default logs; request/trace correlation; stable event schemas; configurable sinks.

Exact UAIX setup/update URL: `https://uaix.org/en-us/tools/ai-memory-package-wizard/?memory=docs-folder&file-handoff=1&loops=1`