Design ↔ Code Alignment
Status: LIVING AUDIT — started 2026-07-27 Purpose: Make "what is in design is in code" true for existing design, without inventing new systems (class skill trees stay FUTURE).
Last updated: October 8, 2026
Darkness Falls — Design ↔ Code Alignment
Status: LIVING AUDIT — started 2026-07-27
Purpose: Make "what is in design is in code" true for existing design, without inventing new systems (class skill trees stay FUTURE).
Parents: index.md, north-star.md, act-1-class-signatures.md, class-playstyle-and-subclasses.md, endgame.md
0. How to use this doc
- HAVE = player-reachable behavior in code (with proof where claimed).
- PARTIAL = service/handler/content exists but a designed loop step is missing.
- SHOULD / gap = design specifies it; code does not (or claim table still says gap after code landed).
- FUTURE = design direction only; do not implement until owner reopens.
- Work top-down by wave. Finish a wave's ship gate before expanding scope.
Proof language follows design-proof-contract.md:gap → spec → building → local_proved → prod_proved → stable.
1. Explicit FUTURE (not in scope for alignment)
| Item | Design home | Rule |
|---|---|---|
| T3 class skill trees | class-playstyle-and-subclasses.md § 5 | NOT IMPLEMENTED. No code, no NLU, no UI. Direction only. Agents must not build trees. |
| Full Act II–V campaign map | north-star.md | Later phases; Act I first |
| Current Season competitive launch | seasons.md | Parity gate not met; do not fake live season |
| Class-specific SFX (Soundstripe) | combat.md Planned | Blocked on keys / asset pipeline |
| PvP arenas, guild quests | index Phase 4 backlog | Longer-term |
Star Map is NOT "class skill trees." Star Map is live (shared four paths). T3 would be a separate class-scoped layer on top of the automatic signature profile.
2. Inventory — systems that design already claims
Status is grounded as of 2026-07-27 (working tree + design docs). Re-verify before coding a row.
2.1 Act I + class playstyle (north-star Phase 1)
| Area | Design says | Code reality | Status | Proof / notes |
|---|---|---|---|---|
| Auto-attack / ignore-path | Preserve | Live | HAVE | scenarios 845, 2126 |
| Objective stages + return briefing | 3 stages + law 1 | Live | HAVE local_proved |
2938–2941; deploy → prod_proved |
| Pilot signatures Guard/Strike/Blast/Mend | Automatic playstyle | Live auto | HAVE local_proved |
2946–2951, 2779 |
| Twin signatures Rage/Mark/Drain/Smite | Distinct auto twins | Live auto | HAVE local_proved |
2952–2955; claim row was stale gap — fix in act-1 table |
| Teach tip ≤2, no cast chip | Soft teach | Live | HAVE | 2949 |
| Cast soft-redirect | No cast bar | Live | HAVE | |
| T1/T2 signature profile mutations | Promotion + path mutate cadence | Live resolver | HAVE (JUnit) | ; optional claim scenarios later |
| Stationary stance gear hook | MEGA_* while hold | Mild +15% armor/evasion on hold | PARTIAL | Full per-MEGA stationary gate optional |
| Watch NPC memory (B5) | One recurring Watch line | Live first-meet + return (Rourke / seeds) | HAVE local_proved |
scenario 2960,2962 |
| Threat teaser (B6) | Named threat in objective | Live Thinning Shadow objective + one-time teaser | HAVE local_proved |
scenario 2963,2964 |
| L10 Act I coda | Gold + one-time coda | Live coda on L10 milestone | HAVE local_proved |
scenario 2961 |
| Class skill trees T3 | Optional late picks | None | FUTURE | § 1 |
2.2 Core combat / exploration (already largely aligned)
| Area | Status | Residual |
|---|---|---|
| After-action combat, hit/damage, positioning | HAVE | Keep scenario discipline |
| Skill gems + Star Map attack cadences | HAVE | Round counter zone-scoped (2026-07-14) |
| Zone HP/damage/loot scaling | HAVE | — |
| Zone gameplay modifiers (Cursed heal cut, Bloodlust lifesteal, Nightmare sight, Void teleport, Endless respawn) | HAVE local_proved |
Wave 4: DarknessFallsZoneModifierEffects + scenario 3017 + JUnit |
| Status effects P1–P4 + rollup | HAVE (status-effects.md 2026-06-19) | combat.md still has an older "getEffectiveStat never consulted" note — doc drift; treat status-effects.md as authority |
| Party teleport / downed / resurrect | HAVE | Resurrect lands in a party's shared zone instance |
| Shared party combat, shared spoils, party-size bonus | HAVE building |
party-combat.md; JUnit in , , |
2.3 Endgame ([endgame.md](endgame.md))
| Area | Status | Missing for "design = code" |
|---|---|---|
| Enter rift + generate VOID_RIFT + scale enemies + stamp modifiers | HAVE | Per-zone variety (always VOID_RIFT); tier-scaled boss pool |
| Rift NLU (enter/status/leaderboard) | HAVE | — |
| Rift tier advance on clear | HAVE local_proved |
scenario 2965; combat zone-wide clear hook |
| Rift death → tier reset | HAVE local_proved |
scenario 2966; death paths call recordDeath |
| Rift exclusive drops / essences / sets | PARTIAL local_proved |
Essences + loot HAVE; Tier 10+ fragments + forge 2pc/4pc HAVE (Wave 14) |
| Weekly rift reset job | HAVE local_proved | scenario 2968; lazy + evt_weekly_rift_reset |
| Siege status/join + staging zone | HAVE | Join → SIEGE_OF_ETERNITY; damage reports to global HP |
| Siege complete + Siege Marks + vendor catalog | HAVE local_proved |
Wave 5–6 catalog; Wave 12 72h cadence + multi-front join; scenarios 3018–3019, 3039–3041 |
| Mastery service (XP, allocate, branches) | HAVE local_proved |
Handlers 362-364 + allocate one-shots; scenarios 2995–2996 |
| Mastery perk effects in stats/loot/XP | HAVE local_proved |
; scenario 2997 (CURRENT_SEASON suppressed) |
| Hideout Mastery perks (stash/potion/portal/beacon/forge) | HAVE local_proved |
Ranks 1–5 scenarios 3042–3053 |
| Power level formula includes Mastery/Rift | HAVE local_proved |
Five-arg formula; scenario 2998 |
2.4 Economy / monetization / social
| Area | Status | Notes |
|---|---|---|
| Blood Emerald shop + consumables | HAVE | Hideout-accessible; ISP repairs 2026-07 |
| Extra Stash Tabs / Resurrection Charm / XP Elixir as premium paths | Check isp-review | Some listed DESIGNED not IMPLEMENTED historically — re-verify vs shop catalog before work |
| Cosmetic shop | PARTIAL local_proved |
BE shop cosmetics: Golden Glow, Shadow Trail, titles Wealthy/Feared (Wave 13) |
| Premium equipment | PARTIAL local_proved |
Six Standard-only BE SKUs + gold/XP passives; CURRENT_SEASON refuse (Wave 14) |
| Abyssal set forge | PARTIAL local_proved |
Fragments, forge, 2pc/4pc bonuses (Wave 14) |
| Siege 72h cadence EVENT | HAVE local_proved |
evt_world_siege_cadence hourly check (Wave 14) |
| Seasons parity scaffolding | PARTIAL | season_config + SeasonParityGate + season status; competitive launch blocked |
| Seasons live lifecycle | PARTIAL | Storage + season status NLU SHIPPED; competitive launch still gated (parity suite) |
| Social discoverability (help/NLU) | HAVE local_proved |
help endgame + social siege discoverability (Wave 12) |
| Quest content depth | PARTIAL | Plumbing live; more quest data needed |
3. Close-the-gap plan (ordered waves)
Principle: wire what design already promises, prove it, ship it. Do not open FUTURE rows.
Wave 0 — Honesty (docs + claims) — THIS SESSION
| Task | Done when |
|---|---|
| Lock T3 skill trees as FUTURE with hard caveats | class-playstyle § 5 |
| Publish this alignment inventory | this file |
Fix claim table drift: twins local_proved + scenarios 2952–2955 |
act-1 claim table |
| Point index / combat at alignment + playstyle | cross-links |
USER /code-checkin then /deploy for playstyle java |
prod_proved for Phase B+C combat claims |
Wave 1 — Finish Act I product (designed spine, still open)
Highest player-facing value after ship of auto-signatures.
| Priority | Work | Design ref | Proof |
|---|---|---|---|
| 1 | Deploy playstyle signatures + twins (USER) | act-1, class-playstyle | claim rows → prod_proved |
| 2 | Phase D: Watch-Sergeant memory line (B5) | act-1 B5, D3 | scenario df.act1.npc.watch-seed |
| 3 | Phase D: Thinning Shadow threat teaser + objective stage | act-1 B6 | df.act1.threat.teaser |
| 4 | Phase D: L10 Act I coda once (no spam) | act-1 B7 | df.act1.close.coda (+ keep 2279 gold) |
| 5 | Optional: promotion-path claim scenarios (T1/T2 cadence) | class-playstyle | claim rows + hermetic setups |
| 6 | Optional: MEGA_* true stationary gating | class-playstyle § 4 | JUnit + one scenario |
Exit: Act I claim table (except explicit wont_fix) ≥ local_proved; combat rows ≥ prod_proved after deploy.
Wave 2 — Make Abyssal Rifts a closed loop
Design already says rifts are the core endgame grind; enter works, climb does not.
| Priority | Work | Why |
|---|---|---|
| 1 | Call advanceTier when rift boss / clear condition met |
Without this, "tiers" are flavor |
| 2 | Call recordDeath on death inside rift |
Designed weekly climb risk |
| 3 | Wire rift loot bonuses already stamped at enter into drop rarity | Partial reward truth |
| 4 | Rift-exclusive essences (minimal currency) | Enables later craft without full set system |
| 5 | Weekly reset event (tier → 1, keep highest_cleared history) | Design Monday reset |
| 6 | Boss pool + non–VOID_RIFT templates (content) | Variety after loop works |
Exit: Solo player can enter → clear → tier++ → die → tier reset; hermetic scenarios for enter + clear advance + death reset.
Wave 3 — Mastery becomes real power (Standard path)
| Priority | Work |
|---|---|
| 1 | Add process_action_handlers + one-shots for view / branch / allocate mastery |
| 2 | Consume perk bonuses in stat rebuild + gold/magic-find/XP paths |
| 3 | Award mastery XP from rift clear (and later siege) per endgame table |
| 4 | Hideout rank-3 Rift Portal SHIPPED Wave 9 (open portal gated; enter rift still forces a tear) |
Respect seasons fairness: Current Season mechanical suppression if seasons.md contract applies.
Wave 4 — Zone modifier gameplay effects
Designed table exists; only Death's Door + scaling live.
Order by integration cost (suggested):
- Nightmare sight −2 (single sight read site)
- Bloodlust enemy heal % of damage dealt (enemy hit path)
- Cursed healing ×0.8 (find or introduce single heal funnel)
- Void-Touched 5% teleport on move
- Endless respawn (hardest — needs scheduler/tick)
Each modifier gets a claim + hermetic or JUnit proof.
Wave 5 — Sieges (social endgame)
Only after Waves 2–3 give solo endgame a heartbeat.
- Scheduler creates siege events on cadence
- Fragment damage → global HP
- Completion mints Siege Marks + ranks
- Vendor spend (minimal catalog)
Wave 6 — Secondary content / polish
Quest data packs, social help topics, cosmetic shop, seasons live launch (only after parity suite), remaining status-effects producer breadth.
Never as alignment work
- Class skill trees (T3)
- Shared combat instances
- Full campaign rewrite
4. Immediate next actions (recommended)
- USER:
/code-checkinthen/deployfor current playstyle + Act I java so local_proved becomes prod_proved. - Next coding session: Wave 1 Phase D (Watch + threat + coda) — pure design already locked (D3).
- After Act I claims green: Wave 2 rift clear/death hooks (smallest endgame loop that design already documents as playable).
- Re-run this inventory after each wave; flip rows HAVE only with proof ids.
5. Claim / doc drift checklist
When code lands ahead of docs (or vice versa):
| Drift | Fix |
|---|---|
Code live, claim still gap |
Update claim row + proof ids same session |
| Design says COMPLETE, code PARTIAL | Correct status line (endgame.md pattern) |
| combat.md vs status-effects.md conflict | Prefer status-effects.md for effects; strip stale combat note |
| Agent invents T3 trees | Reject; point at § 1 FUTURE |
Refs
- act-1-class-signatures.md — Capability Contracts + claim table (Act I restart surface)
- class-playstyle-and-subclasses.md — auto combat + T0–T3
- endgame.md — rifts / sieges / mastery
- combat.md — zone modifiers
- status-effects.md — effect pillars
- north-star.md — journey order
- design-proof-contract.md — HAVE/SHOULD proof lifecycle
- game-balance.md — Phase 0 fight-level metrics + scenario 2935
6. Wave 2 plan — Abyssal Rifts closed loop (next implementation wave)
Goal: A solo player can enter → clear → tier++ → die → tier reset with designed rewards starting to land. Enter already works. Climb and death risk do not.
2.0 Invariants (do not break)
- Private zone instances stay private (no shared combat).
- Death still returns to hideout with normal XP penalty outside rifts; inside rifts also reset tier via
recordDeath. - Voice-first copy; hermetic scenarios for enter/clear/death.
- Mastery / sieges stay Wave 3–5 — do not block Wave 2 on them.
2.1 Work packages (ordered)
| ID | Work | Code touchpoints | Proof |
|---|---|---|---|
| W2.1 | Clear → advance tier | Hook combat victory / zone-clear when zone is a rift instance (createRiftZone / endgame flag). Call .advanceTier(characterRef, currentTier+1) once per clear. Persist highest_cleared. |
Scenario: enter tier 1 → force clear (seed or admin) → rift status shows tier 2 |
| W2.2 | Death → reset tier to 1 | On player death path, if current zone is rift: . Keep loot earned. | Scenario: in rift, die → status tier 1 |
| W2.3 | Clear condition definition | Design currently: "defeat the boss at the end." Implement a single clear signal: boss enemy dead OR all enemies dead in rift zone (pick one; recommend boss dead if a boss is stamped, else all enemies). Document choice in endgame.md. | JUnit pure helper + scenario |
| W2.4 | Rift loot bonus path | Enter already stamps modifiers/scaling. Wire loot rarity/gold bonus from tier table into drop pipeline when zone is rift (minimal: reuse existing endgame loot percent). | Scenario or JUnit on drop level/rarity multiplier |
| W2.5 | Rift essence currency (minimal) | Add a small essence grant on clear (integer on character or seasonal currency). No full craft set yet — just earn + status readout. | Scenario: clear grants essence; status mentions it |
| W2.6 | Weekly reset job | MySQL event or dashboard job: Monday boundary, archive week row / reset currentTier to 1, keep highest_cleared history. | Job dry-run + service unit test |
| W2.7 | Content polish (after loop green) | Non-VOID_RIFT templates, boss pool by tier — content, not engine blockers. | Content scenarios optional |
2.2 Suggested first coding session (W2.1–W2.3 only)
- Find where combat victory runs for DF ( / death utilities).
- Detect "this zone is a rift instance" (flag on zone or zoneRef pattern from
createRiftZone). - On boss defeat (or clear):
advanceTier. - On death in rift:
recordDeath. - Scenario seeds: enter rift if hermetic (or setRiftTier + mock zone flag if enter is non-hermetic).
- Update endgame.md Pending table rows to SHIPPED as each lands.
- Flip design-code-alignment § 2.3 rows.
2.3 Explicitly out of Wave 2
- World Siege scheduler / Siege Marks (Wave 5)
- Mastery NLU + perk consumers (Wave 3)
- Zone modifier gameplay effects beyond what rifts already stamp for scaling (Wave 4)
- Class skill trees T3 (FUTURE forever until design pass)
2.4 Exit criteria for Wave 2
- W2.1–W2.3
local_proved(clear advances tier; death resets; clear condition documented) - W2.4 loot path at least partial with proof
- endgame.md status line updated (not still "tier does not climb")
- USER
/code-checkin+/deployfor java - Optional W2.5–W2.6 same session or follow-up
Wave 2 progress (2026-07-27)
- W2.1–W2.3 local_proved (clear advances tier; death resets; clear = zone-wide no living enemies)
- Essences on clear (minimal W2.5)
- W2.4 loot path (tier rarity mult + gold bonus) — scenarios 2967 + JUnit
- W2.6 weekly Monday rollover — scenario 2968 + fixed MySQL event
- USER /code-checkin + /deploy for java
Wave 3 progress (2026-07-28)
- W3.1 NLU — handlers 362-364 already present; ALLOCATE one-shots on prod (+ local mirror); scenarios 2995 allocate, 2996 view
- W3.2 Perk consumers — damage / gold / magic-find / XP via ; scenario 2997
- W3.3 Power level — MasteryLevel + HighestRift in ; scenario 2998
- orphan_check + comment_lint clean (no new orphans; effectiveLootQualityMultiplier already absent)
- USER /code-checkin + /deploy for java (God-terminal-8 / separate session owns commit)
Wave 4–5 progress (2026-07-28)
- W4 Nightmare/Bloodlust/Cursed/Void-Touched/Endless on real paths — scenario 3017, JUnit
- W5 siege complete → marks + tier — scenario 3018
- W5 spend siege marks — scenario 3019 + NLU
DARKNESS_FALLS_SPEND_SIEGE_MARKS - orphan_check + comment_lint clean
- USER /code-checkin + /deploy for java
Wave 2–5 local loop proof (2026-07-28/29)
Closed-loop local proof for rifts → mastery → zone modifiers → siege marks. Backend local 1.466.0 band.
| Layer | Result |
|---|---|
| Wave 2 Rifts | PASS — scenarios 2965–2968 green×2; live NLU enter/status/leaderboard |
| Wave 3 Mastery | PASS — scenarios 2995–2998 green×2; allocate with seed points |
| Wave 4 Modifiers | PASS — JUnit + scenario 3017 green×2 |
| Wave 5 Siege loop | PASS — scenarios 3018–3019 green×2; complete → marks → spend |
| Voice-first | FIXED — rift status/leaderboard no parentheses (VOICE_RULE) |
| Leaderboard identity | FIXED — ranks speak character names via mapper join |
Hermetic scenario ids (green×2): 2965, 2966, 2967, 2968, 2995, 2996, 2997, 2998, 3017, 3018, 3019.
Re-run checklist: start local backend → POST /api/admin/scenario-tests/run/id/{id} ×2 each → JUnit + → optional play_sequence with setZone=HIDEOUT_ZONE, level≥50 (not bare HIDEOUT).
Residuals (not blocking loop claim): promotion-class interrupt noise at L50+; local leaderboard TestCharacter pollution; REPETITIVE_ENUMERATION on top-10 lists; ambient siege often inactive (use hermetic seeds); CURRENT_SEASON suppresses mechanical mastery by design.
Ship: USER /code-checkin then /deploy for java → advance local_proved rows to prod_proved.
Expansion Ledgers (catalog growth)
Seed systems (forge, premium SKUs, siege vendor, etc.) register Expansion Ledgers in endgame.md and monetization.md. Pattern: catalog-expansion-ledger.md.
- Loop local_proved ≠ catalog mature.
- Monthly audit: report_coverage catalog-expansion + pending checklist phases starting with Expansion Ledger.
- Query: infrastructure({ design_checklist: true, pending_only: true }).