settled-reach/docs/architecture/sprint-37-878-audit.md

Sprint 37 #878 — CharacterArchetype audit (D-032 obsolete claim)

Author: Tyre (architecture) Date: 2026-04-21 (audit); 2026-04-22 (lead override amendment) Ticket: #878 — Audit and purge dead smuggler/detective character enum (D-032 obsolete) Status: CLOSED — lead override 2026-04-21: strip stays. See override section below.

---

Lead override (2026-04-21)

Decision: STRIP the full CharacterArchetype trace from the server. The original audit (below) recommended Option A (no-op, docs-only) on the basis that grep identified five load-bearing consumers. The lead reframed the live-vs-filler determination:

"It is live because we have not scrapped the system loading it in the client. This is not live gameplay. Only the character creation elements and the insert screens are actual production code. The rest is uncleaned filler — per the cascade, we don't deal with character and NPC instructions." — Jeroen, 2026-04-21

Rationale — the cascade framing. Per CLAUDE.md, development follows a strict six-phase cascade. Current focus is Phase 1 (wiki content). Character model, NPC differentiation, verb-label relabeling, and character-keyed monologue pools all belong to Phase 6 (detail coloring). Code that executes at runtime is not automatically production — if the topic belongs to a later cascade phase, it is pre-cascade filler regardless of how deeply it is wired in.

The audit's identification of archetype_verb_label as "live feature code" was mechanically correct: the code runs, produces output, and is observed on the wire. But the feature itself is premature. Container verb differentiation (Smuggler Move/Stash vs Detective Scan/Flag) and archetype-keyed monologue pools are Phase 6 detail, not Phase 1–3 scaffolding. Uniform verb labels and a single monologue pool are the intended end state until a Phase 6 character system is designed — not a regression.

Audit correction. The audit's TL;DR conclusion ("v0.2 dropped reverses D-117 which reverses D-032-obsolete, therefore keep the enum") was the wrong frame. The supersession chain collapsed — yes — but the correct reading is that all three decisions sit below the current cascade floor, so the enum is cruft on cascade grounds independent of the D-117 revocation. The audit should have consulted the cascade phase before grep-counting consumers; that is the non-obvious precedent captured in memory (feedback_running_code_not_production.md).

