neon-sprawl/docs/plans/NEO-75-implementation-plan.md

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 + E3.M2 + E3.M3 · 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 inventory HUD (Done); NEO-73 gather feedback (Done); 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):

• 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 E3.M1/M2/M3 rows + Epic 3 Slice 5 “complete” note in 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

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

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):

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); 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.	pending (implementation)
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