# Implementation Plan: Full Technology Progression (superseded)

> Superseded by `tasks/tech-tree-plan-v0.2.md`. Retained only as a record of the rejected factory-reskin direction.

## Overview

Turn the design in `docs/tech-tree-v0.1.md` into a data-driven research and progression system after the current demo loop is stable. The implementation proceeds in playable vertical slices: first load and validate the catalog, then make each era playable from mining through research unlock, and finally add the heart-furnace victory loop and pacing telemetry. This is post-demo scope and does not change the completion bar for Tasks 1–11 in `tasks/plan.md`.

## Architecture decisions

- The CSV is a design interchange file, not runtime authority. Runtime content should use a typed Godot `Resource` or equivalent structured data generated from the same identifiers.
- Technologies, recipes, buildings, UI labels, save data, and achievements reference stable IDs; display names remain localizable data.
- Research is fixed-tick and event-driven like the current machine simulation. A lab wakes on input, queue, completion, or unlock changes rather than polling independently each frame.
- Unlock evaluation lives in the simulation layer. UI only displays state and submits commands.
- Every era is delivered as a complete loop: resource access → processing → research material → gate technology → visible objective.
- The 8/24-hour targets are verified by route simulation and instrumented playtests, not inferred from green unit tests.

## Dependency graph

```text
TT1 catalog contract
        |
        +----> TT2 graph/cost validator
        |
        v
TT3 research runtime ----> TT4 UI + save
        |
        v
TT5 T0/T1 slice -> TT6 T2 slice -> TT7 T3 slice -> TT8 T4 slice -> TT9 T5 + victory
                                                              |              |
                                                              +------>-------+
                                                                     v
                                                          TT10 optional/postgame
                                                                     |
                                                                     v
                                                          TT11 telemetry/tuning
```

## Task list

### Phase 1: Data and rules

- [ ] TT1: Define stable technology, recipe, building, and unlock IDs
- [ ] TT2: Add dependency validation and route-cost simulation
- [ ] TT3: Implement fixed-tick research runtime
- [ ] TT4: Add research UI, queue commands, and save state

### Checkpoint: Research foundation

- [ ] The full catalog loads with no duplicate, missing, cyclic, or role-invalid dependency
- [ ] A headless test researches a node by consuming exact item counts
- [ ] Save/load preserves completed and partial research exactly

### Phase 2: Early playable progression

- [ ] TT5: Deliver T0/T1 from repair milestones to automated cyan tablets
- [ ] TT6: Deliver T2 mana-logistics and ether-fluid introduction

### Checkpoint: Early game

- [ ] A fresh run reaches crimson-tablet production without debug spawning
- [ ] Existing belt, mana-pipe, and bridge-arm behavior remains deterministic
- [ ] Every stopped lab or production machine exposes a readable reason

### Phase 3: Midgame scale

- [ ] TT7: Deliver T3 alchemy, precision construction, and leyline survey
- [ ] TT8: Deliver T4 cross-island shipping, phase metallurgy, and emerald tablets

### Checkpoint: Midgame

- [ ] At least one required resource must arrive from another island
- [ ] Violet and emerald recipes exercise the intended multi-stage chains
- [ ] A reference factory meets the normal and expert tablet-rate targets

### Phase 4: Endgame and continuation

- [ ] TT9: Deliver T5 source extraction, heart furnace, timed ignition, and achievements
- [ ] TT10: Add comfort, warding, and repeatable postgame branches

### Checkpoint: Complete progression

- [ ] Mainline can finish without researching any O-role node
- [ ] Completing G13 alone cannot trigger victory
- [ ] First stable ignition records one authoritative completion time and unlocks postgame research

### Phase 5: Pacing proof

- [ ] TT11: Add route telemetry, benchmark saves, and 8/24-hour balance gates

### Checkpoint: Release candidate

- [ ] Expert-route P50 is at most 7:15 and P90 at most 8:00
- [ ] Experienced first-play P50 is 18–21 hours and P75 at most 24:00
- [ ] No mainline wait exceeds five minutes when the era reference factory meets target throughput

## Risks and mitigations

| Risk | Impact | Mitigation |
|---|---:|---|
| Sixty-two technologies create content before the core is fun | High | Implement by era and stop at every checkpoint for a complete playable test |
| Research logic duplicates recipe/building unlock rules | High | One ID-based unlock service is authoritative for simulation, UI, and saving |
| Random map distance determines achievement validity | High | Clamp required-resource distance and ship fixed benchmark seeds |
| Optional automation becomes secretly mandatory for 24 hours | High | Maintain a no-comfort-tech reference route and compare it with the recommended route |
| Speedrun balance removes normal-player breathing room | High | Tune guidance and convenience separately from mainline material cost |
| High-tier factories overload scene nodes | High | Preserve data-oriented simulation, sleeping machines, and batched visible rendering |

## Open decisions with safe defaults

- Hostile enemies: default to environmental hazards and optional warding until combat receives its own approved design.
- Campaign map: use a bounded handcrafted resource topology for balance tests; procedural variants must satisfy the same distance envelope.
- Localization names: treat names in v0.1 as Chinese working names while IDs remain stable.
- Achievement clock: count simulation time only, excluding pause/load/non-interactive cutscenes.
- Existing demo: keep its all-tools-available showcase mode even after campaign unlock rules exist.