SoundBlaster · SoundBlaster · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/README.md b/README.md
@@ -104,6 +104,7 @@ Restart Cursor and you're done. For other clients or installation methods, read
 Broker mode lets multiple short-lived MCP client sessions share one persistent
 upstream bridge session.
 
+- **Why this mode exists:** Apple documents a Coding Intelligence known issue in Xcode 26.4 where external development tools may trigger repeated "Allow Connection?" dialogs during normal usage (`170721057`). Reusing one long-lived upstream session via broker mode can reduce reconnect churn that surfaces this prompt pattern. See Apple's official [Xcode 26.4 release notes](https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes).
 - Use `--broker-connect` to attach to an already-running broker.
 - Use `--broker-spawn` to auto-start the broker if needed.
 - Add `--web-ui` (plus optional `--web-ui-config`) when you want the spawned or daemon host to own one shared dashboard endpoint.

diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-02-28 (P1-T1)
+**Last Updated:** 2026-02-28 (P1-T2)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P1-T2 | [P1-T2_Add_Xcode_26_4_known_issue_release_notes_link_to_README/](P1-T2_Add_Xcode_26_4_known_issue_release_notes_link_to_README/) | 2026-02-28 | PASS |
 | P1-T1 | [P1-T1_Add_the_version_badge_in_the_README/](P1-T1_Add_the_version_badge_in_the_README/) | 2026-02-28 | PASS |
 | P15-T1 | [P15-T1_Validate_project_readiness_for_the_next_release/](P15-T1_Validate_project_readiness_for_the_next_release/) | 2026-02-28 | PASS |
 | FU-P13-T19 | [FU-P13-T19_Add_integration_coverage_for_broker-hosted_Web_UI_observability/](FU-P13-T19_Add_integration_coverage_for_broker-hosted_Web_UI_observability/) | 2026-02-28 | PASS |
@@ -170,6 +171,7 @@
 |------|-------------|
 | [Workplan_0.4.0.md](_Historical/Workplan_0.4.0.md) | Archived workplan snapshot for release 0.4.0 |
 | [REVIEW_p1_t1_version_badge_script_tests.md](_Historical/REVIEW_p1_t1_version_badge_script_tests.md) | Review report for P1-T1 (version badge script/tests) |
+| [REVIEW_p1_t2_xcode_26_4_known_issue_link.md](_Historical/REVIEW_p1_t2_xcode_26_4_known_issue_link.md) | Review report for P1-T2 |
 | [REVIEW_p15_t1_next_release_readiness.md](_Historical/REVIEW_p15_t1_next_release_readiness.md) | Review report for P15-T1 |
 | [REVIEW_fu_p13_t19_broker_webui_observability.md](_Historical/REVIEW_fu_p13_t19_broker_webui_observability.md) | Review report for FU-P13-T19 |
 | [REVIEW_fu_p13_t18_unified_config_docs.md](_Historical/REVIEW_fu_p13_t18_unified_config_docs.md) | Review report for FU-P13-T18 |
@@ -514,3 +516,5 @@
 | 2026-02-20 | BUG-T14 | Archived REVIEW_bug_t14_latency_rows report |
 | 2026-02-28 | P1-T1 | Archived Add_the_version_badge_in_the_README (PASS) |
 | 2026-02-28 | P1-T1 | Archived REVIEW_p1_t1_version_badge_script_tests report |
