docs: documentation vs implementation alignment (#7)

Add documentation_and_implementation_alignment.md: register Status
semantics, Planned vs partial work, per-module snapshot guidance,
implementation tracking table (E1.M1 + NS-15).

Expand register Status legend; set E1.M1 to In Progress; E1.M1 module
doc Implementation snapshot and status. Link from contracts,
decomposition README, tech_stack.

Made-with: Cursor

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

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

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.

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)
 

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

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
+- **Planned:** No meaningful implementation toward this module yet (see [documentation and implementation alignment](documentation_and_implementation_alignment.md)).
-- In Progress: currently being implemented
+- **In Progress:** Partial implementation or active stories; contracts may be incomplete.
-- Ready: contract stable and usable by dependents
+- **Ready:** Contract stable and usable by dependents ([contracts.md](contracts.md)).
-- Blocked: dependency missing or unstable
+- **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).