# Refactoring map — v100.0.30 onward

## Completed in this release

| Seam | State | Evidence |
|---|---|---|
| Deterministic seeded selection | Extracted | `src/Domain/Persona/SeededSelector.php` |
| Name/title normalization | Extracted | `src/Domain/Persona/NameNormalizer.php` |
| Immutable persona request/profile boundaries | Extracted | `PersonaDraft.php`, `PersonaProfile.php` |
| Identity-stack construction | Extracted behind facade | `PersonaIdentityBuilder.php` |
| Ordered identity invariants | Extracted behind facade | `PersonaInvariantValidator.php` |
| Characterization fixtures | 30/30 required comparisons | `docs/persona-domain-characterization-v100.0.30.json` |
| Raw response ownership | Ratchet established | `docs/raw-response-ownership-policy-v100.0.30.json` |
| PHPStan readiness | Configuration established; execution not claimed | `docs/static-analysis-readiness-v100.0.30.json` |

## Phase 1 — deterministic generation clock (next bounded action)

1. Inventory every call to `gmdate`, `date`, `microtime`, `random_bytes`, and non-seeded randomness on the persona path.
2. Introduce a generation context carrying seed, generation timestamp, request ID, and schema version.
3. Preserve legacy fingerprint behavior under an explicit compatibility version.
4. Add repeat-run tests proving identical input/context yields identical full bytes.
5. Promote full raw persona snapshots from observed evidence to required evidence.

**Exit criterion:** ten fixture families pass exact full-profile byte equality across separate processes and separate wall-clock times.

## Phase 2 — biography and causal identity

Extract biography, formative experiences, relationship topology, contradiction seeds, and causal identity into deterministic projectors. Replace hidden global catalog reads with typed dependency ports.

**Exit criterion:** characterization includes biography paragraphs, causal links, relationship IDs, and normalized language-family output without schema drift.

## Phase 3 — worldview and behavior projection

Move worldview, values, boundaries, voice, reasoning style, productive tension, examples, anti-examples, and response modes into cohesive projection services.

**Exit criterion:** each projection has independent fixtures, no HTTP/persistence dependencies, and explicit input/output value objects.

## Phase 4 — validation and schema boundary

Separate structural schema validation, semantic invariants, quality heuristics, realism audits, and population-level checks. Introduce repository-boundary JSON Schema validation rather than scattered ad hoc checks.

**Exit criterion:** validation findings carry stable codes, paths, severity, source, and deterministic ordering.

## Phase 5 — orchestration and provider boundary

Turn `includes/agent-persona-service.php` into a thin application service that coordinates request parsing, typed generation, provider enrichment, validation, and projection. Provider responses must remain untrusted input and must not silently replace canonical identity fields.

**Exit criterion:** the facade is below 500 lines, provider adapters are independently testable, and all generation paths share one application service.

## Phase 6 — HTTP response consolidation

Migrate raw header and process-termination owners to `RequestContext` and `ResponseEmitter` in bounded endpoint families. The current ratchet baseline is 141 header owners and 30 exit/die owners.

**Exit criterion:** owner counts decrease monotonically; no domain or repository class owns transport.

## Phase 7 — toolchain and observability

- Install and run PHPStan in CI; ratchet from level 6 toward 8 without broad suppressions.
- Add JavaScript module/type-check baselines.
- Consolidate current release tools around `tools/release_core/` while retaining historical release tools as immutable evidence.
- Add privacy-classified structured telemetry for generation latency, provider cost, validation findings, and fallback reason.

## Guardrails for every phase

- Immutable baseline and changed-file register.
- Characterization before refactor.
- Exact UAIX URL and three-part packaging contract preserved.
- Lowercase Windows-compatible archive names ending in `-wip.zip`.
- No deployment/live/provider/human/runtime acceptance without corresponding evidence.
- No change to research-source status or independent-verification claims.