# Cross-GDD Review Report

> **Date**: 2026-04-30
> **Reviewer**: Claude Code (consistency + design theory agents)
> **GDDs Reviewed**: 6 (node-system.md, tower-assembly.md, shop.md, event-system.md, progression.md, CombatNodeArchitecture.md)
> **Systems Covered**: Node System, Combat System, Tower Assembly, Shop System, Event System, Progression

---

## Consistency Issues

### Warnings

⚠️ **[C-W1] Tower Assembly Dependency Direction Is Inverted**
- **Files**: `tower-assembly.md` (Dependencies, line 207)
- Tower Assembly lists **Node System as an upstream (hard) dependency** — but the relationship is reversed. Node System **calls into** Tower Assembly during Assembly Phase. Tower Assembly is the **downstream** service, not the upstream.
- **Correct model**: Node System → (calls) → Tower Assembly. Tower Assembly is downstream.
- **Impact**: Logical error in dependency model. Does not block implementation.
- **Fix**: Swap direction — Tower Assembly should list Combat System as downstream consumer, and remove Node System as upstream dependency.

⚠️ **[C-W2] RunStats.goldEarned Loss-Path Contract Not Formally Sealed**
- **Files**: `node-system.md` (Edge Cases), `progression.md` (AC5b), `CombatNodeArchitecture.md` (§12.3.2)
- Design intent is **consistent**: zero gold on loss. `CombatNodeArchitecture.md §12.3.2` correctly states `GainedGold = 0` on loss, and `node-system.md` Edge Cases states "no partial rewards."
- However: `progression.md` AC5b says `totalGoldEarned += goldEarned` on loss — correct only if `goldEarned == 0`. The **RunStats schema** (`goldEarned >= 0`) allows non-zero values without a loss-specific constraint.
- No AC in `node-system.md` formally seals: `runStats.goldEarned == 0` on loss.
- **Impact**: Design intent is consistent; GDD contract is not airtight. A future implementer could introduce a non-zero gold-on-loss path without violating any AC.
- **Fix**: Add explicit AC in node-system.md: `"**GIVEN** the player loses Combat at any node, **WHEN** `RecordRunEnd` is called, **THEN** `runStats.goldEarned == 0`."`

⚠️ **[C-W3] Event System Does Not List Node System as Dependency Source for BossBonusGold**
- **Files**: `event-system.md` (Dependencies, line 178), `node-system.md` (line 122, line 223)
- `BossBonusGold = 200` is declared in `node-system.md` but `event-system.md` does not list `node-system.md` as a dependency source for this value.
- Not a functional issue — `BossBonusGold` is not referenced in Event System mechanics.
- **Fix**: Add `BossBonusGold` sourcing note in `event-system.md` Dependencies if the value is ever used in event design.

---

## Game Design Issues

### Warnings

⚠️ **[G-W1] Tag System GDD Does Not Exist — Tag Stacking Is Unconstrained (HIGHEST PRIORITY)**
- **Files**: `tower-assembly.md` (TagAggregation), `design/gdd/tag-system.md` (**DOES NOT EXIST**)
- `TowerAssembly.AggregateTowerTags()` produces `TotalStack = occurrence count (1–3)` per tag. The GDD explicitly states: "the effective power multiplier semantics of this count... are defined in the Tag System GDD."
- **The Tag System GDD does not exist in the codebase.**
- **Structural dominant strategy**: If `Stack=3` is strictly better than `Stack=2` or `Stack=1` for any tag, the optimal tower always uses 3 copies of the best available tag. The "optimization puzzle" has a single solution.
- **Fix**: Write `design/gdd/tag-system.md` before implementing Tower Assembly. Define stacking semantics (linear? diminishing returns? multiplicative ceiling?).

⚠️ **[G-W2] Event Rewards Share Rarity Budget with Shop — No Distinct Tier**
- **Files**: `event-system.md` (ER4: AddRandomComps), `shop.md` (SR1), `progression.md` (pool unlock chain)
- `AddRandomComps` calls `InventoryGenerationComponent.BuildEventRewardComponents()` — the same generation pipeline as shop.
- Events cannot reward a rarity the player hasn't unlocked in Progression.
- Event System pillar ("narrative surprise and meaningful stakes") is undermined when the reward tier is identical to shop.
- **Fix**: Consider a separate event rarity budget (e.g., events drop at most Blue even if player has Red unlocked), or a distinct reward category.

⚠️ **[G-W3] Sell Price at ~50% Actively Discourages Experimentation**
- **Files**: `shop.md` (SR6, Formula 2), `tower-assembly.md` (Fantasy line 20)
- Tower Assembly fantasy: "free reconfiguration," "optimization mastery under constraint"
- Shop sell formula: `Round((minPrice + maxPrice) / 2.0f)` — ~50% of max buy price
- Player who buys a White component for 100, tries it, sells it back gets 50. Half their experiment cost is destroyed.
- Free disassemble partially offsets this — but if inventory is full and player wants to try a new component, they must sell something.
- **Fix**: Make sell ratio a tunable knob (recommend 60–70%) or add a component enhancement sink that uses excess components.

