SoundBlaster · SoundBlaster · Mar 10, 2026 · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -6,6 +6,7 @@
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P1-T13 | [P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/](P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/) | 2026-03-10 | PASS |
 | P2-T8 | [P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/](P2-T8_Gate_broker_tools_list_on_warmed_tool_catalog/) | 2026-03-10 | PASS |
 | P8-T1 | [P8-T1_Release_version_0.4.2_to_PyPI_and_MCP_Registry/](P8-T1_Release_version_0.4.2_to_PyPI_and_MCP_Registry/) | 2026-03-07 | PASS |
 | P7-T5 | [P7-T5_Document_broker_UX/](P7-T5_Document_broker_UX/) | 2026-03-07 | PASS |
@@ -206,6 +207,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_p1_t13_editable_install_troubleshooting.md](_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md) | Review report for P1-T13 |
 | [REVIEW_p2_t8_tools_catalog_gate.md](_Historical/REVIEW_p2_t8_tools_catalog_gate.md) | Review report for P2-T8 |
 | [REVIEW_broker_ux_docs.md](_Historical/REVIEW_broker_ux_docs.md) | Review report for P7-T5 |
 | [REVIEW_tui_local_status_fallback.md](P7-T4_Add_direct_local-status_fallback_for_TUI_when_dashboard_API_is_unavailable/REVIEW_tui_local_status_fallback.md) | Review report for P7-T4 |
@@ -640,3 +642,5 @@
 | 2026-03-07 | P7-T3 | Archived REVIEW_dashboard_port_ownership_conflicts report |
 | 2026-03-10 | P2-T8 | Archived Gate_broker_tools_list_on_warmed_tool_catalog (PASS) |
 | 2026-03-10 | P2-T8 | Archived REVIEW_p2_t8_tools_catalog_gate report |