+| 2026-02-28 | P1-T2 | Archived Add_Xcode_26_4_known_issue_release_notes_link_to_README (PASS) |
+| 2026-02-28 | P1-T2 | Archived REVIEW_p1_t2_xcode_26_4_known_issue_link report |
diff --git a/...link_to_README/P1-T2_Add_Xcode_26_4_known_issue_release_notes_link_to_README.md b/...link_to_README/P1-T2_Add_Xcode_26_4_known_issue_release_notes_link_to_README.md
@@ -0,0 +1,68 @@
+# P1-T2 PRD — Add Xcode 26.4 known issue release-notes link to README
+
+## Objective
+
+Update `README.md` so users have an explicit, authoritative reference to Apple’s official Xcode 26.4 release notes entry for the Coding Intelligence known issue where repeated "Allow Connection?" dialogs can appear with external development tools. The change should improve troubleshooting clarity without introducing speculative guidance, and keep the README aligned with official wording and issue ID `170721057`.
+
+## Scope and Deliverables
+
+- Add a short known-issue note to `README.md` in an appropriate troubleshooting or setup section.
+- Include a direct link to Apple’s official Xcode 26.4 release notes page:
+  - `https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes`
+- Reference the issue context and identifier:
+  - "Coding Intelligence" known issue
+  - repeated "Allow Connection?" dialogs
+  - issue ID `170721057`
+- Produce `SPECS/INPROGRESS/P1-T2_Validation_Report.md` with command evidence and acceptance checks.
+
+## Success Criteria and Acceptance Tests
+
+- `README.md` includes the official Xcode 26.4 release-notes URL.
+- `README.md` explicitly mentions the known issue text context and issue ID `170721057`.
+- Documentation style remains consistent with existing README tone and formatting.
+- Required quality gates run and pass for this task branch:
+  - `pytest`
+  - `ruff check src/`
+  - `mypy src/`
+  - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` (coverage remains >= 90%).
+
+## Test-First Plan
+
+1. Identify the most appropriate existing README section before editing to minimize structural churn.
+2. Add/adjust documentation text in a single focused README edit.
+3. Verify link and issue reference presence with targeted grep checks before running full quality gates.
+
+## Execution Plan
+
+### Phase 1: Documentation placement and wording
+
+- Inputs: current `README.md` structure and troubleshooting/setup sections.
+- Outputs: concise known-issue note draft with Apple link and issue ID.
+- Verification: local read-through confirms wording is specific and non-duplicative.
+
+### Phase 2: README implementation
+
+- Inputs: approved note content from Phase 1.
+- Outputs: updated `README.md` section containing the official link and issue note.
+- Verification: `rg` checks confirm URL and `170721057` appear exactly as intended.
+
+### Phase 3: Validation and reporting
+
+- Inputs: updated docs and repository quality-gate commands.
+- Outputs: `SPECS/INPROGRESS/P1-T2_Validation_Report.md` with command results and acceptance checklist.
+- Verification: all required gates pass and coverage remains at/above project threshold.
+
+## Decision Notes and Constraints
+
+- Keep this task documentation-only; no behavior changes to runtime code.
+- Use official Apple terminology and avoid unsupported mitigation claims.
+- If related wording already exists, prefer refining existing text over adding redundant sections.
+
+## Notes (Post-Implementation)
+
+- Archive artifacts must include this PRD and validation report.
+- REVIEW subject for this task: `p1_t2_xcode_26_4_known_issue_link`.
+
+---
+**Archived:** 2026-02-28
+**Verdict:** PASS
diff --git a/..._Xcode_26_4_known_issue_release_notes_link_to_README/P1-T2_Validation_Report.md b/..._Xcode_26_4_known_issue_release_notes_link_to_README/P1-T2_Validation_Report.md
@@ -0,0 +1,38 @@
+# Validation Report — P1-T2: Add Xcode 26.4 known issue release-notes link to README
+
+**Date:** 2026-02-28  
+**Verdict:** PASS
+
+## Scope
+
+Added an official Xcode 26.4 known-issue reference to `README.md` that documents the repeated "Allow Connection?" prompt behavior for external development tools as broker-mode motivation and links directly to Apple's release notes.
+
+## Deliverables
+
+- `README.md` updated in the `### Broker Mode (Optional)` section with:
+  - issue context for Coding Intelligence prompt repetition
+  - issue ID `170721057`
+  - official release-notes link: `https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes`
+
+## Acceptance Criteria Check
+
+- [x] `README.md` includes a link to `https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes`
+- [x] `README.md` mentions the Coding Intelligence known issue about repeated "Allow Connection?" dialogs and references issue ID `170721057`
+
+## Commands Executed
+
+- `PYTHONPATH=src pytest`
+- `ruff check src/`
+- `mypy src/`
+- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing`
+
+## Results
+
+- `pytest`: PASS (`715 passed, 5 skipped, 2 warnings`)
+- `ruff check src/`: PASS (`All checks passed!`)
+- `mypy src/`: PASS (`Success: no issues found in 18 source files`)
+- Coverage: PASS (`Total coverage: 91.72%`, threshold 90%)
+
+## Notes
+
+- Two deprecation warnings from `websockets.legacy` / `websockets.server.WebSocketServerProtocol` are pre-existing and non-blocking for this documentation-only task.
diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_p1_t2_xcode_26_4_known_issue_link.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t2_xcode_26_4_known_issue_link.md
@@ -0,0 +1,34 @@
+## REVIEW REPORT — P1-T2 Xcode 26.4 Known Issue Link
+
+**Scope:** origin/main..HEAD  
+**Files:** 6
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+
+- None.
+
+### Secondary Issues
+
+- None requiring follow-up tasks.
+
+### Architectural Notes
+
+- The README now references the official Apple release-notes source for the external-tool prompt behavior, which reduces ambiguity and avoids non-authoritative troubleshooting guidance.
+- Task workflow artifacts (PRD + validation) were archived cleanly under the dedicated P1-T2 archive folder, consistent with existing repository process.
+
+### Tests
+
+- `PYTHONPATH=src pytest` passed (`715 passed, 5 skipped`).
+- `ruff check src/` passed.
+- `mypy src/` passed (`18 source files checked`).
+- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` passed with `91.72%` total coverage (>=90%).
+
+### Next Steps
+
+- FOLLOW-UP skipped: no actionable review findings for this task.
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -2,11 +2,11 @@
 
 ## Recently Archived
 