⚠️ **[G-W4] Assembly Phase Has 5 Simultaneous Panels — Cognitive Load Risk**
- **Files**: `tower-assembly.md` (Assembly Phase Screen, UI Requirements)
- Panels: Inventory Grid + 3 Assembly Slots + Assembled Towers + Combat Roster + Next Node Preview
- The GDD's own design note: "Ready button is enabled and clicking it proceeds... without modification." — the designed workaround is to click Ready when nothing needs doing.
- **Structural problem**: Players who understand the game will click Ready almost every time after the first few runs. The elaborate UI becomes noise.
- **Fix**: Merge Assembled Towers panel with Combat Roster (single "Your Towers" panel with roster checkboxes), or introduce a "Quick Assemble" mode that hides unused panels.

⚠️ **[G-W5] "Build Toward the Boss" Fantasy Conflicts with Boss Scaling Formula**
- **Files**: `tower-assembly.md` (Fantasy line 22), `node-system.md` (Boss HP formula)
- Tower Assembly fantasy: "each assembly decision accumulates toward the final confrontation; the boss fight is where build quality is ultimately tested."
- `BossEffectiveHp = BaseHp × 2^completedLoopCount` — Boss HP scales with rounds survived, not player power.
- Better build → faster kill → fewer loops survived → lower effective HP. The boss IS a test of kill speed, not raw survivability.
- The stated fantasy implies build quality = being powerful enough to win, not kill-speed pressure.
- **Fix**: Revise Tower Assembly Fantasy line 22 to reflect kill-speed pressure, not "build quality tested."

⚠️ **[G-W6] Difficulty Spike at Normal→Hard Before Component Pool Catches Up**
- **Files**: `progression.md` (pool unlock chain), `node-system.md` (Plain theme node sequence)
- Green pool unlocks on first Normal win. Hard difficulty unlocks after defeating Boss on Normal.
- Player enters Hard with only Green components. The first 4 Hard combat nodes are fought with inadequate tools.
- **Fix**: Consider starting Green pool available before first win, or give Hard difficulty a more generous starting loadout.

⚠️ **[G-W7] Gold Cap (9999) Is Effectively Unreachable in Normal Play**
- **Files**: `shop.md` (MaxPlayerGold), `node-system.md` (per-run gold ~1100)
- ~1100 gold per full winning run. 9999 cap. ~9 wins to cap, assuming minimal spending.
- With free disassemble and no repair mechanism, spending pressure is low. A skilled player accumulates excess gold with no outlet.
- **Fix**: Consider a prestige mechanic that converts excess gold into permanent upgrades, or significantly lower `MaxPlayerGold`.

---

## Cross-System Scenario Issues

**Scenarios walked:** 1 (Full Run End chain)

### Full Winning Run — RunEnd Chain

1. Node System: Boss defeated → fires `NodeCompleteEventArgs(CombatWon=true)`
2. Node System → `Progression.RecordRunEnd(runStats)` with `{goldEarned, nodesCompleted=10, bossDefeated=true, coinsEarned}`
3. Progression: `LifetimeStats` updated → unlock evaluation → `UnlockedEventArgs` with `UnlockResult[]`
4. UI / Run End Screen: Toast popup for new unlocks

**Issues found:**

⚠️ **G-W7 (display gap)**: Run End Victory screen cannot display "Gold earned this run" without a data path. `UnlockedEventArgs` carries no `goldEarnedThisRun` field. This was G2 in the 2026-04-29 review — flagged as blocking — but is a **display gap, not a crash**. The screen shows 0 gold implicitly. Recommend adding `goldEarnedThisRun` to `UnlockedEventArgs` for UX completeness.

---

## GDDs Flagged for Revision

| GDD | Reason | Type | Priority |
|-----|--------|------|----------|
| `tower-assembly.md` | C-W1: dependency direction inverted; G-W1: Tag System GDD missing; G-W5: boss fantasy conflict | Consistency + Design Theory | **High** |
| `event-system.md` | G-W2: event rarity budget not distinct from shop | Design Theory | Medium |
| `shop.md` | G-W3: sell ratio tunable knob; G-W7: gold cap tuning | Design Theory | Medium |
| `node-system.md` | C-W2: loss gold AC gap; G-W6: difficulty spike | Consistency + Design Theory | Medium |

---

## Verdict: **CONCERNS**

No blocking issues — no system is mechanically broken. All 6 systems are implementable and internally coherent.

Warnings present — 7 warnings and 1 scenario info item. These should be resolved before or during implementation but do not prevent architecture work from beginning.

**Most urgent**: G-W1 (Tag System GDD missing) — without it, `TagAggregation` output is undefined and Tower Assembly cannot be fully implemented.

---

## Recommended Actions

1. **G-W1 (HIGHEST)**: Write `design/gdd/tag-system.md` — define tag stacking semantics before implementing Tower Assembly
2. **C-W1**: Fix Tower Assembly dependency direction — swap Node System from upstream to downstream
3. **C-W2**: Add formal AC in node-system.md sealing `runStats.goldEarned == 0` on loss
4. **G-W5**: Revise Tower Assembly Fantasy line 22 — "build toward the boss" should reflect kill-speed pressure
5. **G-W2**: Event System — consider separate rarity budget for event rewards
6. **G-W3**: Shop — make sell ratio a tunable knob
7. **G-W6**: Progression — address Normal→Hard difficulty spike before component pool upgrade
8. **G-W7**: Shop — consider gold cap tuning or prestige mechanic
9. **C-W3**: Event System — add BossBonusGold sourcing reference to Node System