+| 2026-03-10 | P1-T13 | Archived Document_stale_editable_install_version_mismatch_in_troubleshooting_guide (PASS) |
+| 2026-03-10 | P1-T13 | Archived REVIEW_p1_t13_editable_install_troubleshooting report |
diff --git a/...13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md b/...13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md
@@ -0,0 +1,53 @@
+# PRD: P1-T13 — Document stale editable install version mismatch in troubleshooting guide
+
+## Status
+
+In Progress
+
+## Problem
+
+When a developer works in the local repository with `.venv` activated (or with `.venv/bin` on PATH), the `mcpbridge-wrapper` command resolves to the editable install inside `.venv`. The version metadata for that install is recorded in `.venv/lib/pythonX.Y/site-packages/mcpbridge_wrapper-{VERSION}.dist-info/` at the time `pip install -e .` was last run.
+
+If `pyproject.toml` is subsequently bumped to a new version (e.g. `0.4.1` → `0.4.2`) without re-running `pip install -e .`, the dist-info still reports the old version. As a result:
+
+- `mcpbridge-wrapper --doctor` shows `Package Version: 0.4.1`
+- A broker daemon started via `uvx --from mcpbridge-wrapper` (which fetches fresh from PyPI) writes version `0.4.2` to `broker.version`
+- `--doctor` detects a "version mismatch" and prompts the user to restart the broker
+- The user is confused: they just released `0.4.2`, but their own dev environment reports `0.4.1`
+
+This is a pure developer environment issue — end users on `uvx` are never affected — but it can trap contributors and maintainers who have the repo `.venv` active in their shell.
+
+## Deliverables
+
+1. **`docs/troubleshooting.md`** — new section under a "Development / Local Repository" heading (or appended to an existing relevant section) that:
+   - Names the symptom: `--doctor` reports a version mismatch between local binary (`0.4.N`) and broker (`0.4.N+1`)
+   - Explains the root cause: stale `dist-info` from an old `pip install -e .` after `pyproject.toml` was bumped
+   - Provides the one-line fix: `.venv/bin/pip install -e .` (or `pip install -e .` with venv active)
+   - Notes that `uvx` always fetches the latest PyPI release independently of the local `.venv`
+
+2. **`Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`** — DocC mirror synced to match the new section.
+
+## Acceptance Criteria
+
+- [ ] `docs/troubleshooting.md` describes the symptom, root cause (stale editable dist-info), and the fix (`pip install -e .`)
+- [ ] The entry explains that `uvx` fetches from PyPI independently of the `.venv` editable install
+- [ ] DocC mirror updated to match
+- [ ] `make doccheck-all` passes (mirrors in sync)
+
+## Out of Scope
+
+- No code changes — documentation only
+- No changes to `--doctor` output format
+- End-user (non-dev) scenarios are already covered by existing version-mismatch entries
+
+## Dependencies
+
+None
+
+## Risk
+
+Low — documentation-only change.
+
+---
+**Archived:** 2026-03-10
+**Verdict:** PASS
diff --git a/...e_install_version_mismatch_in_troubleshooting_guide/P1-T13_Validation_Report.md b/...e_install_version_mismatch_in_troubleshooting_guide/P1-T13_Validation_Report.md
@@ -0,0 +1,38 @@
+# Validation Report: P1-T13
+
+## Task
+
+Document stale editable install version mismatch in troubleshooting guide
+
+## Date
+
+2026-03-10
+
+## Changes Made
+
+### `docs/troubleshooting.md`
+
+Added new entry `### "Package Version" shows old release after version bump (development environment)` before the "Debug Mode" section. The entry covers:
+
+- Symptom: `--doctor` version mismatch with old package version from `.venv` dist-info
+- Root cause: editable install dist-info is written at `pip install -e .` time, not at `pyproject.toml` bump time
+- Clarification: `uvx` fetches from PyPI independently of `.venv`
+- Fix: `.venv/bin/pip install -e .` to refresh dist-info
+
+### `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`
+
+Added matching section `## "Package Version" shows old release after version bump (development environment)` before the "Debug Mode" section. Content is condensed to DocC style (no client-specific sub-steps needed since this is a dev-only scenario).
+
+## Quality Gate Results
+
+| Gate | Result |
+|------|--------|
+| `pytest` | 902 passed, 5 skipped |
+| `ruff check src/` | All checks passed |
+| `mypy src/` | Success: no issues found in 20 source files |
+| `pytest --cov` | 91.55% (≥ 90% required) ✅ |
+| `make doccheck-all` | ✓ DocC documentation is in sync ✅ |
+
+## Verdict
+
+PASS
diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md
@@ -0,0 +1,39 @@
+## REVIEW REPORT — P1-T13 Editable Install Troubleshooting
+
+**Scope:** `origin/main..HEAD`
+**Files:** 7
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+
+- None.
+
+### Secondary Issues
+
+- None.
+
+### Architectural Notes
+
+- The new troubleshooting entry is scoped to development environments only, so it clarifies a
+  maintainer-facing mismatch without adding noise to the end-user recovery paths.
+- The DocC mirror remains aligned with `docs/troubleshooting.md`, preserving the repository's
+  documentation-sync contract and keeping `doccheck-all` meaningful.
+- Archiving updates correctly close the task lifecycle in `Workplan`, `next.md`, and the archive
+  index, so the FLOW state now matches the branch contents.
+
+### Tests
+
+- `pytest` — PASS (`902 passed, 5 skipped, 2 warnings`)
+- `ruff check src/` — PASS
+- `mypy src/` — PASS
+- `pytest --cov` — PASS (`91.55%`)
+- `make doccheck-all` — PASS
+
+### Next Steps
+
+- No actionable review findings. FOLLOW-UP is skipped.
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -15,6 +15,7 @@ task only after a follow-up or new workplan entry is created.
 
 ## Recently Archived
 
+- `2026-03-10` — `P1-T13` archived with verdict `PASS`
 - `2026-03-10` — `P2-T8` archived with verdict `PASS`
 - `2026-03-07` — `P8-T1` archived with verdict `PASS`
 - `2026-03-07` — `P7-T5` archived with verdict `PASS`

diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -186,6 +186,22 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - [x] `docs/troubleshooting.md` explains that inactive `mcpbridge-broker` entries in Xcode Agent Activity are usually historical sessions, not proof of multiple live brokers
   - [x] `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` mirrors the new guidance
 
