diff --git a/docs/architecture/tech_stack.md b/docs/architecture/tech_stack.md index 18a8487..b91a7cb 100644 --- a/docs/architecture/tech_stack.md +++ b/docs/architecture/tech_stack.md @@ -116,3 +116,4 @@ Revisit this document if: - [`docs/decomposition/modules/pvp_combat_integration.md`](../decomposition/modules/pvp_combat_integration.md) — E5.M1 combat engine × E6.M1 PvP eligibility (single pipeline, deny reasons) - [`docs/decomposition/modules/quest_scope_and_party.md`](../decomposition/modules/quest_scope_and_party.md) — quest state per character, party credit, turn-in, instance deferral - [`docs/decomposition/modules/data_and_ops_policy.md`](../decomposition/modules/data_and_ops_policy.md) — content boot load vs dev reload, telemetry PII/sampling/retention, baseline events vs vision plan +- [`docs/decomposition/modules/documentation_and_implementation_alignment.md`](../decomposition/modules/documentation_and_implementation_alignment.md) — module register Status vs code, implementation tracking table diff --git a/docs/decomposition/README.md b/docs/decomposition/README.md index 9cbbad1..e142cf0 100644 --- a/docs/decomposition/README.md +++ b/docs/decomposition/README.md @@ -9,7 +9,7 @@ This workspace contains detailed planning artifacts derived from the finalized m ## Folder Layout - `epics/` - One file per epic with implementation slices. -- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. +- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [docs vs implementation](modules/documentation_and_implementation_alignment.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes. - `milestones/` - Phase-gated implementation tracks and pass/fail checklists. ## Working Rules diff --git a/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md index a7aa295..f1e6b43 100644 --- a/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md +++ b/docs/decomposition/modules/E1_M1_InputAndMovementRuntime.md @@ -7,7 +7,7 @@ | **Module ID** | E1.M1 | | **Epic** | [Epic 1 — Core Player Runtime](../epics/epic_01_core_player_runtime.md) | | **Stage target** | Prototype | -| **Status** | Planned (see [dependency register](module_dependency_register.md)) | +| **Status** | In Progress (see [dependency register](module_dependency_register.md); [implementation snapshot](#implementation-snapshot)) | ## Purpose @@ -31,6 +31,12 @@ Provides the foundational client/runtime path for character locomotion and world Contract readiness is tracked in the [module dependency register](module_dependency_register.md). +## Implementation snapshot + +- **Done (spike):** Server-side authoritative **read** API for `PositionState` (JSON over HTTP, versioned payload); in-memory store. See [NS-15 implementation plan](../../plans/NS-15-implementation-plan.md), `server/NeonSprawl.Server/Game/PositionState/`, and [server README — Position state](../../../server/README.md#position-state-ns-15). +- **Not yet:** `MoveCommand` ingestion, client sync, persistence, full movement loop per Epic 1 Slice 1. +- **Alignment:** [Documentation and implementation alignment](documentation_and_implementation_alignment.md). + ## Module dependencies - **None** — root of the player runtime stack. diff --git a/docs/decomposition/modules/contracts.md b/docs/decomposition/modules/contracts.md index d225271..5aaa499 100644 --- a/docs/decomposition/modules/contracts.md +++ b/docs/decomposition/modules/contracts.md @@ -83,6 +83,7 @@ A module’s register **Status** can move to **Ready** when the contracts it **e - [PvP and the combat engine](pvp_combat_integration.md) — E5.M1 gating with E6.M1, deny reasons - [Quest scope and party rules](quest_scope_and_party.md) — per-character quest state, party credit, turn-in - [Data reload and telemetry operations policy](data_and_ops_policy.md) — content reload, PII, sampling, retention, baseline events +- [Documentation and implementation alignment](documentation_and_implementation_alignment.md) — register Status vs repo, tracking table - [Module dependency register](module_dependency_register.md) - [Decomposition README](../README.md) diff --git a/docs/decomposition/modules/documentation_and_implementation_alignment.md b/docs/decomposition/modules/documentation_and_implementation_alignment.md new file mode 100644 index 0000000..7a24879 --- /dev/null +++ b/docs/decomposition/modules/documentation_and_implementation_alignment.md @@ -0,0 +1,55 @@ +# Documentation and implementation alignment + +The [module dependency register](module_dependency_register.md) **Status** column and each module’s summary table should **not silently disagree** with the repo. This doc defines how to keep decomposition docs truthful and where to record **partial** work. + +--- + +## Roles + +| Source | Role | +|--------|------| +| **Register + module markdown** | Intent, dependencies, contracts, policies (authority, PvP, quests, ops). | +| **Code + tests** | What actually runs; paths under `server/`, `client/`, etc. | +| **Plans** | `docs/plans/` (e.g. NS-* implementation plans) tie stories to acceptance criteria. | +| **This doc’s tracking table** | Quick **inventory** of modules that have started implementation; expand as work lands. | + +--- + +## Status column (register) + +| Status | Meaning | +|--------|---------| +| **Planned** | No meaningful implementation toward this module yet, or only unrelated spikes. | +| **In Progress** | At least one tracked story or code path exists toward the module; contracts may be partial. | +| **Ready** | Exported contracts meet [contracts.md](contracts.md) “Ready” guidance and dependents may integrate. | +| **Blocked** | Upstream module or external dependency prevents progress. | + +**Rule:** When a story merges that implements part of a module (API, store, schema), move that row from **Planned** to **In Progress** (or **Ready** when appropriate) in the same PR or a follow-up doc PR. + +**Partial modules** stay **In Progress** until the **prototype slice** for that module is satisfied or contracts are explicitly frozen for dependents. + +--- + +## Per-module docs + +Optional **`## Implementation snapshot`** (or a short bullet under Summary) on a module page: one paragraph + links to `docs/plans/…`, server paths, and [server README](../../../server/README.md) sections—avoid duplicating the full tracking table on every page. + +The **Summary** table **Status** field should match the register row for that module. + +--- + +## Implementation tracking table + +Rows appear when work starts; default for unlisted modules is **Planned** / not started. + + +| Module | Register status | Snapshot | Plans / pointers | +|--------|-----------------|----------|-------------------| +| E1.M1 | In Progress | Authoritative **read** `PositionState` over HTTP (JSON spike); in-memory store; no `MoveCommand` / client sync yet. | [NS-15 plan](../../plans/NS-15-implementation-plan.md); code: `server/NeonSprawl.Server/Game/PositionState/`; [server README — Position state](../../../server/README.md#position-state-ns-15) | + +--- + +## Related docs + +- [Module dependency register](module_dependency_register.md) +- [contracts.md](contracts.md) — versioning and Ready criteria diff --git a/docs/decomposition/modules/module_dependency_register.md b/docs/decomposition/modules/module_dependency_register.md index 2e2a830..3d4745e 100644 --- a/docs/decomposition/modules/module_dependency_register.md +++ b/docs/decomposition/modules/module_dependency_register.md @@ -2,7 +2,7 @@ Tracks cross-epic dependencies and contract readiness. Every **Depends On** module ID in this table has its own row (closed graph). -**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. **Quests × party:** **[Quest scope and party rules](quest_scope_and_party.md)**. **Data reload × telemetry ops:** **[Data reload and telemetry operations policy](data_and_ops_policy.md)**. +**Contract** means a stable boundary with a defined artifact (Protobuf wire message, JSON Schema content file, telemetry catalog entry, or server-internal type until promoted). See **[What a contract is](contracts.md)** for kinds, repo layout, and versioning. **Authority** (who owns `PositionState`, camera, combat outcomes): **[Client vs server authority](client_server_authority.md)**. **PvP × combat:** **[PvP and the combat engine](pvp_combat_integration.md)**. **Quests × party:** **[Quest scope and party rules](quest_scope_and_party.md)**. **Data reload × telemetry ops:** **[Data reload and telemetry operations policy](data_and_ops_policy.md)**. **Docs vs code:** **[Documentation and implementation alignment](documentation_and_implementation_alignment.md)**. Fleshed-out scope, contracts, and integration notes live in **per-module documents** (see [Per-module documentation](#per-module-documentation)). @@ -12,7 +12,7 @@ Fleshed-out scope, contracts, and integration notes live in **per-module documen | Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status | |---|---|---|---|---|---| -| E1.M1 | InputAndMovementRuntime | None | MoveCommand, PositionState, InteractionRequest | Prototype | Planned | +| E1.M1 | InputAndMovementRuntime | None | MoveCommand, PositionState, InteractionRequest | Prototype | In Progress | | E1.M2 | IsometricCameraController | E1.M1 | CameraState, ZoomBandConfig, OcclusionPolicy | Prototype | Planned | | E1.M3 | InteractionAndTargetingLayer | E1.M1 | TargetState, InteractableDescriptor, SelectionEvent | Prototype | Planned | | E1.M4 | AbilityInputScaffold | E1.M3, E5.M1 | AbilityCastRequest, HotbarLoadout, CooldownSnapshot | Prototype | Planned | @@ -148,7 +148,9 @@ Gameplay **content and curves** default to **boot load** with optional **dev-onl ## Status Legend -- Planned: identified but not implemented -- In Progress: currently being implemented -- Ready: contract stable and usable by dependents -- Blocked: dependency missing or unstable +- **Planned:** No meaningful implementation toward this module yet (see [documentation and implementation alignment](documentation_and_implementation_alignment.md)). +- **In Progress:** Partial implementation or active stories; contracts may be incomplete. +- **Ready:** Contract stable and usable by dependents ([contracts.md](contracts.md)). +- **Blocked:** Dependency missing or unstable. + +**Tracking table** (modules with code or plans in flight): [documentation_and_implementation_alignment.md — Implementation tracking table](documentation_and_implementation_alignment.md#implementation-tracking-table).