Scope of the strip (Sprint 37, #878, merged via PR #137). Commit cae3d3ab — "refactor(simulation): strip archetype trace + HeritageRoot per cascade (#877, #878)" — is the authoritative file list; the summary below is the high-signal view:

• server/src/bridge/types.rs — CharacterArchetype enum + StartupMessage.character_archetype field removed. Protocol break rides the PROTOCOL_VERSION drop in #874 (D-192), co-shipped in the same PR.
• server/src/perception/observer/mod.rs — apply_phase2_verb_filter loses its archetype parameter; archetype_verb_label helper + the container-relabeling block deleted.
• server/src/simulation/monologue.rs — MonologueState.character field + Default value removed. Pool selection is now uniform.
• server/src/simulation/examine.rs — generate_examine_text collapses two archetype-specific branches into a single detective-style frame.
• server/src/test_world/mod.rs + server/src/main.rs — setup_gauntlet and setup_proof_room drop the archetype parameter; all internal callsites + the production main loop updated.
• server/tests/archetype_monologue.rs — deleted (regression guard for #587's archetype→monologue wiring; wiring itself deleted).
• server/tests/v01_integration_playthrough.rs — deleted (5 archetype-using integration tests; superseded by Gauntlet coverage).
• server/content/schemas/drama_module.schema.yaml — deleted.
• server/content/modules/tier1/smuggling_ring_v0_1.yaml — deleted.

Client follow-up: ticket #882 — "Strip archetype-driven client code (follow-up to #878 server)". The server strip leaves client-side code referencing the removed character_archetype wire field and archetype- keyed palette/monologue branches. Client cleanup preserves the character- creation UI and insert screens (production per the lead call) and strips lattice_profile branching, character.txt session I/O, and protocol decoding of the removed field. Blocked by this PR; cross-referenced in the server task description.

Decision record amendments (2026-04-22):

• decisions/content.md D-032 [SUPERSEDED] header rewritten to cite the cascade instead of the dropped D-117.
• decisions/content.md D-035 monologue character enum note updated (was [Obsolete post-D-117], now cites the cascade strip).
• decisions/perception.md D-057 marked [PARTIALLY SUPERSEDED] with the archetype verb relabeling portion crossed out; vertical-list + Phase 1/2 split preserved.

Regression guards for the new uniform behavior are being added under separate tasks (Hoshe, Sprint 37) — positive assertions that container verb labels and monologue pool selection are archetype-independent, to prevent silent reintroduction.

DECISION: STRIP.

The original audit body below is retained as a historical record of the pre-override analysis. Do not take its recommendation as current.

---

TL;DR (original audit, SUPERSEDED by lead override above)

The ticket's premise — that CharacterArchetype (Smuggler/Detective) is dead code per D-032's "[Obsolete post-D-117]" footnote — is stale. The footnote relied on D-117 (tycoon is the v0.2 bookmark), but CLAUDE.md now declares "v0.2 target is dropped. No scoping negotiations." That revocation is the most recent architectural directive, and it rolls back the premise that justified marking the enum obsolete.

Recommendation: do not delete CharacterArchetype. Instead, update the decision record to clear the stale obsolete footnote, close the ticket as "no-op — premise superseded," and (optionally) claim a small D-record documenting the reversal chain.

Audit

Grep was run against server/, tooling/, and tests/. CharacterArchetype has five load-bearing consumers plus content-schema users:

1. IPC protocol surface

• server/src/bridge/types.rs:51-54 — StartupMessage.character_archetype: CharacterArchetype. Field is serialized into the session handshake. Removing it is a protocol break.
• server/src/bridge/types.rs:500-518 — enum + as_monologue_key() helper + Default = Detective.
• Roundtrip tests at lines 1133, 1146, 1157, 1166, 1173, 1184 exercise the field.

2. Observer pipeline (D-057, #422) — real runtime behavior

• server/src/perception/observer/mod.rs:81,117,138,200 — archetype flows through apply_phase2_verb_filter.
• server/src/perception/observer/mod.rs:657-760 — archetype_verb_label() swaps container verb labels based on archetype (Smuggler sees Move/Stash, Detective sees Scan/Flag). This is live feature code, not scaffolding.

3. Monologue pool selection (D-032, #587, #595)

• server/src/simulation/monologue.rs:134-152 — MonologueState.character: String is initialized from CharacterArchetype.as_monologue_key() at session start. Pool partition is by string key, but the string is derived from the enum.

4. Gauntlet test-world plumbing

• server/src/test_world/mod.rs:98 — pub fn setup_gauntlet(app: &mut App, archetype: CharacterArchetype).
• 5 internal callsites (lines 702, 725, 742, 761, 778) plus the external archetype_monologue.rs integration suite.

5. Regression test suite

• server/tests/archetype_monologue.rs — entire file is a regression guard against #587 (archetype→monologue character wiring). Seven tests, four explicitly assert Smuggler vs Detective behavior. Deleting the enum requires deleting this guard, which is the thing that catches the bug it was built for.

6. Content schemas (authoring)

• server/content/schemas/drama_module.schema.yaml:231,233,234,280,558 — schema enumerates smuggler | detective | any for dialogue/monologue partitioning in drama modules.

Decision chain (why the ticket premise is stale)

D-027 (v0.1 vertical slice = smuggler + detective)
   └─ superseded by D-117 (2026-03-05: tycoon is the v0.2 bookmark)
         └─ superseded by "v0.2 target is dropped" (CLAUDE.md, current)

The obsolete footnote in D-035 line 83 and the [SUPERSEDED] header on D-032 both point at D-117 as the supersession. With v0.2 dropped, we are back to the v0.1 smuggler/detective frame as the implemented base until the 6-phase cascade reaches Phase 4 (Player control) — and even then, the cascade describes a 2-floor test map + character rendering, not a wholesale character-model replacement.

Proposed alternative scope for #878

Three options, cheapest first:

A. Close as no-op + documentation cleanup (recommended)

• Strip the [Obsolete post-D-117] footnote from decisions/content.md:83 (D-035 tag taxonomy).
• Remove the [SUPERSEDED] marker from decisions/content.md:47 (D-032 header) or add a "supersession reversed" note.
• Optionally claim a new D-record in decisions/scope.md documenting that the v0.2-dropped directive implicitly reverses D-117's character frame revocation.
• Zero code changes. Build stays green. 30 minutes.

B. Narrow the ticket to the authoring-side leftovers

• If there are authoring artifacts (half-written tycoon monologue partitioning, stale schema fields) that were added in anticipation of D-117 and never used, those can be purged. But a quick scan of drama_module.schema.yaml shows the schema is consistent with v0.1 usage.
• Requires a content team review — server-team scope alone cannot confirm what is live in authoring.

C. Rename without removing (if lead wants distance from v0.1 framing)

• Rename CharacterArchetype → PlayerCharacterRole (or similar) and its variants to preserve behavior while shedding the "smuggler/detective investigation framing" language. Higher risk, touches ~45 files, and doesn't actually change runtime. Not recommended unless the lead specifically wants the naming to match post-cascade vocabulary.

Recommendation (SUPERSEDED — see "Lead override" at top)

Go with Option A. The enum is architecturally sound, the ticket is a casualty of the v0.2→cascade pivot, and the cleanup is documentation- only.

Actual decision: strip (Option D, not enumerated above — full trace purge driven by cascade framing, not by the D-117/v0.2 supersession chain). The audit's grep-count-first methodology was the wrong starting heuristic; cascade phase comes first. See top of document.