From 07daf5d1f8092b03cd560a4cb4b1184cd0e558ea Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 7 Mar 2026 23:23:40 +0300 Subject: [PATCH 01/10] Branch for P1-T13: stale editable install troubleshooting doc --- SPECS/Workplan.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 6bcf58e..ba55451 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -186,6 +186,20 @@ 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 +- **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 +- **Acceptance Criteria:** + - [ ] `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 .`) + - [ ] 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 .` + - [ ] DocC mirror (`Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`) is updated to match + - [ ] `make doccheck-all` passes + ### Phase 2: Broker Robustness #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag From 1e45f0b017de21d5071f463b4d5e0cd1a0f2aecf Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 7 Mar 2026 23:24:08 +0300 Subject: [PATCH 02/10] Select task P1-T13: Document stale editable install version mismatch in troubleshooting guide --- SPECS/INPROGRESS/next.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 8d81c42..331f44d 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,17 +1,23 @@ -# Next Task: None +# Next Task: P1-T13 ## Selected Task -- No active task selected. +- **ID:** P1-T13 +- **Name:** Document stale editable install version mismatch in troubleshooting guide +- **Priority:** P2 +- **Branch:** `feature/P1-T13-stale-editable-install-troubleshooting` +- **Status:** In Progress ## Description -All tasks currently tracked in `SPECS/Workplan.md` are archived or completed. Select a new -task only after a follow-up or new workplan entry is created. +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 in `docs/troubleshooting.md` and sync the DocC mirror. ## Outputs -- None. +- `docs/troubleshooting.md` — new entry for stale editable install version mismatch +- `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` — DocC mirror synced ## Recently Archived From 5cd6683580e5061f56e8cbe999578f971466023e Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 7 Mar 2026 23:24:38 +0300 Subject: [PATCH 03/10] Plan task P1-T13: Document stale editable install version mismatch in troubleshooting guide --- ...rsion_mismatch_in_troubleshooting_guide.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 SPECS/INPROGRESS/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md diff --git a/SPECS/INPROGRESS/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md b/SPECS/INPROGRESS/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md new file mode 100644 index 0000000..1c31fa7 --- /dev/null +++ b/SPECS/INPROGRESS/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md @@ -0,0 +1,49 @@ +# 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. From cb6c5f42594e2286c120963751e5b916e221630f Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 7 Mar 2026 23:26:46 +0300 Subject: [PATCH 04/10] Implement P1-T13: add stale editable install version mismatch entry to troubleshooting docs --- SPECS/INPROGRESS/P1-T13_Validation_Report.md | 38 +++++++++++++++ .../Documentation.docc/Troubleshooting.md | 36 ++++++++++++++ docs/troubleshooting.md | 48 +++++++++++++++++++ 3 files changed, 122 insertions(+) create mode 100644 SPECS/INPROGRESS/P1-T13_Validation_Report.md diff --git a/SPECS/INPROGRESS/P1-T13_Validation_Report.md b/SPECS/INPROGRESS/P1-T13_Validation_Report.md new file mode 100644 index 0000000..b34faa2 --- /dev/null +++ b/SPECS/INPROGRESS/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-07 + +## 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` | 898 passed, 5 skipped | +| `ruff check src/` | All checks passed | +| `mypy src/` | Not configured (skipped per project convention) | +| `pytest --cov` | 91.75% (≥ 90% required) ✅ | +| `make doccheck-all` | ✓ DocC documentation is in sync ✅ | + +## Verdict + +PASS diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 050f300..0474ad4 100644 --- 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 artefact 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 index e2f0c08..96eff56 100644 --- 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 artefact 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: From 7cd3a60eb72abd4a86eaef260428d856a203925b Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 10 Mar 2026 02:47:26 +0300 Subject: [PATCH 05/10] Archive task P1-T13: Document_stale_editable_install_version_mismatch_in_troubleshooting_guide (PASS) --- SPECS/ARCHIVE/INDEX.md | 2 ++ ...version_mismatch_in_troubleshooting_guide.md | 4 ++++ .../P1-T13_Validation_Report.md | 8 ++++---- SPECS/INPROGRESS/next.md | 17 ++++++----------- SPECS/Workplan.md | 12 +++++++----- 5 files changed, 23 insertions(+), 20 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide}/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md (98%) rename SPECS/{INPROGRESS => ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide}/P1-T13_Validation_Report.md (87%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 105049d..dadbcc3 100644 --- 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 | @@ -640,3 +641,4 @@ | 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) | diff --git a/SPECS/INPROGRESS/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md b/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md similarity index 98% rename from SPECS/INPROGRESS/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md rename to SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md index 1c31fa7..bb7487f 100644 --- a/SPECS/INPROGRESS/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md +++ b/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide.md @@ -47,3 +47,7 @@ None ## Risk Low — documentation-only change. + +--- +**Archived:** 2026-03-10 +**Verdict:** PASS diff --git a/SPECS/INPROGRESS/P1-T13_Validation_Report.md b/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Validation_Report.md similarity index 87% rename from SPECS/INPROGRESS/P1-T13_Validation_Report.md rename to SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Validation_Report.md index b34faa2..ddd3824 100644 --- a/SPECS/INPROGRESS/P1-T13_Validation_Report.md +++ b/SPECS/ARCHIVE/P1-T13_Document_stale_editable_install_version_mismatch_in_troubleshooting_guide/P1-T13_Validation_Report.md @@ -6,7 +6,7 @@ Document stale editable install version mismatch in troubleshooting guide ## Date -2026-03-07 +2026-03-10 ## Changes Made @@ -27,10 +27,10 @@ Added matching section `## "Package Version" shows old release after version bum | Gate | Result | |------|--------| -| `pytest` | 898 passed, 5 skipped | +| `pytest` | 902 passed, 5 skipped | | `ruff check src/` | All checks passed | -| `mypy src/` | Not configured (skipped per project convention) | -| `pytest --cov` | 91.75% (≥ 90% required) ✅ | +| `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 diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 331f44d..3a112cf 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,26 +1,21 @@ -# Next Task: P1-T13 +# Next Task: None ## Selected Task -- **ID:** P1-T13 -- **Name:** Document stale editable install version mismatch in troubleshooting guide -- **Priority:** P2 -- **Branch:** `feature/P1-T13-stale-editable-install-troubleshooting` -- **Status:** In Progress +- No active task selected. ## 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 in `docs/troubleshooting.md` and sync the DocC mirror. +All tasks currently tracked in `SPECS/Workplan.md` are archived or completed. Select a new +task only after a follow-up or new workplan entry is created. ## Outputs -- `docs/troubleshooting.md` — new entry for stale editable install version mismatch -- `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` — DocC mirror synced +- None. ## 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 index ba55451..6daa9fc 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -186,7 +186,8 @@ 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 +#### ✅ 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 @@ -194,11 +195,12 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - **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:** - - [ ] `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 .`) - - [ ] 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 .` - - [ ] DocC mirror (`Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`) is updated to match - - [ ] `make doccheck-all` passes + - [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 From ad4526a16427a1d79e406b860b8de1188037618c Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 10 Mar 2026 02:47:54 +0300 Subject: [PATCH 06/10] Review P1-T13: p1_t13_editable_install_troubleshooting --- ...p1_t13_editable_install_troubleshooting.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_p1_t13_editable_install_troubleshooting.md diff --git a/SPECS/INPROGRESS/REVIEW_p1_t13_editable_install_troubleshooting.md b/SPECS/INPROGRESS/REVIEW_p1_t13_editable_install_troubleshooting.md new file mode 100644 index 0000000..973039a --- /dev/null +++ b/SPECS/INPROGRESS/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. From e62ead4d9a2469d337db339d7910f869e28f76fa Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 10 Mar 2026 02:48:16 +0300 Subject: [PATCH 07/10] Archive REVIEW_p1_t13_editable_install_troubleshooting report --- SPECS/ARCHIVE/INDEX.md | 2 ++ .../REVIEW_p1_t13_editable_install_troubleshooting.md | 0 2 files changed, 2 insertions(+) rename SPECS/{INPROGRESS => ARCHIVE/_Historical}/REVIEW_p1_t13_editable_install_troubleshooting.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index dadbcc3..a5f7945 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -207,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 | @@ -642,3 +643,4 @@ | 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/SPECS/INPROGRESS/REVIEW_p1_t13_editable_install_troubleshooting.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md similarity index 100% rename from SPECS/INPROGRESS/REVIEW_p1_t13_editable_install_troubleshooting.md rename to SPECS/ARCHIVE/_Historical/REVIEW_p1_t13_editable_install_troubleshooting.md From fa25498a8f21b00127d9d8fa334ed92cf0d37bce Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 10 Mar 2026 02:58:25 +0300 Subject: [PATCH 08/10] Fix PR feedback: unescape P1-T13 troubleshooting heading --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 96eff56..3c57736 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -689,7 +689,7 @@ 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) +### "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: From 271158b426bc20dcd53fac43fa852c97384d8343 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 10 Mar 2026 02:58:33 +0300 Subject: [PATCH 09/10] Fix PR feedback: use artifact in troubleshooting doc --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3c57736..67d2a36 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -711,7 +711,7 @@ the installed binary still reports the version from the last `pip install -e .` 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 artefact of the dev environment, not a real compatibility +`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 From 667fa7f87ffaac6d8a3790424fe748319937801a Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 10 Mar 2026 02:58:42 +0300 Subject: [PATCH 10/10] Fix PR feedback: use artifact in DocC troubleshooting --- Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 0474ad4..fb8e045 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -644,7 +644,7 @@ when `pip install -e .` runs. Bumping `pyproject.toml` alone does not update the 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 artefact of the dev environment, not a real compatibility +`broker.version`. The mismatch is an artifact of the dev environment, not a real compatibility problem. End users running `uvx` are never affected. **Fix:**