+#### ✅ P1-T13: Document stale editable install version mismatch in troubleshooting guide
+- **Status:** ✅ Completed (2026-03-10)
+- **Description:** When developing locally, the `.venv` editable install records the package version at install time in its `dist-info` directory. If `pyproject.toml` is bumped to a new version without re-running `pip install -e .`, the `mcpbridge-wrapper` command in the dev PATH still reports the old version. This causes `--doctor` to show a version mismatch between the running broker (started via `uvx`, which fetches the latest from PyPI) and the local binary. Document this scenario, its cause, and the fix (`pip install -e .` or `.venv/bin/pip install -e .`) in `docs/troubleshooting.md` so developers can self-diagnose without manual inspection of dist-info directories.
+- **Priority:** P2
+- **Dependencies:** none
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - `docs/troubleshooting.md` — new entry under a "Development / Editable Install" section explaining the stale dist-info version mismatch and the fix
+  - `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` — DocC mirror synced
+  - `SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/` — archived PRD and validation report
+- **Acceptance Criteria:**
+  - [x] `docs/troubleshooting.md` describes the symptom (`--doctor` reports version mismatch, package version is old), the root cause (stale editable dist-info after `pyproject.toml` bump), and the fix (`pip install -e .`)
+  - [x] The entry clarifies that `uvx` always fetches the latest PyPI release while the `.venv` editable install reflects the version at the time of `pip install -e .`
+  - [x] DocC mirror (`Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`) is updated to match
+  - [x] `make doccheck-all` passes
+
 ### Phase 2: Broker Robustness
 
 #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md
@@ -623,6 +623,42 @@ PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/b
 2. Verify the wrapper process is running
 3. Restart the MCP client connection
 
+## "Package Version" shows old release after version bump (development environment)
+
+**Symptom:** You bumped `pyproject.toml` to a new version (for example `0.4.2`) and released to
+PyPI, but `--doctor` still reports the old version for the local binary:
+
+```
+Python Runtime
+- Package Version: 0.4.1        ← old version from .venv dist-info
+...
+Local Broker State
+- Recorded Daemon Version: 0.4.2  ← broker started via uvx, fetched latest from PyPI
+- Version Mismatch: yes (package 0.4.1)
+```
+
+**Cause:** The `mcpbridge-wrapper` command resolves to the editable install inside the repository
+`.venv`. Package version metadata is stored in
+`.venv/lib/pythonX.Y/site-packages/mcpbridge_wrapper-{VERSION}.dist-info/` and is written only
+when `pip install -e .` runs. Bumping `pyproject.toml` alone does not update the dist-info.
+
+Meanwhile `uvx --from mcpbridge-wrapper` always fetches the latest published release from PyPI
+independently of your local `.venv`, so the broker daemon writes the new version to
+`broker.version`. The mismatch is an artifact of the dev environment, not a real compatibility
+problem. End users running `uvx` are never affected.
+
+**Fix:**
+
+```bash
+# From the repository root, reinstall the editable package to refresh dist-info
+.venv/bin/pip install -e .
+
+# Verify the version now matches
+mcpbridge-wrapper --doctor | grep "Package Version"
+```
+
+---
+
 ## Debug Mode
 
 To see what's happening under the hood:

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -689,6 +689,54 @@ PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/b
 
 4. Run one MCP request and confirm direct mode is active (no broker file recreation).
 
+### "Package Version" shows old release after version bump (development environment)
+
+**Symptom:** You bumped `pyproject.toml` to a new version (for example `0.4.2`) and released to
+PyPI, but `--doctor` still reports the old version for the local binary:
+
+```
+Python Runtime
+- Package Version: 0.4.1        ← old version from .venv dist-info
+...
+Local Broker State
+- Recorded Daemon Version: 0.4.2  ← broker started via uvx, fetched latest from PyPI
+- Version Mismatch: yes (package 0.4.1)
+```
+
+**Cause:** The `mcpbridge-wrapper` command resolves to the editable install inside your repository
+`.venv`. Package version metadata is stored in
+`.venv/lib/pythonX.Y/site-packages/mcpbridge_wrapper-{VERSION}.dist-info/` and is written only
+when `pip install -e .` runs. Bumping `pyproject.toml` alone does not update the dist-info — so
+the installed binary still reports the version from the last `pip install -e .` invocation.
+
+Meanwhile `uvx --from mcpbridge-wrapper` always fetches the latest published release from PyPI
+independently of your local `.venv`, so the broker daemon it starts writes the new version to
+`broker.version`. The mismatch is an artifact of the dev environment, not a real compatibility
+problem.
+
+**Affected:** Repository contributors and maintainers with `.venv/bin` on their `PATH` or with
+the venv activated. End users running `uvx` are never affected.
+
+**Fix:**
+
+```bash
+# From the repository root, reinstall the editable package to refresh dist-info
+.venv/bin/pip install -e .
+
+# Verify the version now matches
+mcpbridge-wrapper --doctor | grep "Package Version"
+```
+
+Or, if you have the venv activated:
+
+```bash
+pip install -e .
+```
+
+After reinstalling, `--doctor` should show matching versions and no mismatch.
+
+---
+
 ## Debug Mode
 
 For verbose output, check the stderr stream: