diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 3ae896cd..69bf142e 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,11 +1,12 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-03-04 (P1-T5 archived) +**Last Updated:** 2026-03-04 (P1-T6 archived) ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P1-T6 | [P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/](P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/) | 2026-03-04 | PASS | | 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 | @@ -184,6 +185,7 @@ | File | Description | |------|-------------| +| [REVIEW_p1_t6_webui_broker_examples.md](_Historical/REVIEW_p1_t6_webui_broker_examples.md) | Review report for P1-T6 | | [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 | @@ -313,6 +315,8 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-03-04 | P1-T6 | Archived REVIEW_p1_t6_webui_broker_examples report | +| 2026-03-04 | P1-T6 | Archived Update webui-setup.md and DocC mirror to use --broker in multi-agent examples (PASS) | | 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 | diff --git a/SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples.md b/SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples.md new file mode 100644 index 00000000..998da3c2 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples.md @@ -0,0 +1,81 @@ +# P1-T6 PRD — Update webui-setup.md and DocC mirror to use --broker in multi-agent examples + +## Task Metadata + +- **Task ID:** P1-T6 +- **Phase:** Phase 1: Documentation +- **Priority:** P3 +- **Dependencies:** P1-T4 +- **Source:** `SPECS/Workplan.md` open task entry + +## Objective Summary + +Align remaining Web UI multi-agent setup documentation with the current broker CLI contract by replacing legacy `--broker-spawn` usage with `--broker`. The two target docs (`docs/webui-setup.md` and `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md`) should match each other and reflect the same recommended command examples already adopted elsewhere in project docs. + +This task is documentation-only and should not change runtime behavior. The goal is consistency, lower user confusion, and removal of stale examples that imply deprecated or removed flags are still preferred. The update should preserve surrounding guidance (single host broker, shared telemetry, web UI hosting constraints) while changing only the broker invocation form and any adjacent wording that explicitly references spawning. + +## Success Criteria + +1. Every multi-agent broker setup example in `docs/webui-setup.md` uses `--broker` (not `--broker-spawn`). +2. The mirrored sections in `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` match the updated canonical docs wording and commands. +3. `make doccheck-all` passes with no drift between docs and DocC mirrors. +4. Repository quality gates remain green (`pytest`, `ruff check src/`, `mypy src/mcpbridge_wrapper`, coverage >= 90%). + +## Acceptance Tests + +- Search assertions: + - `rg --fixed-strings --line-number "--broker-spawn" docs/webui-setup.md Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` returns no task-related example hits. + - `rg --line-number "--broker" docs/webui-setup.md Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` shows updated example commands. +- Validation command: + - `make doccheck-all` exits successfully. +- Regression gates: + - `pytest` + - `ruff check src/` + - `mypy src/mcpbridge_wrapper` + - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` + +## Test-First Plan + +1. Inspect current docs and capture baseline grep output for `--broker-spawn` occurrences in both target files. +2. Define expected post-change command strings for each multi-agent section before editing. +3. Apply minimal textual edits to canonical docs first, then mirror the same edits to DocC. +4. Re-run targeted grep checks immediately after edits to verify stale flags are removed. +5. Run `make doccheck-all` before full quality gates to catch documentation drift early. +6. Run full required quality gates and record outcomes in validation report. + +## Implementation Plan (Hierarchical TODO) + +### Phase A — Baseline Audit + +- **Inputs:** Current versions of `docs/webui-setup.md`, `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md`. +- **Outputs:** List of exact sections/commands still using `--broker-spawn`. +- **Verification:** Grep results identify all target lines and no unrelated files are modified. + +### Phase B — Documentation Updates + +- **Inputs:** Baseline audit findings + current broker guidance from existing docs. +- **Outputs:** Updated broker examples and wording in both files. +- **Verification:** Side-by-side diff confirms command changes are intentional and mirrored. + +### Phase C — Consistency and Quality Validation + +- **Inputs:** Updated docs and repository quality tooling. +- **Outputs:** Passing `doccheck-all` and required quality gate outputs. +- **Verification:** Command exit codes are zero; validation report records command evidence and verdict. + +## Decision Points and Constraints + +- Keep scope strictly to P1-T6 artifacts unless validation reveals required synchronization edits. +- Prefer exact mirror consistency between canonical docs and DocC content. +- Avoid changing unrelated examples or historical notes unless they directly reference the removed flag in the target sections. +- This repository declares Python 3.7+ compatibility; use existing command targets without introducing new tooling assumptions. + +## Notes (Post-Completion Docs/Artifacts) + +- Produce `SPECS/INPROGRESS/P1-T6_Validation_Report.md` with full gate results and final verdict. +- Archive this PRD and the validation report into `SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/` during ARCHIVE. +- Update `SPECS/ARCHIVE/INDEX.md` and mark the workplan task as completed once validated. + +--- +**Archived:** 2026-03-04 +**Verdict:** PASS diff --git a/SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/P1-T6_Validation_Report.md b/SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/P1-T6_Validation_Report.md new file mode 100644 index 00000000..a29294b1 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/P1-T6_Validation_Report.md @@ -0,0 +1,73 @@ +# Validation Report — P1-T6 + +**Task:** P1-T6 — Update webui-setup.md and DocC mirror to use `--broker` in multi-agent examples +**Date:** 2026-03-04 +**Executor:** Codex (`flow-run`) +**Verdict:** PASS (No-op verification) + +## Summary + +`P1-T6` was validated against the current `main` baseline on feature branch `codex/feature/P1-T6-webui-broker-examples`. +The target documentation files were already aligned with `--broker` guidance before execution, so no content edits were required. +Required documentation sync and repository quality gates passed. + +## Acceptance Criteria Check + +- [x] `docs/webui-setup.md` multi-agent broker example uses `--broker` +- [x] DocC mirror updated to match (already in sync) +- [x] `make doccheck-all` passes + +## Evidence + +### Documentation assertions + +```bash +rg -n --fixed-strings -- "--broker-spawn" docs/webui-setup.md Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md +``` + +Result: no matches. + +```bash +rg -n --fixed-strings -- "--broker --web-ui --web-ui-config " docs/webui-setup.md Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md +``` + +Result: +- `docs/webui-setup.md:101` +- `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md:52` + +### Required quality gates + +```bash +make doccheck-all +``` + +Result: pass (`DocC sync checks passed across unstaged, staged, and branch scopes`). + +```bash +pytest +``` + +Result: `741 passed, 5 skipped`. + +```bash +ruff check src/ +``` + +Result: `All checks passed!`. + +```bash +mypy src/mcpbridge_wrapper +``` + +Result: `Success: no issues found in 18 source files`. + +```bash +pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing +``` + +Result: `741 passed, 5 skipped`, total coverage `91.03%` (>= 90%). + +## Notes + +- This task is closed as a documentation-state verification no-op. +- ARCHIVE should move this report and the PRD into the P1-T6 archive folder and mark the workplan entry complete. diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_p1_t6_webui_broker_examples.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t6_webui_broker_examples.md new file mode 100644 index 00000000..228f59b0 --- /dev/null +++ b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t6_webui_broker_examples.md @@ -0,0 +1,32 @@ +## REVIEW REPORT — P1-T6 Web UI broker examples + +**Scope:** origin/main..HEAD +**Files:** 5 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- None. + +### Architectural Notes +- The task is closed as a documentation verification no-op. The archive artifacts correctly capture that both target docs were already aligned to `--broker` before execution. +- `SPECS/INPROGRESS/next.md` now reflects an idle state with no pending tasks in the current cycle. + +### Tests +- Validation report evidence confirms required gates passed: + - `make doccheck-all` + - `pytest` + - `ruff check src/` + - `mypy src/mcpbridge_wrapper` + - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` (coverage 91.03%) + +### Next Steps +- No actionable review findings. +- FOLLOW-UP step is explicitly skipped. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index a256391f..95522f3a 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,15 +1,15 @@ # No Active Task -**Status:** Idle — P1-T5 archived. Select the next task from `SPECS/Workplan.md`. +**Status:** Idle — P1-T6 archived. Select the next task from `SPECS/Workplan.md`. ## Recently Archived +- **P1-T6** — Update webui-setup.md and DocC mirror to use --broker in multi-agent examples (2026-03-04, PASS) - **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) ## Suggested Next Tasks -- **P1-T6** — Update webui-setup.md and DocC mirror to use --broker in multi-agent examples (Priority: P3) +- No pending tasks in the current cycle. Add new tasks to `SPECS/Workplan.md`. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 71df272c..19ab6d4b 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -87,19 +87,19 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [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 -- **Description:** `docs/webui-setup.md` and `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` still use `--broker-spawn` in their multi-agent broker setup examples. These files were out of scope for P1-T4 but are now inconsistent with all other broker docs. Found during P1-T4 review (low severity). +#### ✅ P1-T6: Update webui-setup.md and DocC mirror to use --broker in multi-agent examples +- **Status:** ✅ Completed (2026-03-04) +- **Description:** Verified and archived this follow-up as already satisfied on the latest `main` baseline: both `docs/webui-setup.md` and `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` already use `--broker` in the targeted multi-agent examples and remain in sync. - **Priority:** P3 - **Dependencies:** P1-T4 - **Parallelizable:** yes - **Outputs/Artifacts:** - - `docs/webui-setup.md` — multi-agent examples updated to `--broker` - - `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` — mirror synced + - `SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/` — archived PRD + validation report + - `SPECS/ARCHIVE/P1-T6_Update_webui_setup_and_DocC_mirror_to_use_broker_in_multi_agent_examples/P1-T6_Validation_Report.md` — verification evidence for no-op completion - **Acceptance Criteria:** - - [ ] `docs/webui-setup.md` multi-agent broker example uses `--broker` - - [ ] DocC mirror updated to match - - [ ] `make doccheck-all` passes + - [x] `docs/webui-setup.md` multi-agent broker example uses `--broker` + - [x] DocC mirror updated to match + - [x] `make doccheck-all` passes #### ✅ P1-T7: Hide README version badge maintenance note - **Status:** ✅ Completed (2026-03-01)