P1-T5: Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section

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 |
@@ -183,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 |
@@ -311,6 +313,8 @@
 
 | 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) |
 | 2026-03-01 | P1-T8 | Archived REVIEW_p1_t8_config_broker_setup_first report |

SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting.md

@@ -0,0 +1,60 @@
+# 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.
+
+---
+**Archived:** 2026-03-04
+**Verdict:** PASS

SPECS/ARCHIVE/P1-T5_Fix_missed_broker_spawn_references_in_troubleshooting/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 <shared-path>\` ...`
+- `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.

SPECS/ARCHIVE/_Historical/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.

SPECS/INPROGRESS/next.md

@@ -1,14 +1,15 @@
 # No Active Task
 
-**Status:** Idle — P1-T9 archived. Select the next task from `SPECS/Workplan.md`.
+**Status:** Idle — P1-T5 archived. Select the next task from `SPECS/Workplan.md`.
 
 ## Recently Archived
 
+- **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)
-- **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)
+
+## Suggested Next Tasks
+
+- **P1-T6** — Update webui-setup.md and DocC mirror to use --broker in multi-agent examples (Priority: P3)

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
-- **Status:** ⬜ Pending
-- **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