+- **P1-T2** — Add Xcode 26.4 known issue release-notes link to README (2026-02-28, PASS)
 - **P1-T1** — Add the version badge in the README.md (2026-02-28, PASS)
 - **P15-T1** — Validate project readiness for the next release (2026-02-28, PASS)
 - **FU-P13-T19** — Add integration coverage for broker-hosted Web UI observability (2026-02-28, PASS)
-- **FU-P13-T18** — Document unified single-config setup for broker + Web UI multi-agent workflows (2026-02-28, PASS)
 
 ## Suggested Next Tasks
 
-- **None** — All tasks completed (1/1)
+- **None** — All tasks completed (2/2)
diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -27,3 +27,16 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
 - **Acceptance Criteria:**
   - [x] `README.md` includes a visible version badge near the project heading or badges area
   - [x] The badge renders correctly and links to the canonical published version page
+
+#### ✅ P1-T2: Add Xcode 26.4 known issue release-notes link to README
+- **Status:** ✅ Completed (2026-02-28)
+- **Description:** Update `README.md` to include a link to the official Xcode 26.4 release notes for the Coding Intelligence known issue: "When using external development tools that connect to Xcode, you may see multiple \"Allow Connection?\" dialogs during normal usage. (170721057)".
+- **Priority:** P2
+- **Dependencies:** none
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - `README.md` updated with the official Xcode release-notes reference link
+  - A note in `README.md` that points users to the documented known issue (170721057)
+- **Acceptance Criteria:**
+  - [x] `README.md` includes a link to `https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes`
+  - [x] `README.md` mentions the Coding Intelligence known issue about repeated "Allow Connection?" dialogs and references issue ID `170721057`
diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md
@@ -98,6 +98,7 @@ Restart Cursor and you're done. For other clients or installation methods, read
 
 Broker mode lets short-lived MCP sessions share one persistent upstream bridge.
 
+- **Why this mode exists:** Apple documents a Coding Intelligence known issue in Xcode 26.4 where external development tools may trigger repeated "Allow Connection?" dialogs during normal usage (`170721057`). Reusing one long-lived upstream session via broker mode can reduce reconnect churn that surfaces this prompt pattern. See Apple's official [Xcode 26.4 release notes](https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes).
 - `--broker-connect`: attach to an already-running broker.
 - `--broker-spawn`: best-effort auto-start, then connect.
 - Add `--web-ui` (plus optional `--web-ui-config`) when you want the spawned or daemon host to own one shared dashboard endpoint.