diff --git a/.cursor/rules/story-kickoff.md b/.cursor/rules/story-kickoff.md index 2e287c7..b5d9503 100644 --- a/.cursor/rules/story-kickoff.md +++ b/.cursor/rules/story-kickoff.md @@ -13,6 +13,13 @@ When the user starts work on a **Linear issue** (e.g. issue key `NEO-5`, phrases - Use **concrete questions**, often with short options when helpful; group related questions so the user can answer in one pass. - When the Cursor session supports it (**Agent** mode), prefer **`AskQuestion`** multiple-choice for blocking decisions (same pattern as [story-end](story-end.md) §4a for **Linear state** after “end story”) instead of only long prose lists. +### Clarifications gate (hard requirement) + +- **Do not** create or update `docs/plans/{KEY}-implementation-plan.md` until clarification questions have been asked and the user has answered (or explicitly says no questions are needed). +- If at least one **blocking decision** exists in planning, use **`AskQuestion`** (Agent mode) instead of prose-only questions. +- If kickoff has zero questions, explicitly record why in the plan under a **Kickoff clarifications** section with evidence from Linear + repo context. +- **Do not commit** a kickoff plan until the clarification step above is complete. + ## 1. Load Linear context - Fetch the issue when possible (Linear MCP `get_issue` / `list_issues`, server **`plugin-linear-linear`**), or use a URL / pasted description the user provides. @@ -48,6 +55,7 @@ When the user starts work on a **Linear issue** (e.g. issue key `NEO-5`, phrases **Required sections** in that file (do **not** ship a plan that omits any of these): - Story reference (key, title, link if available) +- Kickoff clarifications (questions asked + answers, or explicit “No clarifications needed” with reason) - Goal, scope, and out-of-scope (from Linear) - Acceptance criteria checklist (from Linear) - Technical approach (concise) diff --git a/client/README.md b/client/README.md index 3d06e75..9833ce1 100644 --- a/client/README.md +++ b/client/README.md @@ -111,7 +111,8 @@ Full checklist: [`docs/manual-qa/NEO-25.md`](../manual-qa/NEO-25.md). - **`TargetSelectionClient`** emits **`selection_event(event: Dictionary)`** only when the server-acknowledged **`lockedTargetId`** changes (not on **`validity`-only** updates; those stay on **`target_state_changed`**). - Payload keys: **`previous`** ([String] or `null`), **`next`** (same), **`cause`** (`tab` \| `clear` \| `server_correction`), **`sequence`** (int from the new state). **`POST …/target/select`** from **`request_select_target_id`** (including the path used by Tab) uses cause **`tab`**; **`request_clear_target`** uses **`clear`**; every **`GET …/target`** completion uses **`server_correction`** (including boot sync). -- **Dev logging:** enable **`log_selection_events`** on the `TargetSelectionClient` node to mirror each event to the Godot **Output** (`print`). +- **Slice 3 telemetry hook (NEO-27):** this selection transition maps to product event name **`target_changed`**; with **`log_selection_events`** enabled, Godot Output prints the `target_changed` token for manual verification. **TODO(E9.M1):** replace dev log with cataloged telemetry emit. +- **Ability telemetry reserves (NEO-27):** `scripts/main.gd` documents future hook sites for **`ability_cast_requested`** / **`ability_cast_denied`** (implemented in E1.M4 + E5.M1, not in this story). - **E1.M4+:** connect to **`$TargetSelectionClient.selection_event`** (or your scene’s path to that node) without reshaping the payload. Full checklist: [`docs/manual-qa/NEO-26.md`](../docs/manual-qa/NEO-26.md). diff --git a/client/scripts/main.gd b/client/scripts/main.gd index 09a3d71..fe24e70 100644 --- a/client/scripts/main.gd +++ b/client/scripts/main.gd @@ -200,6 +200,11 @@ func _on_authoritative_position(world: Vector3, apply_as_snap: bool) -> void: ## surface client-vs-server divergence. This is the same signal `TargetSelectionClient` ## hooks for movement-driven lock refresh — we do not snap the capsule to this value ## (that is `authoritative_position_received`'s job on boot + move rejection). +## +## NEO-27 telemetry reserve (input/cast path not implemented in E1.M3): +## - `ability_cast_requested` hook will attach in E1.M4 input wiring before cast submit. +## - `ability_cast_denied` hook will attach on cast-response denial (`reasonCode`) in E1.M4+E5.M1. +## TODO(E9.M1): map both to the telemetry schema/catalog once available. func _on_authoritative_ack_for_hud(world: Vector3) -> void: _last_ack_world = world _have_last_ack = true diff --git a/client/scripts/target_selection_client.gd b/client/scripts/target_selection_client.gd index b6d85f2..44d0578 100644 --- a/client/scripts/target_selection_client.gd +++ b/client/scripts/target_selection_client.gd @@ -26,6 +26,8 @@ signal target_state_changed(state: Dictionary) ## [code]cause[/code] ([code]"tab"[/code] | [code]"clear"[/code] | ## [code]"server_correction"[/code]), [code]sequence[/code] ([int], from new state). ## E1.M4+ may [code]connect[/code] here without reshaping. +## NEO-27 telemetry hook: this transition maps to product event name [code]target_changed[/code] +## (TODO(E9.M1): wire schema/catalog and ingest once telemetry contracts land). signal selection_event(event: Dictionary) enum Phase { IDLE, GET, POST_SELECT } @@ -351,4 +353,6 @@ func _maybe_emit_selection_event( } selection_event.emit(ev) if log_selection_events: - print("[TargetSelectionClient] SelectionEvent ", ev) + # NEO-27 telemetry hook site: `target_changed` mirrors this payload shape. + # TODO(E9.M1): replace dev print with cataloged telemetry emit. + print("[TargetSelectionClient] target_changed ", ev) diff --git a/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md b/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md index 04e6f6b..f2f56b5 100644 --- a/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md +++ b/docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md @@ -100,7 +100,7 @@ flowchart LR ## Implementation snapshot -- **`TargetState` (prototype JSON v1 — NEO-23):** server **`GET /game/players/{id}/target`** and **`POST /game/players/{id}/target/select`** with versioned **`PlayerTargetStateResponse`** / **`TargetSelectRequest`** / **`TargetSelectResponse`**; stub registry + in-memory lock under `server/NeonSprawl.Server/Game/Targeting/`; horizontal reach + soft lock semantics — [NEO-23](../../plans/NEO-23-implementation-plan.md), [server README — Targeting](../../../server/README.md#targeting-neo-23). Godot tab-target: [NEO-24](https://linear.app/neon-sprawl/issue/NEO-24). **`InteractableDescriptor` list:** **`GET /game/world/interactables`** (NEO-25). **`SelectionEvent` (prototype):** Godot **`TargetSelectionClient.selection_event`** when **`lockedTargetId`** changes — [NEO-26](../../plans/NEO-26-implementation-plan.md). **Story backlog:** [E1M3 prototype backlog](../../plans/E1M3-prototype-backlog.md). +- **`TargetState` (prototype JSON v1 — NEO-23):** server **`GET /game/players/{id}/target`** and **`POST /game/players/{id}/target/select`** with versioned **`PlayerTargetStateResponse`** / **`TargetSelectRequest`** / **`TargetSelectResponse`**; stub registry + in-memory lock under `server/NeonSprawl.Server/Game/Targeting/`; horizontal reach + soft lock semantics — [NEO-23](../../plans/NEO-23-implementation-plan.md), [server README — Targeting](../../../server/README.md#targeting-neo-23). Godot tab-target: [NEO-24](https://linear.app/neon-sprawl/issue/NEO-24). **`InteractableDescriptor` list:** **`GET /game/world/interactables`** (NEO-25). **`SelectionEvent` (prototype):** Godot **`TargetSelectionClient.selection_event`** when **`lockedTargetId`** changes — [NEO-26](../../plans/NEO-26-implementation-plan.md). **NEO-27 hook mapping:** `selection_event` maps to Slice 3 telemetry name **`target_changed`** (dev log token + TODO(E9.M1) in `client/scripts/target_selection_client.gd`); server lock mutation hook comments live in `server/NeonSprawl.Server/Game/Targeting/InMemoryPlayerTargetLockStore.cs`; ability hook reserves (`ability_cast_requested` / `ability_cast_denied`) are documented in `client/scripts/main.gd` pending E1.M4 + E5.M1 — [NEO-27](../../plans/NEO-27-implementation-plan.md). **Story backlog:** [E1M3 prototype backlog](../../plans/E1M3-prototype-backlog.md). - **Precursor under E1.M1 (NEO-9 + NEO-25):** server **`POST /game/players/{id}/interact`** with **`InteractionRequest`** / **`InteractionResponse`**; **`GET /game/world/interactables`** (versioned descriptor list); **`HorizontalReach`** (`server/NeonSprawl.Server/Game/World/HorizontalReach.cs`); prototype registry under `server/NeonSprawl.Server/Game/Interaction/`; client **`interactables_catalog_client.gd`**, **`interactable_world_builder.gd`**, **`interaction_request_client.gd`**, **`interaction_radius_indicators.gd`** — see [NEO-9](../../plans/NEO-9-implementation-plan.md), [NEO-25](../../plans/NEO-25-implementation-plan.md), and [server README — Interaction](../../../server/README.md#interaction-neo-9). - **Alignment:** [Documentation and implementation alignment](documentation_and_implementation_alignment.md). @@ -110,7 +110,7 @@ flowchart LR - **Occluders vs truth:** camera occlusion and pick-through ([NEO-20](https://linear.app/neon-sprawl/issue/NEO-20)) affect **presentation** and click-to-move; **server** eligibility must not depend on “what the camera showed.” - **Lag compensation** for tab-target: deferred per [client vs server authority](client_server_authority.md#what-this-doc-does-not-fix-yet); decide with combat design when E5.M1 networking MVP is scoped. -**Telemetry (Slice 3):** `target_changed`, `ability_cast_requested`, `ability_cast_denied` — **TODO(E9.M1)** until event schema exists. +**Telemetry (Slice 3):** `target_changed`, `ability_cast_requested`, `ability_cast_denied` hook sites are documented in client/server code (NEO-27); **TODO(E9.M1)** until event schema/catalog and ingest wiring exist. ## Linear backlog diff --git a/docs/decomposition/modules/documentation_and_implementation_alignment.md b/docs/decomposition/modules/documentation_and_implementation_alignment.md index ac523a9..dd85978 100644 --- a/docs/decomposition/modules/documentation_and_implementation_alignment.md +++ b/docs/decomposition/modules/documentation_and_implementation_alignment.md @@ -48,7 +48,7 @@ Rows appear when work starts; default for unlisted modules is **Planned** / not |--------|-----------------|----------|-------------------| | E1.M1 | Ready | Prototype milestone **Done** ([E1.M1](https://linear.app/neon-sprawl/project/e1m1-inputandmovementruntime-20eb28dd3db4)). Authoritative `PositionState` + **MoveCommand** over HTTP (JSON v1 snap); **in-memory** store by default, **Postgres** when configured ([NEO-8](../../plans/NEO-8-implementation-plan.md)); shared **NpgsqlDataSource** disposed on host shutdown ([NEO-13](../../plans/NEO-13-implementation-plan.md)); Godot sync + path-follow ([NEO-7](../../plans/NEO-7-implementation-plan.md), [NEO-11](../../plans/NEO-11-implementation-plan.md)); **InteractionRequest** + horizontal range ([NEO-9](../../plans/NEO-9-implementation-plan.md)). Follow-on: prediction/reconciliation, Slice 1 telemetry, Protobuf wire per [contracts.md](contracts.md). | [NEO-6](../../plans/NEO-6-implementation-plan.md), [NEO-7](../../plans/NEO-7-implementation-plan.md), [NEO-8](../../plans/NEO-8-implementation-plan.md), [NEO-9](../../plans/NEO-9-implementation-plan.md), [NEO-10](../../plans/NEO-10-implementation-plan.md), [NEO-11](../../plans/NEO-11-implementation-plan.md), [NEO-13](../../plans/NEO-13-implementation-plan.md); `server/NeonSprawl.Server/Game/PositionState/`, `Game/Interaction/`; [server README](../../../server/README.md) | | E1.M2 | Ready | **Slice 2 prototype slice closed:** follow + `CameraState` ([NEO-15](https://linear.app/neon-sprawl/issue/NEO-15)); zoom bands ([NEO-16](https://linear.app/neon-sprawl/issue/NEO-16)); occlusion ([NEO-17](https://linear.app/neon-sprawl/issue/NEO-17)); occluder pick-through ([NEO-20](https://linear.app/neon-sprawl/issue/NEO-20)); contracts + hardening ([NEO-18](https://linear.app/neon-sprawl/issue/NEO-18)). Client-local; no server use of camera pose. | [NEO-15](../../plans/NEO-15-implementation-plan.md), [NEO-16](../../plans/NEO-16-implementation-plan.md), [NEO-17](../../plans/NEO-17-implementation-plan.md), [NEO-18](../../plans/NEO-18-implementation-plan.md), [NEO-20](../../plans/NEO-20-implementation-plan.md); `client/scripts/isometric_follow_camera.gd`, `camera_state.gd`, `zoom_band_config.gd`, `occlusion_policy.gd`, `ground_pick.gd`; [E1_M2_IsometricCameraController.md](E1_M2_IsometricCameraController.md) | -| E1.M3 | In Progress | **NEO-23 landed:** JSON v1 targeting read + select (`GET`/`POST …/target`, `Game/Targeting/`, [NEO-23](../../plans/NEO-23-implementation-plan.md)) — `PlayerTargetStateResponse` / soft lock / `reasonCode` denials; wire name differs from illustrative **`TargetState`** in module doc (called out in plan + README). **NEO-24 landed:** client tab-target + lock HUD synced to server ([NEO-24](../../plans/NEO-24-implementation-plan.md)) — `TargetSelectionClient` ([`client/scripts/target_selection_client.gd`](../../../client/scripts/target_selection_client.gd)), Tab / Esc bindings, `TargetLockLabel` HUD, hybrid movement-triggered refresh via new `PositionAuthorityClient.authoritative_ack` signal (fires on every server-confirmed position, boot + `move-stream` 200) with a 250 ms cooldown; manual QA in [`docs/manual-qa/NEO-24.md`](../../manual-qa/NEO-24.md). **NEO-25 landed:** versioned **`GET /game/world/interactables`** ([NEO-25](../../plans/NEO-25-implementation-plan.md)) — `InteractablesListResponse` / `InteractablesWorldApi` in `server/NeonSprawl.Server/Game/Interaction/`; Godot `interactables_catalog_client.gd` + `interactable_world_builder.gd` (fetch-driven props + glow); [server README — Interactable descriptors (NEO-25)](../../../server/README.md#interactable-descriptors-neo-25). **NEO-26 landed:** prototype **`SelectionEvent`** — **`TargetSelectionClient.selection_event`** ([NEO-26](../../plans/NEO-26-implementation-plan.md)) when **`lockedTargetId`** changes; optional **`log_selection_events`**. **Follow-on / still open:** richer **`InteractableDescriptor`** consumers beyond list projection + existing `POST …/interact`, Slice 3 telemetry (see [E1M3 prototype backlog](../../plans/E1M3-prototype-backlog.md)). **Precursor (E1.M1):** [NEO-9](../../plans/NEO-9-implementation-plan.md) `POST …/interact`. | Linear [NEO-24](https://linear.app/neon-sprawl/issue/NEO-24)–[NEO-27](https://linear.app/neon-sprawl/issue/NEO-27); [E1_M3_InteractionAndTargetingLayer.md](E1_M3_InteractionAndTargetingLayer.md); [E1M3 prototype backlog](../../plans/E1M3-prototype-backlog.md); [server README — Targeting](../../../server/README.md#targeting-neo-23), [Interactable descriptors (NEO-25)](../../../server/README.md#interactable-descriptors-neo-25), [Interaction](../../../server/README.md#interaction-neo-9) | +| E1.M3 | In Progress | **NEO-23 landed:** JSON v1 targeting read + select (`GET`/`POST …/target`, `Game/Targeting/`, [NEO-23](../../plans/NEO-23-implementation-plan.md)) — `PlayerTargetStateResponse` / soft lock / `reasonCode` denials; wire name differs from illustrative **`TargetState`** in module doc (called out in plan + README). **NEO-24 landed:** client tab-target + lock HUD synced to server ([NEO-24](../../plans/NEO-24-implementation-plan.md)) — `TargetSelectionClient` ([`client/scripts/target_selection_client.gd`](../../../client/scripts/target_selection_client.gd)), Tab / Esc bindings, `TargetLockLabel` HUD, hybrid movement-triggered refresh via new `PositionAuthorityClient.authoritative_ack` signal (fires on every server-confirmed position, boot + `move-stream` 200) with a 250 ms cooldown; manual QA in [`docs/manual-qa/NEO-24.md`](../../manual-qa/NEO-24.md). **NEO-25 landed:** versioned **`GET /game/world/interactables`** ([NEO-25](../../plans/NEO-25-implementation-plan.md)) — `InteractablesListResponse` / `InteractablesWorldApi` in `server/NeonSprawl.Server/Game/Interaction/`; Godot `interactables_catalog_client.gd` + `interactable_world_builder.gd` (fetch-driven props + glow); [server README — Interactable descriptors (NEO-25)](../../../server/README.md#interactable-descriptors-neo-25). **NEO-26 landed:** prototype **`SelectionEvent`** — **`TargetSelectionClient.selection_event`** ([NEO-26](../../plans/NEO-26-implementation-plan.md)) when **`lockedTargetId`** changes; optional **`log_selection_events`**. **NEO-27 landed:** Slice 3 telemetry hook sites documented — `selection_event` maps to product `target_changed` in `target_selection_client.gd`; server lock transition hook comments in `InMemoryPlayerTargetLockStore`; reserved `ability_cast_requested` / `ability_cast_denied` comments in `client/scripts/main.gd` (all TODO(E9.M1)); see [NEO-27](../../plans/NEO-27-implementation-plan.md) and [`docs/manual-qa/NEO-27.md`](../../manual-qa/NEO-27.md). **Follow-on / still open:** richer **`InteractableDescriptor`** consumers beyond list projection + existing `POST …/interact`; production telemetry ingest/catalog after E9.M1. **Precursor (E1.M1):** [NEO-9](../../plans/NEO-9-implementation-plan.md) `POST …/interact`. | Linear [NEO-24](https://linear.app/neon-sprawl/issue/NEO-24)–[NEO-27](https://linear.app/neon-sprawl/issue/NEO-27); [E1_M3_InteractionAndTargetingLayer.md](E1_M3_InteractionAndTargetingLayer.md); [E1M3 prototype backlog](../../plans/E1M3-prototype-backlog.md); [server README — Targeting](../../../server/README.md#targeting-neo-23), [Interactable descriptors (NEO-25)](../../../server/README.md#interactable-descriptors-neo-25), [Interaction](../../../server/README.md#interaction-neo-9) | --- diff --git a/docs/manual-qa/NEO-27.md b/docs/manual-qa/NEO-27.md new file mode 100644 index 0000000..eef6f3b --- /dev/null +++ b/docs/manual-qa/NEO-27.md @@ -0,0 +1,32 @@ +# NEO-27 — Manual QA checklist + +Story: [NEO-27](https://linear.app/neon-sprawl/issue/NEO-27/e1m3-slice-3-telemetry-hook-sites-target-changed) +Plan: [`docs/plans/NEO-27-implementation-plan.md`](../plans/NEO-27-implementation-plan.md) + +## Preconditions + +- Game server running (`server/NeonSprawl.Server`). +- Godot client opens `client/project.godot` and runs `scenes/main.tscn`. +- In the scene, `TargetSelectionClient.log_selection_events` is enabled (`true`). + +## Checks + +- [ ] **`target_changed` dev token appears on lock transition** + - Press `Tab` to acquire a target lock or switch lock ids. + - Verify Godot Output prints a line prefixed with `[TargetSelectionClient] target_changed`. + - Confirm payload includes `previous`, `next`, `cause`, and `sequence`. + +- [ ] **No `target_changed` log on validity-only updates** + - Hold a lock, move to force `validity` changes (`ok` ↔ `out_of_range`) without lock-id change. + - Verify `target_state_changed` behavior remains, and no new `target_changed` log is printed for id-unchanged refreshes. + +- [ ] **Ability telemetry reserves are documented (not implemented)** + - Confirm comment block exists in `client/scripts/main.gd` naming `ability_cast_requested` and `ability_cast_denied`. + - Confirm comments include `TODO(E9.M1)` and reference E1.M4/E5.M1 as future wiring points. + +## Expected outcome + +- Slice 3 telemetry hook names are explicitly present in code/docs: + - Active hook mapping: `target_changed`. + - Reserved hook names: `ability_cast_requested`, `ability_cast_denied`. +- No production telemetry pipeline is introduced in this story. diff --git a/docs/plans/NEO-27-implementation-plan.md b/docs/plans/NEO-27-implementation-plan.md new file mode 100644 index 0000000..0075f00 --- /dev/null +++ b/docs/plans/NEO-27-implementation-plan.md @@ -0,0 +1,88 @@ +# NEO-27 — Implementation plan + +## Story reference + +| Field | Value | +|--------|--------| +| **Key** | NEO-27 | +| **Title** | E1.M3: Slice 3 telemetry hook sites (`target_changed`, …) | +| **Linear** | [NEO-27](https://linear.app/neon-sprawl/issue/NEO-27/e1m3-slice-3-telemetry-hook-sites-target-changed) | +| **Slug** | E1M3-05 | +| **Git branch** | `NEO-27-e1m3-slice-3-telemetry-hook-sites` | +| **Parent context** | [Epic 1 — Core Player Runtime](https://linear.app/neon-sprawl/project/epic-1-core-player-runtime-client-controls-character-loop-66bd590cd016) · [E1M3 prototype backlog](E1M3-prototype-backlog.md) | +| **Decomposition** | [Epic 1 Slice 3 — telemetry hooks](../decomposition/epics/epic_01_core_player_runtime.md#epic-1-slice-3); [E1.M3 — InteractionAndTargetingLayer](../decomposition/modules/E1_M3_InteractionAndTargetingLayer.md) | + +## Kickoff clarifications + +- **Q1 (resolved):** Where should reserved `ability_cast_requested` / `ability_cast_denied` hook comments live for this story? +- **Answer:** Keep them in **`client/scripts/main.gd`** (no extra placeholder script in NEO-27). +- **Why no additional blocking questions:** Event names, scope, and out-of-scope were explicit in Linear + backlog docs; this was the only implementation-location decision not already settled. + +## Goal, scope, and out-of-scope + +**Goal:** Establish **documented hook sites** for Epic 1 Slice 3 product telemetry names: **`target_changed`** (wired to real selection transitions), plus **reserved** (no-op / comment-only) sites for **`ability_cast_requested`** and **`ability_cast_denied`** until [E1.M4](../decomposition/modules/E1_M4_AbilityInputScaffold.md) + [E5.M1](../decomposition/modules/E5_M1_CombatRulesEngine.md). All real ingest waits on **`TODO(E9.M1)`** per [E9.M1 — TelemetryEventSchema](../decomposition/modules/E9_M1_TelemetryEventSchema.md). + +**In scope** + +- **Event names** in code or doc comments matching [epic Slice 3](../decomposition/epics/epic_01_core_player_runtime.md#epic-1-slice-3) (`target_changed`, `ability_cast_requested`, `ability_cast_denied`). +- **`TODO(E9.M1)`** at each hook site until a catalog exists. +- **Optional dev logging** when a flag is enabled (reuse or extend the NEO-26 `log_selection_events` pattern on the client; optional `ILogger` / `Debug.WriteLine` guard on server only if we add a clearly dev-gated path—prefer comments + single optional trace line consistent with repo norms). +- **`documentation_and_implementation_alignment.md`:** extend the **E1.M3** snapshot row to mention NEO-27 hook sites (per Linear acceptance; NEO-23 is already on `main`). + +**Out of scope** + +- Production ingest, dashboards, OpenTelemetry. +- Changing `TargetState` / HTTP contracts (NEO-23). +- Implementing real ability cast requests (E1.M4). + +## Acceptance criteria checklist + +- [ ] **Documented event names** in-repo matching Slice 3: `target_changed`, `ability_cast_requested`, `ability_cast_denied` (latter two may be comment-only reserves). +- [ ] **`TODO(E9.M1)`** at each hook site referencing schema work. +- [ ] **Optional dev logging** for `target_changed` when a documented flag is on (or explicitly documented that an existing flag covers it, with log line including the product event name). +- [ ] **`documentation_and_implementation_alignment.md`** E1.M3 row updated for NEO-27. + +## Technical approach + +1. **`target_changed` (client)** — Canonical prototype mirror: when **`TargetSelectionClient`** emits **`selection_event`** (NEO-26), the product telemetry name is **`target_changed`** (same transition: normalized `lockedTargetId` change, with `cause` / `sequence` carrying intent). Add a short class-level or method-level note on **`_maybe_emit_selection_event`** linking **`selection_event`** → **`target_changed`**. Optionally prefix dev **`print`** (when `log_selection_events` is true) with a literal `target_changed` token so grep and QA are unambiguous. + +2. **`target_changed` (server)** — Authoritative lock id transitions occur in **`InMemoryPlayerTargetLockStore.ApplySet`** / **`ApplyClear`** when the stored lock id actually changes (sequence bumps). Add **`//` / `///` comments** (and `TODO(E9.M1)`) at those mutation success paths as the **server-side hook site** for `target_changed`. Rationale: single choke point; HTTP handlers stay thin. + +3. **`ability_cast_requested` / `ability_cast_denied` (reserve)** — No hotbar or cast route exists yet. Add a compact **comment block** in **`client/scripts/main.gd`** (or the first file E1.M4 will extend for input, if we prefer—**Decision:** `main.gd` next to other prototype wiring) listing the two event names and pointing to E1.M4 / E5.M1 + E9.M1. Optionally mirror a one-line reserve in **`TargetingApi.cs`** near denial responses noting that **`ability_cast_denied`** (with `reasonCode`) will attach to a **future cast POST**, not the current target-select deny path—avoids confusion with selection denials. + +4. **Docs alignment** — Append to the E1.M3 **Snapshot** cell: NEO-27 documents Slice 3 telemetry hook sites; link this plan. + +## Files to add + +| Path | Rationale | +|------|-----------| +| `docs/manual-qa/NEO-27.md` | Ticket-level manual verification checklist for Slice 3 telemetry hook-site behavior and expectations. | + +## Files to modify + +| Path | Rationale | +|------|-----------| +| `client/scripts/target_selection_client.gd` | Document `target_changed` ↔ `selection_event`; optional dev log prefix; `TODO(E9.M1)`. | +| `server/NeonSprawl.Server/Game/Targeting/InMemoryPlayerTargetLockStore.cs` | Server authoritative `target_changed` hook site on lock id transitions. | +| `client/scripts/main.gd` | Reserved comment block for `ability_cast_requested` / `ability_cast_denied` (E1.M4 + E5.M1). | +| `server/NeonSprawl.Server/Game/Targeting/TargetingApi.cs` | Optional one-line reserve clarifying cast denials vs target-select denials (avoids mis-mapping event names). | +| `client/README.md` | Short “Slice 3 telemetry (NEO-27)” pointer next to SelectionEvent section. | +| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | E1.M3 snapshot: NEO-27 telemetry hook sites landed (per team rule). | +| `docs/decomposition/modules/E1_M3_InteractionAndTargetingLayer.md` | Optional one-line under telemetry: code hook pointers (`target_selection_client.gd`, lock store)—only if the module table still says hooks are TODO-only; keep register alignment. | +| `docs/plans/NEO-27-implementation-plan.md` | Keep kickoff clarifications and resolved decisions synchronized with actual implementation choices. | + +## Tests + +| File | Action | +|------|--------| +| `client/test/selection_event_client_test.gd` | **Change only if** new observable behavior is added (e.g. new export or signal). If implementation is comments + optional `print` format only, **no test change** — manual QA: enable `log_selection_events`, tab/clear, confirm output contains `target_changed`. | +| `docs/manual-qa/NEO-27.md` | Add explicit manual checks for `target_changed` log token, id-change-only emission behavior, and ability telemetry reserve documentation. | + +**Server:** No new tests required for comment-only / dev-trace placeholders unless we introduce a testable abstraction (out of scope). + +## Open questions / risks + +**Resolved (2026-04-26):** Linear no longer lists **NEO-24** as blocking NEO-27 (dependency removed on board). +**Resolved (2026-04-26):** Keep ability telemetry reserve comments in **`client/scripts/main.gd`** for NEO-27; no placeholder script yet. + +**None** otherwise. diff --git a/server/NeonSprawl.Server/Game/Targeting/InMemoryPlayerTargetLockStore.cs b/server/NeonSprawl.Server/Game/Targeting/InMemoryPlayerTargetLockStore.cs index 1926eae..894de55 100644 --- a/server/NeonSprawl.Server/Game/Targeting/InMemoryPlayerTargetLockStore.cs +++ b/server/NeonSprawl.Server/Game/Targeting/InMemoryPlayerTargetLockStore.cs @@ -44,6 +44,8 @@ public sealed class InMemoryPlayerTargetLockStore : IPlayerTargetLockStore var next = new PlayerLockRow(null, prev.Sequence + 1); rows[key] = next; + // NEO-27 telemetry hook site: `target_changed` fires when lock id transitions. + // TODO(E9.M1): emit cataloged telemetry event (player id, previous/next lock, cause=clear). return (null, next.Sequence); } } @@ -67,6 +69,8 @@ public sealed class InMemoryPlayerTargetLockStore : IPlayerTargetLockStore var next = new PlayerLockRow(targetIdLowercase, prev.Sequence + 1); rows[key] = next; + // NEO-27 telemetry hook site: `target_changed` fires when lock id transitions. + // TODO(E9.M1): emit cataloged telemetry event (player id, previous/next lock, cause=tab/select). return (next.LockIdLowercase, next.Sequence); } } diff --git a/server/NeonSprawl.Server/Game/Targeting/TargetingApi.cs b/server/NeonSprawl.Server/Game/Targeting/TargetingApi.cs index 172c2bc..49020df 100644 --- a/server/NeonSprawl.Server/Game/Targeting/TargetingApi.cs +++ b/server/NeonSprawl.Server/Game/Targeting/TargetingApi.cs @@ -6,6 +6,9 @@ namespace NeonSprawl.Server.Game.Targeting; /// Maps GET/POST …/target selection APIs (NEO-23). public static class TargetingApi { + // NEO-27 note: these are target-selection deny reasons, not cast telemetry events. + // Future ability flow (E1.M4 + E5.M1) will hook `ability_cast_denied` on cast endpoints. + // TODO(E9.M1): map deny reason telemetry to cataloged event schema. public const string ReasonUnknownTarget = "unknown_target"; public const string ReasonOutOfRange = "out_of_range";