# NEO-75 — Implementation plan

## Story reference

| Field | Value |
|--------|--------|
| **Key** | NEO-75 |
| **Title** | E3: Playable gather→refine→make loop in client (E3S5-04) |
| **Linear** | https://linear.app/neon-sprawl/issue/NEO-75/e3-playable-gatherrefinemake-loop-in-client-e3s5-04 |
| **Module** | Epic 3 **Slice 5 capstone** — [E3.M1](../decomposition/modules/E3_M1_ResourceNodeAndGatherLoop.md) + [E3.M2](../decomposition/modules/E3_M2_RefinementAndRecipeExecution.md) + [E3.M3](../decomposition/modules/E3_M3_ItemizationAndInventorySchema.md) · backlog **E3S5-04** |
| **Branch** | `NEO-75-e3-playable-gather-refine-make-loop` |
| **Server deps** | NEO-63 gather interact, NEO-70 craft POST, NEO-55 inventory GET, NEO-37 skill-progression GET (**Done** on `main`) |
| **Client deps** | [NEO-72](https://linear.app/neon-sprawl/issue/NEO-72) inventory HUD (**Done**); [NEO-73](https://linear.app/neon-sprawl/issue/NEO-73) gather feedback (**Done**); [NEO-74](https://linear.app/neon-sprawl/issue/NEO-74) craft UI (**Done**) |
| **Pattern** | Capstone integration — reuse NEO-72–74 wiring; docs + manual QA primary; HUD collapse per kickoff |

## Kickoff clarifications

| Topic | Question | Agent recommendation | Answer |
|--------|----------|----------------------|--------|
| **Implementation scope** | Docs-only vs code changes? | **Docs + manual QA first**; add code only if QA fails — loop already wired in NEO-72–74. | **User:** docs + manual QA first; code only if QA fails. |
| **HUD collapse** | Build toggle now or defer? | **Defer** — optional per backlog; left scroll usable for capstone. | **User:** **implement** collapsible HUD sections in this story. |
| **Capstone session start** | Fresh player without Bruno? | **Restart server** (in-memory dev store resets) before Godot **F5** — no curl/Bruno seeding. | **Adopted** (Linear AC + kickoff default). |
| **Progression gate smoke** | Filter recipes by skill level? | **Visible XP only** — salvage/refine rows refresh after gather/craft; no recipe gating UI (explicit NEO-74 out-of-scope). | **Adopted** (decomposition default). |

## Goal, scope, and out-of-scope

**Goal:** Prove Epic 3 prototype acceptance **in Godot**: gather **`scrap_metal_bulk`** → **`refine_scrap_standard`** → **`make_field_stim_mk0`** without Bruno; satisfies vision **crafting loop** + **progression gate** smoke test.

**In scope (from Linear + [E3S5-04](E3S5-client-prototype-backlog.md#e3s5-04--playable-gatherrefinemake-loop-in-client-capstone)):**

- **`docs/manual-qa/NEO-75.md`**: numbered **single-session** capstone script — fresh dev player, four-node gather route, two refines + one make, final **`field_stim_mk0`** assertion; **no Bruno/curl** steps.
- **`client/README.md`**: **End-to-end economy loop** section — integration checklist (boot → **R** gather → craft panel → inventory/skill refresh chain); input keys; material math (11 scrap minimum).
- **Collapsible economy HUD**: toggle to hide/show **`InventoryLabel`**, **`SkillProgressionLabel`**, **`CraftRecipePanel`** block so prototype scene stays playable on smaller viewports.
- **Module alignment** (on story completion): update [`documentation_and_implementation_alignment.md`](../decomposition/modules/documentation_and_implementation_alignment.md) E3.M1/M2/M3 rows + Epic 3 Slice 5 “complete” note in [`epic_03_crafting_economy.md`](../decomposition/epics/epic_03_crafting_economy.md).
- **Integration fixes only if capstone QA fails** on current `main` wiring (unexpected deny, refresh gap, etc.).

**Out of scope (from Linear):**

- Quest UI (E7); combat consumable **use** of **`field_stim_mk0`** (E5 follow-up); art pass.
- New HTTP routes or economy clients; recipe quantity spinner; station placement.
- Bruno-only verification as prototype-complete proof.

## Acceptance criteria checklist

- [x] Manual QA checklist completable by a human in **one session** with server + client running (**`docs/manual-qa/NEO-75.md`**).
- [x] **`field_stim_mk0`** quantity ≥ **1** in inventory at end of script.
- [x] Epic 3 Slice 3 AC re-read satisfied in Godot: player (not Bruno) completes **gather → refine → usable item**; **salvage** / **refine** XP visible after actions.
- [x] Economy HUD collapse toggle documented and functional.

## Implementation reconciliation (shipped)

- **HUD:** `prototype_economy_hud_section.gd` — **`Economy HUD`** checkbox collapses inventory/skills/recipe panel under **`UICanvas/EconomyHudSection/Body/`**.
- **Docs:** [`NEO-75` manual QA](../manual-qa/NEO-75.md) capstone script (zero Bruno); `client/README.md` end-to-end economy loop section.
- **Tests:** `prototype_economy_hud_section_test.gd` — toggle visibility.
- **Alignment:** E3.M1/M2/M3 rows + E3S5-04 backlog AC updated for Slice 5 client complete.
- **Integration:** No `main.gd` logic changes beyond `@onready` path updates for reparented HUD nodes.

## Technical approach

### 1. Capstone manual QA script (`docs/manual-qa/NEO-75.md`)

**Preconditions:** Stop any running server; start fresh (`dotnet run`) so in-memory **`dev-local-1`** inventory/skills/nodes reset. Godot **F5** with no prior session curl seeding.

**Material math** (from [`content/recipes/prototype_recipes.json`](../../content/recipes/prototype_recipes.json)):

| Step | Action | Scrap consumed | Plates gained | Scrap remaining |
|------|--------|----------------|---------------|-----------------|
| Gather ×4 | **R** at alpha (+1), beta (+2), gamma (+3), delta (+5) | — | — | **11** |
| Refine #1 | Craft **`refine_scrap_standard`** | 5 | +1 | **6** |
| Refine #2 | Craft **`refine_scrap_standard`** | 5 | +1 | **1** (+ **2** plates) |
| Make | Craft **`make_field_stim_mk0`** | 1 | −2 plates | **0** (+ **`field_stim_mk0` ×1**) |

**Checklist outline:**

1. Start server + client; confirm empty bag and skill rows on HUD.
2. Walk each resource anchor (coords from [NEO-73 manual QA](../manual-qa/NEO-73.md)); **R** once per node — verify **`GatherFeedbackLabel`**, inventory scrap, **salvage** XP without **I**.
3. Craft **`refine_scrap_standard`** twice; verify **`CraftFeedbackLabel`**, **refine** XP, plate stock.
4. Craft **`make_field_stim_mk0`**; verify consumable in **`InventoryLabel`**.
5. Optional: collapse economy HUD, expand again — panel still populated.

### 2. HUD collapse (`prototype_economy_hud_section.gd`)

- Add **`UICanvas/EconomyHudSection`** (`VBoxContainer` + script):
  - Header row: **`CheckButton`** text **`Economy HUD`** (default **pressed** / expanded).
  - Body **`VBoxContainer`**: reparent existing **`InventoryLabel`**, **`SkillProgressionLabel`**, **`CraftRecipePanel`** from flat **`UICanvas`** (remove fixed **`offset_top`** stacking — use container layout).
- **`toggled(pressed)`** → set body **`visible = pressed`**; header stays visible.
- **`main.gd`**: no signal rewiring — `@onready` paths update to new hierarchy (or export node refs unchanged if reparent preserves names).
- Document toggle in **`client/README.md`** and capstone manual QA step.

**Keep expanded by default** so capstone QA matches NEO-72–74 expectations; collapse is optional UX for viewport space.

### 3. README integration checklist

New **`## End-to-end economy loop (NEO-75)`** section after NEO-74 craft subsection:

- Flow diagram in prose: boot GETs → **R** nearest resource node → gather feedback + inventory/salvage refresh → scroll craft panel → **Craft** → craft feedback + inventory/refine refresh.
- Cross-links: NEO-72 (**I**), NEO-73 (**R** + anchors), NEO-74 (recipes).
- Pointer to **`docs/manual-qa/NEO-75.md`** as authoritative capstone script.

### 4. Module alignment (implementation batch or story end)

When acceptance criteria pass:

- **`documentation_and_implementation_alignment.md`**: E3.M1/M2/M3 — note **NEO-75 landed**, Epic 3 Slice 5 client capstone complete.
- **`epic_03_crafting_economy.md`**: Slice 5 AC checkboxes / status if not already marked.

### 5. Integration fixes (conditional)

Run capstone QA on **`main`** wiring before collapse refactor; if any step fails, fix minimal **`main.gd`** / client bug in this branch and note in plan **Decisions**. Expected path: **no logic changes** beyond HUD layout.

## Files to add

| Path | Purpose |
|------|---------|
| `docs/manual-qa/NEO-75.md` | Capstone single-session manual QA (zero Bruno). |
| `client/scripts/prototype_economy_hud_section.gd` | Collapse toggle + body visibility for economy HUD block. |
| `client/scripts/prototype_economy_hud_section.gd.uid` | Godot UID companion (same commit as `.gd`). |
| `client/test/prototype_economy_hud_section_test.gd` | GdUnit: toggle hides/shows body container. |

## Files to modify

| Path | Rationale |
|------|-----------|
| `client/scenes/main.tscn` | Add **`EconomyHudSection`**; reparent inventory/skills/craft panel under collapsible body. |
| `client/scripts/main.gd` | Update `@onready` node paths if hierarchy changes; wire collapse only if script needs refs from root. |
| `client/README.md` | End-to-end economy loop section + economy HUD toggle note. |
| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | Record NEO-75 / Slice 5 capstone complete when shipped. |
| `docs/decomposition/epics/epic_03_crafting_economy.md` | Slice 5 prototype client completion note (if needed). |

## Tests

| File | Coverage |
|------|----------|
| **`client/test/prototype_economy_hud_section_test.gd`** (add) | **`# Arrange`**: scene with section + body child. **`# Act`**: toggle **`CheckButton`**. **`# Assert`**: body **`visible`** matches pressed state. |
| Existing NEO-72–74 client tests | No change expected — capstone reuses their clients; run suite in CI. |

**No `main.gd` automated test** — orchestration verified via capstone manual QA (same policy as NEO-72–74).

## Open questions / risks

| Question / risk | Agent recommendation | Status |
|-----------------|---------------------|--------|
| **Loop already works on `main`** | Run capstone QA before collapse refactor; expect pass. | **adopted** — no integration logic changes |
| **HUD reparent breaks `@onready` paths** | Update paths in **`main.gd`** + **`craft_recipe_panel.gd`** exports in same commit as **`main.tscn`**. | **adopted** |
| **Depleted nodes block repeat QA** | Capstone script uses **one R per node** (11 scrap); delta node has capacity 10 — single pass sufficient. Re-run requires **server restart**. | **adopted** |
| **Vertical layout shift after collapse container** | Use **`VBoxContainer`** layout instead of absolute **`offset_top`** for economy block only; combat/debug labels above unchanged. | **adopted** |