P8-T3: Prepare for Release 0.4.4

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to the mcpbridge-wrapper project will be documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.4] - 2026-03-10
+
+### Added
+
+- Added a deterministic Xcode approval observation harness that can script MCP startup probes, capture timestamped protocol traces, and document approval-race behavior for troubleshooting and validation workflows.
+
+### Fixed
+
+- Broker now emits a synthetic `notifications/tools/list_changed` when its warmed tool catalog first becomes usable, and again only when a later reconnect produces a materially different non-empty catalog, giving strict MCP clients an explicit refresh hint when upstream never sends one.
+
 ## [0.4.3] - 2026-03-10
 
 ### Fixed
@@ -113,6 +123,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - ✅ Support for all 20 Xcode MCP tools
 - ✅ Configuration examples for Cursor, Claude Code, and Codex CLI
 
+[0.4.4]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.4
 [0.4.3]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.3
 [0.4.2]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.2
 [0.4.1]: https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.1

README.md

@@ -3,7 +3,7 @@
 <!-- mcp-name: io.github.SoundBlaster/xcode-mcpbridge-wrapper -->
 
 <!-- version-badge:start -->
-[![Version](https://img.shields.io/badge/version-0.4.3-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.3)
+[![Version](https://img.shields.io/badge/version-0.4.4-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.4)
 <!-- version-badge:end -->
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

SPECS/ARCHIVE/INDEX.md

@@ -6,6 +6,7 @@
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P8-T3 | [P8-T3_Prepare_for_Release_0.4.4/](P8-T3_Prepare_for_Release_0.4.4/) | 2026-03-10 | PASS |
 | T-011 | [T-011_Emit_synthetic_broker_tools_list_changed_on_catalog_warm-up/](T-011_Emit_synthetic_broker_tools_list_changed_on_catalog_warm-up/) | 2026-03-10 | PASS |
 | T-010 | [T-010_Build_Xcode_approval_observation_harness/](T-010_Build_Xcode_approval_observation_harness/) | 2026-03-10 | PASS |
 | P8-T2 | [P8-T2_Prepare_for_Release_0.4.3/](P8-T2_Prepare_for_Release_0.4.3/) | 2026-03-10 | PASS |
@@ -212,6 +213,7 @@
 |------|-------------|
 | [REVIEW_t011_synthetic_broker_tools_list_changed.md](_Historical/REVIEW_t011_synthetic_broker_tools_list_changed.md) | Review report for T-011 |
 | [REVIEW_t010_xcode_approval_harness.md](_Historical/REVIEW_t010_xcode_approval_harness.md) | Review report for T-010 |
+| [REVIEW_release_0.4.4_preparation.md](P8-T3_Prepare_for_Release_0.4.4/REVIEW_release_0.4.4_preparation.md) | Review report for P8-T3 |
 | [REVIEW_release_0.4.3_preparation.md](P8-T2_Prepare_for_Release_0.4.3/REVIEW_release_0.4.3_preparation.md) | Review report for P8-T2 |
 | [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 |
@@ -654,3 +656,5 @@
 | 2026-03-10 | P1-T13 | Archived REVIEW_p1_t13_editable_install_troubleshooting report |
 | 2026-03-10 | T-010 | Archived Build_Xcode_approval_observation_harness (PASS) |
 | 2026-03-10 | T-010 | Archived REVIEW_t010_xcode_approval_harness report |
+| 2026-03-10 | P8-T3 | Archived Prepare_for_Release_0.4.4 (PASS) |
+| 2026-03-10 | P8-T3 | Archived REVIEW_release_0.4.4_preparation report |

SPECS/ARCHIVE/P8-T3_Prepare_for_Release_0.4.4/P8-T3_Prepare_for_Release_0.4.4.md

@@ -0,0 +1,135 @@
+# P8-T3: Prepare for Release 0.4.4
+
+**Status:** In Progress
+**Date:** 2026-03-10
+**Priority:** P0
+**Dependencies:** T-010, T-011 (completed)
+
+---
+
+## Objective
+
+Prepare patch release `0.4.4` for the work merged after `v0.4.3`:
+- `T-010` added a deterministic Xcode approval observation harness so startup behavior around the Xcode "Allow" dialog can be captured and replayed as structured protocol traces.
+- `T-011` taught the broker to emit a synthetic `notifications/tools/list_changed` when the warmed tool catalog first becomes usable, compensating for missing upstream change notifications after Xcode approval.
+
+The deliverable is a merge-ready branch that updates release metadata, records release notes in `CHANGELOG.md`, passes the full pre-release quality gate suite required by `PUBLISHING.md`, and leaves exact post-merge tag/publish commands for the human operator.
+
+**Scope boundary:** Creating and pushing the `v0.4.4` tag, publishing to PyPI, and publishing to the MCP Registry remain post-merge human actions on `main`. This task prepares the branch and validates the repository state before those actions.
+
+---
+
+## Current State
+
+| Artifact | Current value |
+|----------|---------------|
+| `pyproject.toml` version | `0.4.3` |
+| `server.json` root version | `0.4.3` |
+| `server.json` package version | `0.4.3` |
+| `README.md` version badge | `v0.4.3` |
+| `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` version badge | `v0.4.3` |
+| Latest git tag on current baseline | `v0.4.3` |
+| Unreleased merged work since `v0.4.3` | `T-010`, `T-011` |
+
+---
+
+## Deliverables
+
+1. **`pyproject.toml`** — `[project].version` updated to `0.4.4`.
+2. **`server.json`** — root `version` and `packages[0].version` updated to `0.4.4`.
+3. **`README.md`** — version badge updated to `v0.4.4`.
+4. **`Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md`** — DocC overview badge updated to `v0.4.4`.
+5. **`CHANGELOG.md`** — new `[0.4.4] - 2026-03-10` entry summarizing the shipped tooling/runtime changes.
+6. **`SPECS/INPROGRESS/P8-T3_Validation_Report.md`** — records release metadata checks, quality gates, and post-merge publish instructions.
+
+---
+
+## Implementation Steps
+
+### 1. Update release metadata
+
+Use the existing release helpers so version fields stay in sync:
+
+```bash
+make bump-version VERSION=0.4.4
+make badge-version TAG=v0.4.4
+python scripts/update_version_badge.py --readme Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md --tag v0.4.4
+```
+
+This updates:
+- `pyproject.toml`
+- `server.json`
+- `README.md` version badge block
+- `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` version badge block
+
+### 2. Add release notes
+
+Update `CHANGELOG.md` with a new `0.4.4` entry that covers:
+- the Xcode approval observation harness and its troubleshooting/docs value (`T-010`)
+- the broker-side synthetic `notifications/tools/list_changed` signal after warm-up (`T-011`)
+
+### 3. Run pre-release quality gates
+
+Run the full local validation suite required by FLOW and `PUBLISHING.md`:
+
+```bash
+pytest tests/ -v --cov=src --cov-report=term
+python -m ruff check src/ tests/
+python -m ruff format --check src/ tests/
+mypy src/
+make doccheck-all
+python -m build
+twine check dist/*
+```
+
+### 4. Record release validation
+
+Write `SPECS/INPROGRESS/P8-T3_Validation_Report.md` with:
+- the exact versions now present in release metadata
+- changelog verification
+- quality gate outcomes
+- explicit post-merge steps for tagging and publish verification
+
+### 5. Post-merge operator steps
+
+These commands must be executed only after the PR merges into `main`:
+
+```bash
+git checkout main
+git pull origin main
+git tag v0.4.4
+git push origin v0.4.4
+```
+
+Then verify:
+- GitHub Actions `publish-mcp.yml` succeeds for `v0.4.4`
+- PyPI serves `mcpbridge-wrapper==0.4.4`
+- the MCP Registry reflects `0.4.4`
+
+---
+
+## Acceptance Criteria
+
+- [ ] `pyproject.toml` contains `version = "0.4.4"`.
+- [ ] `server.json` root `version` and `packages[0].version` both equal `0.4.4`.
+- [ ] `README.md` and `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` version badges reflect `v0.4.4`.
+- [ ] `CHANGELOG.md` contains `[0.4.4] - 2026-03-10` and summarizes `T-010` and `T-011`.
+- [ ] `pytest tests/ -v --cov=src --cov-report=term` passes with coverage >=90%.
+- [ ] `python -m ruff check src/ tests/` passes.
+- [ ] `python -m ruff format --check src/ tests/` passes.
+- [ ] `mypy src/` passes.
+- [ ] `make doccheck-all` passes.
+- [ ] `python -m build` and `twine check dist/*` pass.
+- [ ] Validation report captures the exact post-merge commands and verification steps for `v0.4.4`.
+
+---
+
+## Risk Notes
+
+- `main` is protected. Do not tag or publish from this feature branch; tag only after merge.
+- `make badge-version` must be called with explicit `TAG=v0.4.4` so it does not reuse `v0.4.3`.
+- The release notes must stay scoped to work already merged after `v0.4.3`; do not pull in unmerged follow-ups or future publish verification results.
+
+---
+**Archived:** 2026-03-10
+**Verdict:** PASS

SPECS/ARCHIVE/P8-T3_Prepare_for_Release_0.4.4/P8-T3_Validation_Report.md

@@ -0,0 +1,65 @@
+# P8-T3 Validation Report — Prepare for Release 0.4.4
+
+**Date:** 2026-03-10
+**Branch:** `codex/feature/P8-T3-prepare-release-0.4.4`
+**Python:** `3.10.19`
+**Verdict:** PASS
+
+---
+
+## Deliverables Checklist
+
+| Deliverable | Status | Detail |
+|-------------|--------|--------|
+| `pyproject.toml` version = `0.4.4` | ✅ PASS | Updated via `make bump-version VERSION=0.4.4` |
+| `server.json` root `version` = `0.4.4` | ✅ PASS | Updated by `scripts/publish_helper.py` |
+| `server.json` `packages[0].version` = `0.4.4` | ✅ PASS | Updated by `scripts/publish_helper.py` |
+| `README.md` badge updated to `v0.4.4` | ✅ PASS | Updated via `make badge-version TAG=v0.4.4` |
+| `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` badge updated to `v0.4.4` | ✅ PASS | Synced via `python scripts/update_version_badge.py --readme ... --tag v0.4.4` |
+| `CHANGELOG.md` contains `[0.4.4] - 2026-03-10` | ✅ PASS | Added release notes for `T-010` and `T-011` |
+
+---
+
+## Quality Gates
+
+| Gate | Result | Detail |
+|------|--------|--------|
+| `pytest tests/ -v --cov=src --cov-report=term` | ✅ PASS | `923 passed, 5 skipped, 2 warnings in 28.60s` |
+| Coverage >= 90% | ✅ PASS | Total coverage: **91.62%** |
+| `python -m ruff check src/ tests/` | ✅ PASS | All checks passed |
+| `python -m ruff format --check src/ tests/` | ✅ PASS | `56 files already formatted` |
+| `mypy src/` | ✅ PASS | `Success: no issues found in 20 source files` |
+| `make doccheck-all` | ✅ PASS | README and DocC overview stayed in sync across unstaged, staged, and branch scopes |
+| `python -m build` | ✅ PASS | Built `dist/mcpbridge_wrapper-0.4.4.tar.gz` and `dist/mcpbridge_wrapper-0.4.4-py3-none-any.whl` |
+| `twine check dist/*` | ✅ PASS | Wheel and sdist metadata both passed |
+
+---
+
+## Release Notes Scope
+
+`0.4.4` is prepared as a patch release for the work merged after `v0.4.3`:
+
+- `T-010` adds the Xcode approval observation harness so approval-race behavior can be captured as timestamped MCP traces during troubleshooting and validation.
+- `T-011` adds a broker-side synthetic `notifications/tools/list_changed` signal when the warmed tool catalog first becomes usable, and only re-emits it when a later reconnect changes the non-empty catalog.
+
+---
+
+## Remaining Steps (post-merge)
+
+The following steps are intentionally deferred until the PR merges into `main`:
+
+1. `git checkout main`
+2. `git pull origin main`
+3. `git tag v0.4.4`
+4. `git push origin v0.4.4`
+5. Verify GitHub Actions `publish-mcp.yml` for `v0.4.4` completes successfully
+6. Verify `https://pypi.org/project/mcpbridge-wrapper/0.4.4/` is live
+7. Verify the MCP Registry reflects `0.4.4`
+
+These checks are acceptance criteria that cannot be completed on the feature branch without publishing from the wrong ref.
+
+---
+
+## Summary
+
+All pre-merge release-preparation deliverables are complete. Version metadata is consistent across package metadata, MCP Registry manifest, README, and DocC overview; the changelog captures the shipped work; and the full local validation suite required by FLOW and `PUBLISHING.md` passed.

SPECS/ARCHIVE/P8-T3_Prepare_for_Release_0.4.4/REVIEW_release_0.4.4_preparation.md

@@ -0,0 +1,34 @@
+## REVIEW REPORT — release_0.4.4_preparation
+
+**Scope:** `origin/main..HEAD`
+**Files:** 10
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+
+- None.
+
+### Secondary Issues
+
+- None.
+
+### Architectural Notes
+
+- The release-preparation branch keeps publish side effects out of scope for the PR itself, which matches the protected-`main` workflow documented in `CONTRIBUTING.md` and `PUBLISHING.md`.
+- README and DocC overview version badges were updated together, so the branch remains compatible with `make doccheck-all`.
+- `CHANGELOG.md` stays narrowly scoped to the work merged after `v0.4.3`, which keeps the `0.4.4` patch release reviewable and avoids over-reporting unpublished work.
+
+### Tests
+
+- `pytest tests/ -v --cov=src --cov-report=term` passed with `923 passed, 5 skipped, 2 warnings` and `91.62%` total coverage.
+- `python -m ruff check src/ tests/`, `python -m ruff format --check src/ tests/`, `mypy src/`, `make doccheck-all`, `python -m build`, and `twine check dist/*` all passed.
+
+### Next Steps
+
+- No actionable review findings. FOLLOW-UP is skipped.
+- After merge, run the documented `git tag v0.4.4` / `git push origin v0.4.4` sequence on `main` and verify the `publish-mcp.yml` workflow, PyPI package page, and MCP Registry entry.

SPECS/INPROGRESS/next.md

@@ -4,11 +4,12 @@
 
 No active task is selected in `SPECS/INPROGRESS/`.
 
-The most recently completed task was `T-011 — Emit synthetic broker tools/list_changed on catalog warm-up`,
+The most recently completed task was `P8-T3 — Prepare for Release 0.4.4`,
 archived on `2026-03-10` with verdict `PASS`.
 
 ## Recently Archived
 
+- `2026-03-10` — `P8-T3` archived with verdict `PASS`
 - `2026-03-10` — `T-011` archived with verdict `PASS`
 - `2026-03-10` — `T-010` archived with verdict `PASS`
 - `2026-03-10` — `P8-T2` archived with verdict `PASS`
@@ -18,16 +19,15 @@ archived on `2026-03-10` with verdict `PASS`.
 - `2026-03-07` — `P7-T5` archived with verdict `PASS`
 - `2026-03-07` — `P7-T4` archived with verdict `PASS`
 - `2026-03-07` — `FU-P7-T3-2` archived with verdict `PASS`
-- `2026-03-07` — `FU-P7-T3-1` archived with verdict `PASS`
 
 ## Post-Merge Action Required
 
-After the `P8-T2` PR merges to `main`, push the release tag to trigger publishing:
+After the `P8-T3` PR merges to `main`, push the release tag to trigger publishing:
 
 ```bash
 git checkout main && git pull origin main
-git tag v0.4.3
-git push origin v0.4.3
+git tag v0.4.4
+git push origin v0.4.4
 ```
 
 Then verify GitHub Actions `publish-mcp.yml` completes successfully.

SPECS/Workplan.md

@@ -662,3 +662,25 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - [ ] Git tag `v0.4.3` exists on `origin/main` (post-merge)
   - [ ] `https://pypi.org/project/mcpbridge-wrapper/0.4.3/` is accessible (post-merge)
   - [ ] GitHub Actions `publish-mcp.yml` run for tag `v0.4.3` shows all steps green (post-merge)
+
+#### ✅ P8-T3: Prepare for Release 0.4.4
+- **Status:** ✅ Completed (2026-03-10)
+- **Description:** Prepared patch release `0.4.4` for the work merged after `v0.4.3`, covering the Xcode approval observation harness (`T-010`) and the broker-side synthetic `notifications/tools/list_changed` warm-up notification (`T-011`). Bumped release metadata to `0.4.4`, synced the README and DocC overview badges, added changelog release notes, and validated the full local pre-release gate suite from `PUBLISHING.md`. Tagging and publication remain post-merge actions on `main`.
+- **Priority:** P0
+- **Dependencies:** none
+- **Parallelizable:** no
+- **Outputs/Artifacts:**
+  - `pyproject.toml` — version set to `0.4.4`
+  - `server.json` — root and package versions set to `0.4.4`
+  - `README.md` and `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` — version badges updated to `v0.4.4`
+  - `CHANGELOG.md` — `[0.4.4]` entry added for `T-010` and `T-011`
+  - `SPECS/ARCHIVE/P8-T3_Prepare_for_Release_0.4.4/` — archived PRD + validation report
+  - (Post-merge, human action) `git tag v0.4.4` push triggers PyPI + MCP Registry publish
+- **Acceptance Criteria:**
+  - [x] `pyproject.toml` and `server.json` both contain version `0.4.4`
+  - [x] `README.md` and `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` both reflect `v0.4.4`
+  - [x] `CHANGELOG.md` contains a `[0.4.4]` entry dated `2026-03-10` covering `T-010` and `T-011`
+  - [x] `pytest tests/ -v --cov=src --cov-report=term`, `ruff check src/ tests/`, `ruff format --check src/ tests/`, `mypy src/`, `make doccheck-all`, `python -m build`, and `twine check dist/*` all pass
+  - [ ] Git tag `v0.4.4` exists on `origin/main` (post-merge)
+  - [ ] `https://pypi.org/project/mcpbridge-wrapper/0.4.4/` is accessible (post-merge)
+  - [ ] GitHub Actions `publish-mcp.yml` run for tag `v0.4.4` shows all steps green (post-merge)

Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md

@@ -8,7 +8,7 @@ Model Context Protocol (MCP).
 [https://github.com/SoundBlaster/XcodeMCPWrapper](https://github.com/SoundBlaster/XcodeMCPWrapper)
 
 <!-- version-badge:start -->
-[![Version](https://img.shields.io/badge/version-0.4.3-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.3)
+[![Version](https://img.shields.io/badge/version-0.4.4-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.4.4)
 <!-- version-badge:end -->
 
 ## Overview

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcpbridge-wrapper"
-version = "0.4.3"
+version = "0.4.4"
 description = "Python wrapper for xcrun mcpbridge that adds structuredContent to MCP responses"
 readme = "README.md"
 requires-python = ">=3.9"

server.json

@@ -3,7 +3,7 @@
   "name": "io.github.SoundBlaster/xcode-mcpbridge-wrapper",
   "title": "Xcode: MCP Bridge Wrapper for Cursor",
   "description": "Python wrapper that makes Xcode's MCP bridge compatible with strict MCP clients like Cursor",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "repository": {
     "url": "https://github.com/SoundBlaster/XcodeMCPWrapper",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "mcpbridge-wrapper",
-      "version": "0.4.3",
+      "version": "0.4.4",
       "transport": {
         "type": "stdio"
       },