From d7c3ede5a7dc7053aa67438a5e5656a3fdee33c8 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Sat, 30 May 2026 19:25:56 -0400 Subject: [PATCH] chore: Epic 5 stable slice anchors and doc cluster alignment Add explicit HTML slice anchors to epic_05, restore deep links across E5 backlogs and plans, fix E5M2 NEO-98 resolve vocabulary and E5.M3 Linear row, and record review follow-up as Done. --- .../decomposition/epics/epic_05_pve_combat.md | 10 +++ .../modules/E5_M3_EncounterAndRewardTables.md | 2 +- docs/plans/E5M1-prototype-backlog.md | 6 +- docs/plans/E5M2-prototype-backlog.md | 14 ++-- docs/plans/E5M3-prototype-backlog.md | 6 +- docs/plans/NEO-84-implementation-plan.md | 2 +- docs/plans/NEO-86-implementation-plan.md | 2 +- docs/plans/NEO-96-implementation-plan.md | 2 +- docs/plans/NEO-98-implementation-plan.md | 2 +- .../2026-05-30-epic-5-anchor-stability.md | 77 +++++++++++++++++++ server/README.md | 4 +- 11 files changed, 108 insertions(+), 19 deletions(-) create mode 100644 docs/reviews/2026-05-30-epic-5-anchor-stability.md diff --git a/docs/decomposition/epics/epic_05_pve_combat.md b/docs/decomposition/epics/epic_05_pve_combat.md index 910a200..619a1f7 100644 --- a/docs/decomposition/epics/epic_05_pve_combat.md +++ b/docs/decomposition/epics/epic_05_pve_combat.md @@ -46,6 +46,8 @@ Deliver tab-target combat resolution, NPC behaviors and telegraphs, encounter te ## Implementation Slices (Backlog-Ready) + + ### Slice 1 - Combat rules MVP - Scope: E5.M1 with target lock, basic attacks, 4-6 abilities, cooldowns/resources per prototype scope. @@ -56,6 +58,8 @@ Deliver tab-target combat resolution, NPC behaviors and telegraphs, encounter te **Linear backlog:** [E5M1-prototype-backlog.md](../../plans/E5M1-prototype-backlog.md) — [NEO-76](https://linear.app/neon-sprawl/issue/NEO-76) → [NEO-86](https://linear.app/neon-sprawl/issue/NEO-86); gig XP **E5M1-10** [NEO-44](https://linear.app/neon-sprawl/issue/NEO-44). + + ### Slice 2 - NPC archetypes and telegraphs - Scope: E5.M2 for three archetypes: melee pressure, ranged control, elite mini-boss. @@ -66,6 +70,8 @@ Deliver tab-target combat resolution, NPC behaviors and telegraphs, encounter te **Linear backlog:** [E5M2-prototype-backlog.md](../../plans/E5M2-prototype-backlog.md) — [NEO-87](https://linear.app/neon-sprawl/issue/NEO-87) → [NEO-98](https://linear.app/neon-sprawl/issue/NEO-98); client capstone **E5M2-12** [NEO-98](https://linear.app/neon-sprawl/issue/NEO-98). Verify in **Godot**, not Bruno-only. + + ### Slice 3 - Encounters and loot routing - Scope: E5.M3 wired to E3.M3 and E7.M2 for rewards and quest progress. @@ -76,6 +82,8 @@ Deliver tab-target combat resolution, NPC behaviors and telegraphs, encounter te **Linear backlog:** [E5M3-prototype-backlog.md](../../plans/E5M3-prototype-backlog.md) — [NEO-100](https://linear.app/neon-sprawl/issue/NEO-100) → [NEO-111](https://linear.app/neon-sprawl/issue/NEO-111); client capstone **E5M3-12** [NEO-111](https://linear.app/neon-sprawl/issue/NEO-111). Verify in **Godot**, not Bruno-only. + + ### Slice 4 - Group scaling (pre-production) - Scope: E5.M4 with party-sized modifiers behind E8.M1. @@ -91,6 +99,8 @@ Deliver tab-target combat resolution, NPC behaviors and telegraphs, encounter te - Risk: Loot tables desync from item schema. - Mitigation: Shared validation in content pipeline; lint reward references. + + ## Definition of Done - Prototype combat, archetypes, and encounters meet documented minimums in master plan. diff --git a/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md b/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md index 41fc246..ce7f83e 100644 --- a/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md +++ b/docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md @@ -8,7 +8,7 @@ | **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) | | **Stage target** | Prototype | | **Status** | In Progress — Slice 3 backlog [E5M3-prototype-backlog.md](../../plans/E5M3-prototype-backlog.md): **E5M3-01** [NEO-100](https://linear.app/neon-sprawl/issue/NEO-100) → **E5M3-12** [NEO-111](https://linear.app/neon-sprawl/issue/NEO-111) decomposed | -| **Linear** | Label **`E5.M3`** · [E5M3-prototype-backlog.md](../../plans/E5M3-prototype-backlog.md) **E5M3-01** [NEO-100](https://linear.app/neon-sprawl/issue/NEO-100) · **E5M3-02** [NEO-101](https://linear.app/neon-sprawl/issue/NEO-101) · **E5M3-03** [NEO-102](https://linear.app/neon-sprawl/issue/NEO-102) · **E5M3-04** [NEO-103](https://linear.app/neon-sprawl/issue/NEO-103) · **E5M3-05** [NEO-104](https://linear.app/neon-sprawl/issue/NEO-104) · **E5M3-06** [NEO-105](https://linear.app/neon-sprawl/issue/NEO-105) · **E5M3-07** [NEO-106](https://linear.app/neon-sprawl/issue/NEO-106) · **E5M3-08** [NEO-107](https://linear.app/neon-sprawl/issue/NEO-107) · **E5M3-09** [NEO-108](https://linear.app/neon-sprawl/issue/NEO-108) · **E5M3-10** [NEO-109](https://linear.app/neon-sprawl/issue/NEO-109) · **E5M3-11** [NEO-110](https://linear.app/neon-sprawl/issue/NEO-110) · **E5M3-12** [NEO-111](https://linear.app/neon-sprawl/issue/NEO-111) | +| **Linear** | Label **`E5.M3`** · [E5M3-prototype-backlog.md](../../plans/E5M3-prototype-backlog.md) **E5M3-01** [NEO-100](https://linear.app/neon-sprawl/issue/NEO-100) · **E5M3-02** [NEO-101](https://linear.app/neon-sprawl/issue/NEO-101) · **E5M3-03** [NEO-102](https://linear.app/neon-sprawl/issue/NEO-102) · **E5M3-04** [NEO-103](https://linear.app/neon-sprawl/issue/NEO-103) · **E5M3-05** [NEO-104](https://linear.app/neon-sprawl/issue/NEO-104) · **E5M3-06** [NEO-105](https://linear.app/neon-sprawl/issue/NEO-105) · **E5M3-07** [NEO-106](https://linear.app/neon-sprawl/issue/NEO-106) · **E5M3-08** [NEO-108](https://linear.app/neon-sprawl/issue/NEO-108) · **E5M3-09** [NEO-107](https://linear.app/neon-sprawl/issue/NEO-107) · **E5M3-10** [NEO-109](https://linear.app/neon-sprawl/issue/NEO-109) · **E5M3-11** [NEO-110](https://linear.app/neon-sprawl/issue/NEO-110) · **E5M3-12** [NEO-111](https://linear.app/neon-sprawl/issue/NEO-111) | ## Purpose diff --git a/docs/plans/E5M1-prototype-backlog.md b/docs/plans/E5M1-prototype-backlog.md index 08dd787..398e9e9 100644 --- a/docs/plans/E5M1-prototype-backlog.md +++ b/docs/plans/E5M1-prototype-backlog.md @@ -1,6 +1,6 @@ # E5.M1 — Prototype story backlog (CombatRulesEngine) -Working backlog for **Epic 5 — Slice 1** ([combat rules MVP](../decomposition/epics/epic_05_pve_combat.md#slice-1---combat-rules-mvp)). Decomposition and contracts: [E5.M1 — CombatRulesEngine](../decomposition/modules/E5_M1_CombatRulesEngine.md). +Working backlog for **Epic 5 — Slice 1** ([Epic 5 · Slice 1 — combat rules MVP](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-1)). Decomposition and contracts: [E5.M1 — CombatRulesEngine](../decomposition/modules/E5_M1_CombatRulesEngine.md). **Labels (Linear):** every issue **`E5.M1`**; add **`server`** or **`client`** + **`Story`** as listed. @@ -287,7 +287,7 @@ Working backlog for **Epic 5 — Slice 1** ([combat rules MVP](../decomposition/ **Acceptance criteria** -- [x] Hook names match [epic_05 Slice 1](../decomposition/epics/epic_05_pve_combat.md#slice-1---combat-rules-mvp) vocabulary. +- [x] Hook names match [epic_05 Slice 1](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-1) vocabulary. - [x] **`enemy_defeat`** site fires only on transition to defeated (not every overkill cast). **Landed ([NEO-84](https://linear.app/neon-sprawl/issue/NEO-84)):** comment-only **`ability_used`** / **`enemy_defeat`** hook sites in **`CombatOperations.TryResolve`**; reserved **`encounter_start`** / **`player_death`** ([NEO-84-implementation-plan.md](NEO-84-implementation-plan.md)); [server README — Combat telemetry hooks](../../../server/README.md#combat-telemetry-hooks-neo-84). @@ -368,7 +368,7 @@ Working backlog for **Epic 5 — Slice 1** ([combat rules MVP](../decomposition/ - [x] Human completes script with server + client; **`prototype_target_alpha`** shows defeated state in HUD. - [x] Epic 5 Slice 1 AC: combat readable in fixed isometric camera; no silent cast failures. -- [x] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#definition-of-done) for prototype minimums. +- [x] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#epic-5-definition-of-done) for prototype minimums. **Landed ([NEO-86](https://linear.app/neon-sprawl/issue/NEO-86)):** **`gig_progression_client.gd`** + **`GigXpLabel`**; defeat-triggered gig GET refresh; capstone manual QA [`NEO-86`](../manual-qa/NEO-86.md); plan [NEO-86-implementation-plan.md](NEO-86-implementation-plan.md); `client/README.md` end-to-end combat loop section. Epic 5 Slice 1 client capstone complete. diff --git a/docs/plans/E5M2-prototype-backlog.md b/docs/plans/E5M2-prototype-backlog.md index 9c0e01c..dc2d739 100644 --- a/docs/plans/E5M2-prototype-backlog.md +++ b/docs/plans/E5M2-prototype-backlog.md @@ -1,6 +1,6 @@ # E5.M2 — Prototype story backlog (NpcAiAndBehaviorProfiles) -Working backlog for **Epic 5 — Slice 2** ([NPC archetypes and telegraphs](../decomposition/epics/epic_05_pve_combat.md#slice-2---npc-archetypes-and-telegraphs)). Decomposition and contracts: [E5.M2 — NpcAiAndBehaviorProfiles](../decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md). +Working backlog for **Epic 5 — Slice 2** ([Epic 5 · Slice 2 — NPC archetypes and telegraphs](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-2)). Decomposition and contracts: [E5.M2 — NpcAiAndBehaviorProfiles](../decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md). **Full-stack policy:** Epics deliver **playable game features**. Every **player-visible** story has a **`client`** Linear issue created in **this same decomposition pass** — not an undocumented follow-up. Reference: [E5M1 (paired server+client)](../plans/E5M1-prototype-backlog.md). @@ -69,11 +69,13 @@ Working backlog for **Epic 5 — Slice 2** ([NPC archetypes and telegraphs](../d | Player HP | **Session in-memory** **`IPlayerCombatHealthStore`** (100 default); **no Postgres** | NPC pressure readable in Godot without E5.M1 persistence scope | | NPC tick | **Lazy advance** on **`GET …/npc-runtime-snapshot`** poll (client ~1 Hz in combat pocket) | Mirrors cooldown snapshot poll ([NEO-32](https://linear.app/neon-sprawl/issue/NEO-32)) | | Telegraph wire | **`GET /game/world/npc-runtime-snapshot`** v1 — states + active **`TelegraphEvent`** rows | Single poll surface; no client-side windup math | -| NPC attacks | **Deterministic** damage from `NpcBehaviorDef.attackDamage` after telegraph resolves | Matches E5.M1 no-RNG combat | +| NPC attacks | **Deterministic** damage from behavior **`attackAbilityId`** → ability catalog **`baseDamage`** when holder is within ability **`maxRange`** after telegraph resolves | Matches E5.M1 no-RNG combat; behavior **`attackDamage`** = projection + CI cross-ref only ([NEO-98](https://linear.app/neon-sprawl/issue/NEO-98)) | | PvP | NPCs **never** acquire player targets blocked by E6 stub | [pvp_combat_integration.md](../decomposition/modules/pvp_combat_integration.md) | | World placement | Static **`PrototypeNpcRegistry`** (successor to target registry anchors) until [E4.M2](../decomposition/modules/E4_M2_SpawnEcologyController.md) | Same static-registry pattern as E5.M1 dummies | | HUD fidelity | Prototype Labels / debug panels (not final art) | NEO-85 / NEO-97 precedent | +**Resolve source ([NEO-98](https://linear.app/neon-sprawl/issue/NEO-98)):** telegraph complete uses **`attackAbilityId`** + NPC ability catalog (**`baseDamage`**, **`maxRange`**), not behavior **`attackDamage`**. **`attackDamage`** remains on the behavior row for HTTP projection and CI cross-ref only. + --- ### E5M2-01 — Prototype NpcBehaviorDef catalog + schemas + CI @@ -280,7 +282,7 @@ Working backlog for **Epic 5 — Slice 2** ([NPC archetypes and telegraphs](../d ### E5M2-09 — NPC attack resolve + session player combat HP -**Goal:** When telegraph completes, apply **`attackDamage`** to aggro holder via **`IPlayerCombatHealthStore`**; expose player HP on snapshot or dedicated GET. +**Goal:** When telegraph completes, resolve via behavior **`attackAbilityId`** → ability catalog **`baseDamage`** when aggro holder is within ability **`maxRange`**; apply to holder via **`IPlayerCombatHealthStore`**; expose player HP on snapshot or dedicated GET. Behavior **`attackDamage`** is projection/CI cross-ref only (**[NEO-98](https://linear.app/neon-sprawl/issue/NEO-98)** superseded direct **`attackDamage`** resolve). **In scope** @@ -301,7 +303,7 @@ Working backlog for **Epic 5 — Slice 2** ([NPC archetypes and telegraphs](../d - [x] Player HP read model matches store after NPC attack. - [x] No client-side damage math required for verification (Bruno or integration tests). -**Landed ([NEO-95](https://linear.app/neon-sprawl/issue/NEO-95)):** **`IPlayerCombatHealthStore`** + **`NpcAttackOperations.TryResolveTelegraphComplete`** — telegraph complete applies catalog damage; **`GET /game/players/{id}/combat-health`**; plan [NEO-95-implementation-plan.md](NEO-95-implementation-plan.md). +**Landed ([NEO-95](https://linear.app/neon-sprawl/issue/NEO-95)):** **`IPlayerCombatHealthStore`** + **`NpcAttackOperations.TryResolveTelegraphComplete`** — telegraph complete applies catalog damage; **`GET /game/players/{id}/combat-health`**; plan [NEO-95-implementation-plan.md](NEO-95-implementation-plan.md). **Resolve source superseded by [NEO-98](https://linear.app/neon-sprawl/issue/NEO-98):** **`attackAbilityId`** + ability **`baseDamage`** / **`maxRange`** (behavior **`attackDamage`** = projection/CI cross-ref only). **Client counterpart:** [NEO-97](https://linear.app/neon-sprawl/issue/NEO-97) — player HP + incoming telegraph/attack feedback labels. @@ -322,7 +324,7 @@ Working backlog for **Epic 5 — Slice 2** ([NPC archetypes and telegraphs](../d **Acceptance criteria** -- [x] Hook names match [epic_05 Slice 2](../decomposition/epics/epic_05_pve_combat.md#slice-2---npc-archetypes-and-telegraphs) vocabulary. +- [x] Hook names match [epic_05 Slice 2](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-2) vocabulary. - [x] No runtime behavior change beyond comments. **Landed ([NEO-96](https://linear.app/neon-sprawl/issue/NEO-96)):** comment-only **`telegraph_fired`** + **`npc_state_transition`** hook sites in **`NpcRuntimeOperations`**; plan [NEO-96-implementation-plan.md](NEO-96-implementation-plan.md). @@ -378,7 +380,7 @@ Working backlog for **Epic 5 — Slice 2** ([NPC archetypes and telegraphs](../d - [x] Human completes script with server + client; telegraph timing readable before damage. - [x] Epic 5 Slice 2 AC: telegraph timing matches UI feedback; aggro rules feel deterministic in manual QA. - [x] All three archetypes defeated in one session; **`CombatTargetHpLabel`** shows defeated for each (manual QA steps 9, 14, 18). -- [x] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#definition-of-done) for prototype minimums. +- [x] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#epic-5-definition-of-done) for prototype minimums. **Landed ([NEO-98](https://linear.app/neon-sprawl/issue/NEO-98)):** playable NPC telegraph combat capstone — [`NEO-98` manual QA](../manual-qa/NEO-98.md); `client/README.md` end-to-end NPC telegraph combat loop section; plan [NEO-98-implementation-plan.md](NEO-98-implementation-plan.md). **Epic 5 Slice 2 client capstone complete.** diff --git a/docs/plans/E5M3-prototype-backlog.md b/docs/plans/E5M3-prototype-backlog.md index d022aba..da301ba 100644 --- a/docs/plans/E5M3-prototype-backlog.md +++ b/docs/plans/E5M3-prototype-backlog.md @@ -1,6 +1,6 @@ # E5.M3 — Prototype story backlog (EncounterAndRewardTables) -Working backlog for **Epic 5 — Slice 3** ([encounters and loot routing](../decomposition/epics/epic_05_pve_combat.md#slice-3---encounters-and-loot-routing)). Decomposition and contracts: [E5.M3 — EncounterAndRewardTables](../decomposition/modules/E5_M3_EncounterAndRewardTables.md). +Working backlog for **Epic 5 — Slice 3** ([Epic 5 · Slice 3 — encounters and loot routing](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-3)). Decomposition and contracts: [E5.M3 — EncounterAndRewardTables](../decomposition/modules/E5_M3_EncounterAndRewardTables.md). **Full-stack policy:** Epics deliver **playable game features**. Every **player-visible** story has a **`client`** Linear issue created in **this same decomposition pass** — not an undocumented follow-up. Reference: [E5M2 (paired server+client)](../plans/E5M2-prototype-backlog.md). @@ -296,7 +296,7 @@ Working backlog for **Epic 5 — Slice 3** ([encounters and loot routing](../dec **Acceptance criteria** -- [ ] Hook names match [epic_05 Slice 3](../decomposition/epics/epic_05_pve_combat.md#slice-3---encounters-and-loot-routing) vocabulary. +- [ ] Hook names match [epic_05 Slice 3](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-3) vocabulary. - [ ] No runtime behavior change beyond comments. --- @@ -345,7 +345,7 @@ Working backlog for **Epic 5 — Slice 3** ([encounters and loot routing](../dec - [ ] Human completes script with server + client; loot readable in inventory HUD. - [ ] Epic 5 Slice 3 AC: completing defined encounter grants expected items + quest token **once**. -- [ ] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#definition-of-done) for prototype minimums. +- [ ] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#epic-5-definition-of-done) for prototype minimums. **Client counterpart:** this issue (**NEO-111**). diff --git a/docs/plans/NEO-84-implementation-plan.md b/docs/plans/NEO-84-implementation-plan.md index 38a01b3..e28dd89 100644 --- a/docs/plans/NEO-84-implementation-plan.md +++ b/docs/plans/NEO-84-implementation-plan.md @@ -44,7 +44,7 @@ ## Acceptance criteria checklist -- [x] Hook names match [epic_05 Slice 1](../decomposition/epics/epic_05_pve_combat.md#slice-1---combat-rules-mvp) vocabulary (`ability_used`, `enemy_defeat`, reserved `encounter_start`, `player_death`). +- [x] Hook names match [epic_05 Slice 1](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-1) vocabulary (`ability_used`, `enemy_defeat`, reserved `encounter_start`, `player_death`). - [x] **`enemy_defeat`** site documents emit only on transition to defeated (not re-hit / overkill — enforced by `target_defeated` deny before damage). ## Technical approach diff --git a/docs/plans/NEO-86-implementation-plan.md b/docs/plans/NEO-86-implementation-plan.md index bfaac71..c0918c6 100644 --- a/docs/plans/NEO-86-implementation-plan.md +++ b/docs/plans/NEO-86-implementation-plan.md @@ -48,7 +48,7 @@ No other blocking decisions — combat loop HUD, hotbar pulse bootstrap, and eve - [x] Human completes **`docs/manual-qa/NEO-86.md`** with server + client; **`prototype_target_alpha`** shows defeated state in HUD. - [x] Epic 5 Slice 1 AC: combat readable in fixed isometric camera; no silent cast failures on deny. - [x] **`breach`** gig XP visible in Godot after defeat (≥ **25** from fresh-server baseline). -- [x] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#definition-of-done) for prototype minimums. +- [x] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#epic-5-definition-of-done) for prototype minimums. ## Implementation reconciliation (shipped) diff --git a/docs/plans/NEO-96-implementation-plan.md b/docs/plans/NEO-96-implementation-plan.md index bf091bb..785c651 100644 --- a/docs/plans/NEO-96-implementation-plan.md +++ b/docs/plans/NEO-96-implementation-plan.md @@ -46,7 +46,7 @@ ## Acceptance criteria checklist - [x] **`TODO(E9.M1)`** markers present at **`telegraph_fired`** and **`npc_state_transition`** hook sites in NPC runtime path. -- [x] Hook names match [epic_05 Slice 2](../decomposition/epics/epic_05_pve_combat.md#slice-2---npc-archetypes-and-telegraphs) vocabulary (`telegraph_fired`, `npc_state_transition`). +- [x] Hook names match [epic_05 Slice 2](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-2) vocabulary (`telegraph_fired`, `npc_state_transition`). - [x] No runtime behavior change beyond comments / doc cross-links. ## Implementation reconciliation (shipped) diff --git a/docs/plans/NEO-98-implementation-plan.md b/docs/plans/NEO-98-implementation-plan.md index 0c5d6b2..87a0aaa 100644 --- a/docs/plans/NEO-98-implementation-plan.md +++ b/docs/plans/NEO-98-implementation-plan.md @@ -50,7 +50,7 @@ - [x] Human completes **`docs/manual-qa/NEO-98.md`** with server + client; telegraph timing readable before damage on the melee spine. - [x] Epic 5 Slice 2 AC: telegraph timing matches UI feedback; aggro rules feel deterministic in manual QA. - [x] All three archetypes defeated in one session; **`CombatTargetHpLabel`** shows defeated for each. -- [x] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#definition-of-done) for prototype minimums. +- [x] Re-read [epic_05 Definition of Done](../decomposition/epics/epic_05_pve_combat.md#epic-5-definition-of-done) for prototype minimums. ## Implementation reconciliation (shipped) diff --git a/docs/reviews/2026-05-30-epic-5-anchor-stability.md b/docs/reviews/2026-05-30-epic-5-anchor-stability.md new file mode 100644 index 0000000..8044f6f --- /dev/null +++ b/docs/reviews/2026-05-30-epic-5-anchor-stability.md @@ -0,0 +1,77 @@ +# Documentation review — Epic 5 anchor stability + doc cluster + +**Date:** 2026-05-30 +**Scope:** Uncommitted docs batch — `epic_05_pve_combat.md` stable slice anchors; link updates in `E5M1`/`E5M2`/`E5M3` backlogs, `NEO-84`/`NEO-86`/`NEO-96`/`NEO-98` plans, `server/README.md`; cross-check against Epic 5 modules, game-design progression seams, and full-stack backlog policy +**Base:** Working tree on `main` (uncommitted) + +## Verdict + +**Approve** — suggestions applied (2026-05-30 follow-up). + +## Summary + +The batch correctly adds explicit HTML slice anchors to `epic_05_pve_combat.md` (matching the Epic 1 / Epic 3 precedent) and removes fragile GitHub heading slugs (`#slice-1---combat-rules-mvp`, etc.) that were prone to renderer drift. Hook vocabulary, gig-vs-skill XP boundaries, and full-stack E5M1/E5M2/E5M3 backlog pairing remain aligned with game-design and module docs. Follow-ups from initial review (stable deep links, E5M2 NEO-98 resolve vocabulary, E5.M3 Linear row) are **Done.** + +## Documentation checked + +| Path | Result | +|------|--------| +| `docs/decomposition/epics/epic_05_pve_combat.md` | **Matches** — `` … `epic-5-slice-4`, `epic-5-definition-of-done`; slice telemetry vocabulary unchanged. | +| `docs/plans/E5M1-prototype-backlog.md` | **Matches** — epic links use stable `#epic-5-slice-1` / `#epic-5-definition-of-done` anchors; Slice 1 complete; full-stack checklist satisfied. | +| `docs/plans/E5M2-prototype-backlog.md` | **Matches** — stable slice/DoD anchors; kickoff + E5M2-09 document NEO-98 **`attackAbilityId`** resolve supersession; full-stack pairing **NEO-97**/**NEO-98** intact. | +| `docs/plans/E5M3-prototype-backlog.md` | **Matches** — stable `#epic-5-slice-3` / DoD anchors; decomposition checklist + client capstone **NEO-111** present. Gig XP / encounter loot separation matches `progression.md` seams. | +| `docs/plans/NEO-84-implementation-plan.md` | **Matches** — hook names align with epic Slice 1 list. | +| `docs/plans/NEO-86-implementation-plan.md` | **Matches** — capstone AC + gig XP proof; DoD link uses `#epic-5-definition-of-done`. | +| `docs/plans/NEO-96-implementation-plan.md` | **Matches** — Slice 2 hook vocabulary; reconciliation complete. | +| `docs/plans/NEO-98-implementation-plan.md` | **Matches** — capstone scope reconciliation documents NEO-98 server integration; aligns with [2026-05-30-NEO-98-followup.md](2026-05-30-NEO-98-followup.md). | +| `docs/decomposition/modules/E5_M1_CombatRulesEngine.md` | **Matches** — gig XP on defeat via NEO-44; combat → gig, not E2.M2 skill XP. | +| `docs/decomposition/modules/E5_M2_NpcAiAndBehaviorProfiles.md` | **Matches** — freeze table + NEO-98 `attackAbilityId` / range-gated resolve documented. | +| `docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md` | **Matches** — slug table (lines 50–63) and summary **Linear** row both use **E5M3-08 → NEO-108**, **E5M3-09 → NEO-107**. | +| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | **Matches** — E5.M1 Ready, E5.M2 Ready + NEO-98 integration, E5.M3 decomposed In Progress. | +| `docs/game-design/progression.md`, `gigs.md`, `abilities.md` | **N/A** (not edited) — spot-check: combat encounters → gig XP; no skill XP from fight loop reintroduced in Epic 5 docs. | +| `server/README.md` (NEO-84 combat hooks) | **Matches** — epic link valid; hook semantics unchanged. | +| `server/README.md` (NEO-96 NPC hooks) | **Matches** — epic cross-link to Slice 2 anchor added (parity with NEO-84). | + +## Blocking issues + +None. + +## Suggestions + +1. ~~**Use stable slice anchors in deep links** — Anchors exist (`epic-5-slice-1` … `epic-5-slice-4`, `epic-5-definition-of-done`) but updated links drop fragments entirely. Match Epic 3 / E3M1 pattern:~~ **Done.** Backlog intros, telemetry AC, DoD re-read AC, and `server/README.md` NEO-84/NEO-96 now use `#epic-5-slice-N` / `#epic-5-definition-of-done`. + + ~~Example target:~~ + + ```markdown + [Epic 5 · Slice 2 — NPC archetypes and telegraphs](../decomposition/epics/epic_05_pve_combat.md#epic-5-slice-2) + ``` + +2. ~~**E5M2 backlog — NEO-98 resolve source drift** — Kickoff table row **NPC attacks** and **E5M2-09** goal still say telegraph resolve applies `NpcBehaviorDef.attackDamage`. Module doc and NEO-98 plan correctly document **`attackAbilityId`** + ability **`baseDamage`** / **`maxRange`**. Add a kickoff footnote or revise the E5M2-09 goal + landed **NEO-95** line to note NEO-98 supersession (behavior **`attackDamage`** = projection/CI cross-ref only).~~ **Done.** + +3. ~~**E5_M3 module summary Linear row** — Line 11 lists **E5M3-08 → NEO-107**, **E5M3-09 → NEO-108**; backlog and slug table in the same module file use **E5M3-08 → NEO-108**, **E5M3-09 → NEO-107** (documented creation-order swap). Fix the summary **Linear** cell to match the slug table.~~ **Done.** + +## Nits + +- ~~**Related docs path style** — `E5M2`/`E5M3` backlogs use `./../decomposition/epics/epic_05_pve_combat.md`; `E5M1` uses `../decomposition/...`. Normalize to one form.~~ **Done.** All E5 backlogs use `../decomposition/...`. +- **Epic 5 Slice 4** — Anchor `epic-5-slice-4` added with no current consumers (pre-production); fine as forward-looking stability. +- **Prior reviews** — [2026-05-30-NEO-98-followup.md](2026-05-30-NEO-98-followup.md) suggestions are addressed; no reopen needed for NEO-98 doc cluster. + +## Verification + +After applying suggestions: + +```bash +# No remaining fragile epic_05 heading slugs +rg 'epic_05_pve_combat\.md#' docs/ server/ + +# Epic 5 stable anchors referenced where slice-specific +rg 'epic-5-slice-|epic-5-definition-of-done' docs/ + +# E5M3 slug ↔ Linear consistency +rg 'E5M3-0[89].*NEO-10[78]' docs/plans/E5M3-prototype-backlog.md docs/decomposition/modules/E5_M3_EncounterAndRewardTables.md + +# NEO-98 resolve vocabulary in E5M2 backlog +rg 'attackDamage|attackAbilityId' docs/plans/E5M2-prototype-backlog.md +``` + +Human re-read: epic Slice 1–3 telemetry hook lists vs plan AC checklists; E5M3 kickoff **Gig XP** row vs `progression.md` combat → gig seam. diff --git a/server/README.md b/server/README.md index 1d6c5cf..ce42dab 100644 --- a/server/README.md +++ b/server/README.md @@ -192,7 +192,7 @@ Plan: [NEO-93 implementation plan](../../docs/plans/NEO-93-implementation-plan.m ### NPC runtime telemetry hooks (NEO-96) -Comment-only hook sites in **`NpcRuntimeOperations.AdvanceAll`** for future E9.M1 catalog events — **`telegraph_fired`** at each **`telegraph_windup`** entry (aggro→telegraph and recover→telegraph); **`npc_state_transition`** on every committed state change during **`AdvanceAll`** (including holder clear → **`idle`**). Dev fixture **`ResetAllPrototypeRows`** writes idle directly and bypasses **`AdvanceOne`** hooks (optional E9.M1 anchor noted on reset path). **`TODO(E9.M1)`** — no production ingest. Snapshot GET invokes **`AdvanceAll`** before read (no duplicate API-layer hooks). Plan: [NEO-96 implementation plan](../../docs/plans/NEO-96-implementation-plan.md). +Comment-only hook sites in **`NpcRuntimeOperations.AdvanceAll`** for future E9.M1 catalog events ([Epic 5 Slice 2](../../docs/decomposition/epics/epic_05_pve_combat.md#epic-5-slice-2)) — **`telegraph_fired`** at each **`telegraph_windup`** entry (aggro→telegraph and recover→telegraph); **`npc_state_transition`** on every committed state change during **`AdvanceAll`** (including holder clear → **`idle`**). Dev fixture **`ResetAllPrototypeRows`** writes idle directly and bypasses **`AdvanceOne`** hooks (optional E9.M1 anchor noted on reset path). **`TODO(E9.M1)`** — no production ingest. Snapshot GET invokes **`AdvanceAll`** before read (no duplicate API-layer hooks). Plan: [NEO-96 implementation plan](../../docs/plans/NEO-96-implementation-plan.md). ## NPC runtime snapshot (NEO-94) @@ -247,7 +247,7 @@ Plan: [NEO-81 implementation plan](../../docs/plans/NEO-81-implementation-plan.m ### Combat telemetry hooks (NEO-84) -Comment-only hook sites in **`CombatOperations.TryResolve`** for future E9.M1 catalog events ([Epic 5 Slice 1](../../docs/decomposition/epics/epic_05_pve_combat.md#slice-1---combat-rules-mvp)). **`TODO(E9.M1)`** — no production ingest. HTTP **`POST …/ability-cast`** calls the engine only (no duplicate API-layer hooks for these names). +Comment-only hook sites in **`CombatOperations.TryResolve`** for future E9.M1 catalog events ([Epic 5 Slice 1](../../docs/decomposition/epics/epic_05_pve_combat.md#epic-5-slice-1)). **`TODO(E9.M1)`** — no production ingest. HTTP **`POST …/ability-cast`** calls the engine only (no duplicate API-layer hooks for these names). - **`ability_used`** — on every successful resolve (zero-damage abilities included). - **`enemy_defeat`** — only when lethal damage drives **`after.Defeated`** to **`true`** (re-hit on defeated targets denies at **`target_defeated`** before damage).