From b1ca9e41f5bd6d2d77702b0b1ca883950013275f Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 4 Mar 2026 09:47:34 +0300 Subject: [PATCH 1/7] Branch for P1-T5: fix missed broker references From 07860a216cea17be2590636ec355400626ebafa4 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 4 Mar 2026 09:48:29 +0300 Subject: [PATCH 2/7] Select task P1-T5: Fix missed broker references in troubleshooting --- SPECS/INPROGRESS/next.md | 23 ++++++++++++----------- SPECS/Workplan.md | 4 ++-- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 9a4221e3..0fcaefcf 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,14 +1,15 @@ -# No Active Task +# Next Task: P1-T5 — Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section -**Status:** Idle — P1-T9 archived. Select the next task from `SPECS/Workplan.md`. +**Priority:** P2 +**Phase:** Phase 1: Documentation +**Effort:** 0.5h +**Dependencies:** P1-T4 +**Status:** Selected -## Recently Archived +## Description -- **P1-T9** — Add direct links for all command steps in FLOW.md (2026-03-03, PASS) -- **P3-T11** — Add Stop broker/service control button to Web UI (2026-03-01, PASS) -- **P1-T8** — Update /config examples for broker setup first (2026-03-01, PASS) -- **P2-T6** — Remove legacy --broker-connect and --broker-spawn flags (2026-03-01, PASS) -- **P1-T7** — Hide README version badge maintenance note (2026-03-01, PASS) -- **P1-T4** — Update docs to reflect broker robustness improvements (2026-03-01, PASS) -- **P2-T5** — Warn or restart daemon when --web-ui requested but running broker lacks it (2026-03-01, PASS) -- **P2-T4** — Surface broker unavailability as JSON-RPC error instead of silent timeout (2026-03-01, PASS) +Fix two stale `--broker-spawn` references in `docs/troubleshooting.md` so this section aligns with the broker guidance delivered in P1-T4 and with its already-correct DocC mirror. + +## Next Step + +Run the PLAN command to generate the implementation-ready PRD. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 6d394e65..c03334fc 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -73,8 +73,8 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [ ] New troubleshooting entry for "Warning: broker is running without --web-ui" present - [ ] DocC sync check passes (`make doccheck-all`) -#### ⬜ P1-T5: Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section -- **Status:** ⬜ Pending +#### ⬜ P1-T5: Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section **INPROGRESS** +- **Status:** 🟧 In Progress (2026-03-04) - **Description:** Two lines in `docs/troubleshooting.md` "MCP tools are green, but dashboard is unreachable" section still say `--broker-spawn` where they should say `--broker`. The DocC mirror (`Sources/.../Troubleshooting.md`) was correctly updated in P1-T4 but the docs source was missed. Found during P1-T4 review (medium severity). - **Priority:** P2 - **Dependencies:** P1-T4 From 02b5c128d76749440209114b6664052b12b6a8b7 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 4 Mar 2026 09:49:01 +0300 Subject: [PATCH 3/7] Plan task P1-T5: Fix missed broker references in troubleshooting --- ...ker_spawn_references_in_troubleshooting.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 SPECS/INPROGRESS/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md diff --git a/SPECS/INPROGRESS/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md b/SPECS/INPROGRESS/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md new file mode 100644 index 00000000..48998727 --- /dev/null +++ b/SPECS/INPROGRESS/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md @@ -0,0 +1,56 @@ +# P1-T5 PRD — Fix missed --broker-spawn references in troubleshooting + +## Task Metadata +- **Task ID:** P1-T5 +- **Phase:** Phase 1 — Documentation +- **Priority:** P2 +- **Dependencies:** P1-T4 +- **Source:** `SPECS/Workplan.md` open follow-up from P1-T4 review + +## Objective Summary +Correct the two remaining stale `--broker-spawn` references in the `docs/troubleshooting.md` section titled "MCP tools are green, but dashboard is unreachable" so guidance is consistent with the broker-mode consolidation (`--broker`) completed in previous tasks. This task is intentionally narrow and should not alter runtime behavior, CLI parsing, or unrelated docs. + +The change must align the docs source with existing guidance already reflected in the DocC mirror. The goal is to eliminate contradictory setup examples that could make users start a broker in a legacy mode when the project now documents `--broker` as the canonical entrypoint. + +## Deliverables +- Updated `docs/troubleshooting.md` with both targeted command examples changed to `--broker --web-ui`. +- Validation report at `SPECS/INPROGRESS/P1-T5_Validation_Report.md` capturing quality gate outputs and verdict. +- Archived task artifacts after completion in `SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/`. + +## Success Criteria and Acceptance Tests +1. The line describing "only starts one when it must spawn a host" uses `--broker --web-ui`. +2. The "Unified broker single-config" solution option uses `--broker --web-ui`. +3. `make doccheck-all` passes to confirm docs and DocC mirrors stay synchronized. +4. Required FLOW quality gates (`pytest`, `ruff check src/`, `mypy src/`, `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing`) complete successfully with coverage at or above 90%. + +## Test-First Plan +1. Identify current failing condition by searching for `--broker-spawn --web-ui` in `docs/troubleshooting.md` and confirming exactly two target hits in the impacted section. +2. Confirm mirror baseline by checking the corresponding DocC troubleshooting content is already on `--broker` (no edit expected there). +3. Apply minimal text edits in the docs source only. +4. Re-run search to assert no stale `--broker-spawn` remains in that section. + +## Hierarchical Execution Plan + +### Phase A — Baseline and scope lock +- **Inputs:** `SPECS/Workplan.md`, `docs/troubleshooting.md`, DocC troubleshooting mirror. +- **Outputs:** Confirmed exact edit scope (2 lines). +- **Verification:** `rg -n "broker-spawn|MCP tools are green" docs/troubleshooting.md` and targeted mirror spot-check. + +### Phase B — Documentation correction +- **Inputs:** Baseline findings from Phase A. +- **Outputs:** `docs/troubleshooting.md` updated from `--broker-spawn --web-ui` to `--broker --web-ui` in the two required lines. +- **Verification:** `git diff -- docs/troubleshooting.md` shows only expected replacements. + +### Phase C — Validation and reporting +- **Inputs:** Edited docs + repo quality gates. +- **Outputs:** Passing validation commands and `SPECS/INPROGRESS/P1-T5_Validation_Report.md`. +- **Verification:** Command exit codes are zero; coverage output reports >=90%; report records PASS/FAIL/PARTIAL clearly. + +## Decision Points and Constraints +- Keep edits minimal and task-scoped; avoid opportunistic rewrites. +- Preserve existing wording and structure except for command flag correction. +- If `make doccheck-all` surfaces unrelated failures, record them explicitly and classify verdict accordingly. + +## Notes +- After EXECUTE, archive using the ARCHIVE command workflow and mark P1-T5 as completed in `SPECS/Workplan.md`. +- If review finds no new issues, FOLLOW-UP is skipped and REVIEW artifact is archived immediately. From 47e993317b03e925466e20e8adf32a1acec6ccfa Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 4 Mar 2026 09:50:20 +0300 Subject: [PATCH 4/7] Implement P1-T5: validate no-op broker flag consistency --- SPECS/INPROGRESS/P1-T5_Validation_Report.md | 32 +++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 SPECS/INPROGRESS/P1-T5_Validation_Report.md diff --git a/SPECS/INPROGRESS/P1-T5_Validation_Report.md b/SPECS/INPROGRESS/P1-T5_Validation_Report.md new file mode 100644 index 00000000..bb9b0e84 --- /dev/null +++ b/SPECS/INPROGRESS/P1-T5_Validation_Report.md @@ -0,0 +1,32 @@ +# Validation Report — P1-T5 + +**Task:** P1-T5 — Fix missed `--broker-spawn` references in troubleshooting.md +**Date:** 2026-03-04 +**Verdict:** PASS + +## Summary +P1-T5 was validated as already satisfied on the latest `main` baseline pulled during FLOW BRANCH. The two target lines in `docs/troubleshooting.md` already use `--broker --web-ui`, matching the acceptance criteria and the DocC mirror. + +No content edits to `docs/troubleshooting.md` were required in this execution cycle. + +## Acceptance Criteria Verification +- [x] `docs/troubleshooting.md` line "only starts one when it must spawn a host" uses `--broker --web-ui` (verified at line 309) +- [x] `docs/troubleshooting.md` "Unified broker single-config" solution option uses `--broker --web-ui` (verified at line 334) +- [x] `make doccheck-all` passes + +## Evidence +- `rg -n "MCP tools are green|broker --web-ui" docs/troubleshooting.md` + - `309:- \`--broker --web-ui\` only starts a dashboard when it must spawn a host...` + - `334:3. **Unified broker single-config:** use \`--broker --web-ui --web-ui-config \` ...` +- `rg -n -- '--broker-spawn' docs/troubleshooting.md Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` + - no matches + +## Required Quality Gates +- `pytest` → PASS (`741 passed, 5 skipped`) +- `ruff check src/` → PASS (`All checks passed!`) +- `mypy src/` → PASS (`Success: no issues found in 18 source files`) +- `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` → PASS (`Total coverage: 91.03%`, threshold `>=90%`) +- `make doccheck-all` → PASS + +## Notes +Because the task scope was already fulfilled upstream, EXECUTE for P1-T5 is recorded as a verified no-op implementation with full regression and documentation sync validation. From e2610984a3effc939a5ef0736ea362064385023b Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 4 Mar 2026 09:51:36 +0300 Subject: [PATCH 5/7] Archive task P1-T5: Fix missed broker references in troubleshooting (PASS) --- SPECS/ARCHIVE/INDEX.md | 4 +++- ...ker_spawn_references_in_troubleshooting.md | 4 ++++ .../P1-T5_Validation_Report.md | 0 SPECS/INPROGRESS/next.md | 20 +++++++++---------- SPECS/Workplan.md | 15 +++++++------- 5 files changed, 25 insertions(+), 18 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting}/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md (98%) rename SPECS/{INPROGRESS => ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting}/P1-T5_Validation_Report.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index aa57e77e..825620ff 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,11 +1,12 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-03-03 (P1-T9 archived) +**Last Updated:** 2026-03-04 (P1-T5 archived) ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P1-T5 | [P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/](P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/) | 2026-03-04 | PASS | | P1-T9 | [P1-T9_Add_direct_links_for_all_command_steps_in_FLOW/](P1-T9_Add_direct_links_for_all_command_steps_in_FLOW/) | 2026-03-03 | PASS | | P3-T11 | [P3-T11_Add_Stop_broker_service_control_button_to_Web_UI/](P3-T11_Add_Stop_broker_service_control_button_to_Web_UI/) | 2026-03-01 | PASS | | P1-T8 | [P1-T8_Update_config_examples_for_broker_setup_first/](P1-T8_Update_config_examples_for_broker_setup_first/) | 2026-03-01 | PASS | @@ -311,6 +312,7 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-03-04 | P1-T5 | Archived Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section (PASS) | | 2026-03-03 | P1-T9 | Archived REVIEW_p1_t9_flow_command_links report | | 2026-03-03 | P1-T9 | Archived Add direct links for all command steps in FLOW.md (PASS) | | 2026-03-01 | P1-T8 | Archived REVIEW_p1_t8_config_broker_setup_first report | diff --git a/SPECS/INPROGRESS/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md b/SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md similarity index 98% rename from SPECS/INPROGRESS/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md rename to SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md index 48998727..46782417 100644 --- a/SPECS/INPROGRESS/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md +++ b/SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md @@ -54,3 +54,7 @@ The change must align the docs source with existing guidance already reflected i ## Notes - After EXECUTE, archive using the ARCHIVE command workflow and mark P1-T5 as completed in `SPECS/Workplan.md`. - If review finds no new issues, FOLLOW-UP is skipped and REVIEW artifact is archived immediately. + +--- +**Archived:** 2026-03-04 +**Verdict:** PASS diff --git a/SPECS/INPROGRESS/P1-T5_Validation_Report.md b/SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/P1-T5_Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/P1-T5_Validation_Report.md rename to SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/P1-T5_Validation_Report.md diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 0fcaefcf..a256391f 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,15 +1,15 @@ -# Next Task: P1-T5 — Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section +# No Active Task -**Priority:** P2 -**Phase:** Phase 1: Documentation -**Effort:** 0.5h -**Dependencies:** P1-T4 -**Status:** Selected +**Status:** Idle — P1-T5 archived. Select the next task from `SPECS/Workplan.md`. -## Description +## Recently Archived -Fix two stale `--broker-spawn` references in `docs/troubleshooting.md` so this section aligns with the broker guidance delivered in P1-T4 and with its already-correct DocC mirror. +- **P1-T5** — Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section (2026-03-04, PASS) +- **P1-T9** — Add direct links for all command steps in FLOW.md (2026-03-03, PASS) +- **P3-T11** — Add Stop broker/service control button to Web UI (2026-03-01, PASS) +- **P1-T8** — Update /config examples for broker setup first (2026-03-01, PASS) +- **P2-T6** — Remove legacy --broker-connect and --broker-spawn flags (2026-03-01, PASS) -## Next Step +## Suggested Next Tasks -Run the PLAN command to generate the implementation-ready PRD. +- **P1-T6** — Update webui-setup.md and DocC mirror to use --broker in multi-agent examples (Priority: P3) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index c03334fc..71df272c 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -73,18 +73,19 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [ ] New troubleshooting entry for "Warning: broker is running without --web-ui" present - [ ] DocC sync check passes (`make doccheck-all`) -#### ⬜ P1-T5: Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section **INPROGRESS** -- **Status:** 🟧 In Progress (2026-03-04) -- **Description:** Two lines in `docs/troubleshooting.md` "MCP tools are green, but dashboard is unreachable" section still say `--broker-spawn` where they should say `--broker`. The DocC mirror (`Sources/.../Troubleshooting.md`) was correctly updated in P1-T4 but the docs source was missed. Found during P1-T4 review (medium severity). +#### ✅ P1-T5: Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section +- **Status:** ✅ Completed (2026-03-04) +- **Description:** Verified and archived this follow-up as already satisfied on the latest `main` baseline: both targeted lines in `docs/troubleshooting.md` already use `--broker --web-ui`, matching the DocC mirror and eliminating the previously reported mismatch. - **Priority:** P2 - **Dependencies:** P1-T4 - **Parallelizable:** yes - **Outputs/Artifacts:** - - `docs/troubleshooting.md` — 2 occurrences updated in "MCP tools are green" section + - `SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/` — archived PRD + validation report + - `SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/P1-T5_Validation_Report.md` — verification evidence for no-op completion - **Acceptance Criteria:** - - [ ] `docs/troubleshooting.md` line "only starts one when it must spawn a host" uses `--broker --web-ui` - - [ ] `docs/troubleshooting.md` "Unified broker single-config" solution option uses `--broker --web-ui` - - [ ] `make doccheck-all` passes (mirrors stay in sync) + - [x] `docs/troubleshooting.md` line "only starts one when it must spawn a host" uses `--broker --web-ui` + - [x] `docs/troubleshooting.md` "Unified broker single-config" solution option uses `--broker --web-ui` + - [x] `make doccheck-all` passes (mirrors stay in sync) #### ⬜ P1-T6: Update webui-setup.md and DocC mirror to use --broker in multi-agent examples - **Status:** ⬜ Pending From a0fbb336573777c84fbe45fa380e602f12a36961 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 4 Mar 2026 09:51:56 +0300 Subject: [PATCH 6/7] Review P1-T5: troubleshooting broker references --- .../REVIEW_p1_t5_troubleshooting_broker.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_p1_t5_troubleshooting_broker.md diff --git a/SPECS/INPROGRESS/REVIEW_p1_t5_troubleshooting_broker.md b/SPECS/INPROGRESS/REVIEW_p1_t5_troubleshooting_broker.md new file mode 100644 index 00000000..3fd30f87 --- /dev/null +++ b/SPECS/INPROGRESS/REVIEW_p1_t5_troubleshooting_broker.md @@ -0,0 +1,31 @@ +## REVIEW REPORT — P1-T5 Troubleshooting Broker References + +**Scope:** origin/main..HEAD +**Files:** 5 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- None. + +### Architectural Notes +- Execution is intentionally documentation-workflow only (no runtime code paths changed). +- Task was completed as a verified no-op because targeted docs lines were already corrected on `main`; artifacts capture this state clearly. + +### Tests +- `pytest` passed (`741 passed, 5 skipped`) +- `ruff check src/` passed +- `mypy src/` passed +- `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` passed (`91.03%` total, threshold `>=90%`) +- `make doccheck-all` passed + +### Next Steps +- No actionable follow-up items identified. +- FOLLOW-UP step can be skipped for P1-T5. From 414cb9d7eea900965200a2a7c32c67a67ca83f49 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 4 Mar 2026 09:52:26 +0300 Subject: [PATCH 7/7] Archive REVIEW_p1_t5_troubleshooting_broker report --- SPECS/ARCHIVE/INDEX.md | 2 ++ .../_Historical}/REVIEW_p1_t5_troubleshooting_broker.md | 0 2 files changed, 2 insertions(+) rename SPECS/{INPROGRESS => ARCHIVE/_Historical}/REVIEW_p1_t5_troubleshooting_broker.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 825620ff..3ae896cd 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -184,6 +184,7 @@ | File | Description | |------|-------------| +| [REVIEW_p1_t5_troubleshooting_broker.md](_Historical/REVIEW_p1_t5_troubleshooting_broker.md) | Review report for P1-T5 | | [REVIEW_p1_t9_flow_command_links.md](_Historical/REVIEW_p1_t9_flow_command_links.md) | Review report for P1-T9 | | [REVIEW_p3_t11_webui_stop_control.md](_Historical/REVIEW_p3_t11_webui_stop_control.md) | Review report for P3-T11 | | [REVIEW_p1_t8_config_broker_setup_first.md](_Historical/REVIEW_p1_t8_config_broker_setup_first.md) | Review report for P1-T8 | @@ -312,6 +313,7 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-03-04 | P1-T5 | Archived REVIEW_p1_t5_troubleshooting_broker report | | 2026-03-04 | P1-T5 | Archived Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section (PASS) | | 2026-03-03 | P1-T9 | Archived REVIEW_p1_t9_flow_command_links report | | 2026-03-03 | P1-T9 | Archived Add direct links for all command steps in FLOW.md (PASS) | diff --git a/SPECS/INPROGRESS/REVIEW_p1_t5_troubleshooting_broker.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t5_troubleshooting_broker.md similarity index 100% rename from SPECS/INPROGRESS/REVIEW_p1_t5_troubleshooting_broker.md rename to SPECS/ARCHIVE/_Historical/REVIEW_p1_t5_troubleshooting_broker.md