SoundBlaster · SoundBlaster · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
 # Makefile for mcpbridge-wrapper
 
-.PHONY: help install install-webui test test-webui lint format format-check typecheck doccheck doccheck-staged doccheck-branch doccheck-all doccheck-all-strict package-assets-check bump-version clean webui webui-restart webui-health check
+.PHONY: help install install-webui test test-webui lint format format-check typecheck doccheck doccheck-staged doccheck-branch doccheck-all doccheck-all-strict package-assets-check bump-version badge-version badge-version-check clean webui webui-restart webui-health check
 
 help:
 	@echo "Available targets:"
@@ -19,6 +19,8 @@ help:
 	@echo "  doccheck-all-strict - Same as doccheck-all + require doc/docc updates in same commit on branch scope"
 	@echo "  package-assets-check - Build artifacts and verify required packaged assets"
 	@echo "  bump-version   - Update pyproject.toml and server.json versions (VERSION=x.y.z, add DRY_RUN=1 to preview)"
+	@echo "  badge-version  - Update README version badge (latest tag or TAG=vX.Y.Z; add DRY_RUN=1 to preview)"
+	@echo "  badge-version-check - Fail if README version badge does not match latest tag"
 	@echo "  webui          - Start wrapper with Web UI dashboard (port 8080)"
 	@echo "  webui-restart  - Restart Web UI dashboard on chosen port (PORT=8080 by default)"
 	@echo "  webui-health   - Check Web UI health status"
@@ -89,6 +91,24 @@ bump-version:
 		python scripts/publish_helper.py $(VERSION); \
 	fi
 
+badge-version:
+	@if [ -n "$(TAG)" ]; then \
+		if [ -n "$(DRY_RUN)" ]; then \
+			python scripts/update_version_badge.py --tag "$(TAG)" --dry-run; \
+		else \
+			python scripts/update_version_badge.py --tag "$(TAG)"; \
+		fi; \
+	else \
+		if [ -n "$(DRY_RUN)" ]; then \
+			python scripts/update_version_badge.py --dry-run; \
+		else \
+			python scripts/update_version_badge.py; \
+		fi; \
+	fi
+
+badge-version-check:
+	python scripts/update_version_badge.py --check
+
 check: test lint format-check typecheck doccheck-all package-assets-check
 
 clean:

diff --git a/README.md b/README.md
@@ -2,11 +2,16 @@
 
 <!-- mcp-name: io.github.SoundBlaster/xcode-mcpbridge-wrapper -->
 
+<!-- version-badge:start -->
+[![Version](https://img.shields.io/badge/version-0.3.3-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.3.3)
+<!-- 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)
 [![Coverage](https://img.shields.io/badge/coverage-92.19%25-brightgreen.svg)](./SPECS/ARCHIVE/P5-T14_Code_Coverage/)
 [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.SoundBlaster%2Fxcode--mcpbridge--wrapper-blue)](https://registry.modelcontextprotocol.io)
 
+Version badge maintenance: run `make badge-version` (or `make badge-version-check` in CI).
+
 A Python wrapper that makes Xcode 26.3's MCP bridge compatible with Cursor and other strict MCP-spec-compliant clients.
 
 ## The Problem

diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-03-01 (Workplan_0.4.0.md)
+**Last Updated:** 2026-02-28 (P1-T1)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| 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 |
 | FU-P13-T18 | [FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/](FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/) | 2026-02-28 | PASS |
@@ -168,6 +169,7 @@
 | File | Description |
 |------|-------------|
 | [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_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 |
@@ -510,3 +512,5 @@
 | 2026-02-20 | BUG-T17 | Archived REVIEW_bug_t17_audit_log_rows_stay_unfolded report |
 | 2026-02-20 | BUG-T14 | Archived Rows_in_Per-Tool_Latency_Statistics_fold_automatically_immediately_after_unfolding (PASS) |
 | 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 |
diff --git a/...dd_the_version_badge_in_the_README/P1-T1_Add_the_version_badge_in_the_README.md b/...dd_the_version_badge_in_the_README/P1-T1_Add_the_version_badge_in_the_README.md
@@ -0,0 +1,52 @@
+# P1-T1 — Add the version badge in the README.md
+
+**Task ID:** P1-T1  
+**Phase:** Phase 1: Documentation  
+**Priority:** P2  
+**Dependencies:** none  
+**Status:** Planned
+
+## Objective
+
+Implement maintainable automation for the README version badge so it can be updated from git tags with a small, test-covered script and ergonomic `make` commands.
+
+## Success Criteria
+
+- `README.md` contains a version badge wrapped in stable start/end markers.
+- `scripts/update_version_badge.py` updates only the marker block using either `--tag` or latest tag.
+- Script behavior is covered by unit tests for success and failure paths.
+- `Makefile` exposes update and check commands for local/CI usage.
+- Quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` with coverage >= 90%.
+
+## Test-First Plan
+
+1. Add tests for tag normalization, badge block rendering, marker replacement, and check/update flows.
+2. Refactor script internals to reduce function complexity and keep logic focused/testable.
+3. Run targeted script tests, then full project quality gates.
+
+## Execution Plan
+
+### Phase A: Script Refactor
+- **Inputs:** current `scripts/update_version_badge.py`, README marker contract
+- **Outputs:** smaller helper functions, clearer error paths, idempotent update behavior
+- **Verification:** unit tests for pure helpers and CLI behavior
+
+### Phase B: Test Coverage
+- **Inputs:** script contract and expected README badge format
+- **Outputs:** `tests/unit/test_update_version_badge.py`
+- **Verification:** `pytest tests/unit/test_update_version_badge.py -v`
+
+### Phase C: Integration and Tooling
+- **Inputs:** updated script and `Makefile`
+- **Outputs:** validated `badge-version` / `badge-version-check` commands
+- **Verification:** dry-run and check command execution; full quality-gate run
+
+## Notes
+
+- Keep implementation dependency-free and Python 3.9-compatible.
+- Preserve unrelated README badges and formatting.
+- Do not rewrite the full README file when marker block is unchanged.
+
+---
+**Archived:** 2026-02-28
+**Verdict:** PASS
diff --git a/SPECS/ARCHIVE/P1-T1_Add_the_version_badge_in_the_README/P1-T1_Validation_Report.md b/SPECS/ARCHIVE/P1-T1_Add_the_version_badge_in_the_README/P1-T1_Validation_Report.md
@@ -0,0 +1,47 @@
+# Validation Report — P1-T1: Add the version badge in the README.md
+
+**Date:** 2026-02-28  
+**Verdict:** PASS
+
+## Scope
+
+Implemented README version badge automation with `make` helpers, refactored the badge update script into a plan/apply flow, and added dedicated unit tests for the new script behavior.
+
+## Deliverables
+
+- `README.md` updated with marker-wrapped version badge block
+- `Makefile` updated with `badge-version` and `badge-version-check` targets
+- `scripts/update_version_badge.py` created and refactored for testability
+- `tests/unit/test_update_version_badge.py` created with explicit script behavior coverage
+
+## Acceptance Criteria Check
+
+- [x] `README.md` includes a visible version badge near the heading/badges area
+- [x] Badge links to canonical GitHub release tag page
+- [x] Script updates/checks badge from explicit or latest tag
+- [x] Script has dedicated unit tests for core and CLI behavior
+
+## Commands Executed
+
+- `pytest tests/unit/test_update_version_badge.py -v`
+- `python3 -m ruff check --fix scripts/update_version_badge.py tests/unit/test_update_version_badge.py`
+- `python3 -m ruff check scripts/update_version_badge.py tests/unit/test_update_version_badge.py`
+- `PYTHONPATH=src pytest`
+- `python3 -m ruff check src/`
+- `mypy src/`
+- `PYTHONPATH=src pytest --cov`
+- `make badge-version-check`
+
+## Results
+
+- Targeted script tests: PASS (`18 passed`)
+- Script/test linting: PASS
+- `pytest`: PASS (`715 passed, 5 skipped`)
+- `ruff check src/`: PASS
+- `mypy src/`: PASS (`18 source files checked`)
+- `pytest --cov`: PASS (`Total coverage: 91.72%`, threshold 90%)
+- `make badge-version-check`: PASS (`README version badge already up to date (v0.3.3)`)
+
+## Notes
+
+- Running plain `pytest` without `PYTHONPATH=src` failed in this environment due `ModuleNotFoundError: mcpbridge_wrapper` during collection. Re-running with `PYTHONPATH=src` resolved the environment issue and all tests passed.
diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_p1_t1_version_badge_script_tests.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t1_version_badge_script_tests.md
@@ -0,0 +1,32 @@
+## REVIEW REPORT — P1-T1 Version Badge Script + Tests
+
+**Scope:** origin/main..HEAD  
+**Files:** 9
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+
+- None.
+
+### Secondary Issues
+
+- None requiring follow-up tasks.
+
+### Architectural Notes
+
+- The script uses a clean plan/apply split (`plan_badge_update` + `apply_badge_update`) that makes file mutation deterministic and CLI flags (`--check`, `--dry-run`) straightforward to reason about and test.
+- Marker-based replacement in `README.md` keeps edits scoped and avoids touching unrelated badges.
+
+### Tests
+
+- New unit suite `tests/unit/test_update_version_badge.py` covers tag normalization, marker replacement, plan generation, apply/check/dry-run modes, and main CLI flows.
+- Full suite and coverage were re-run successfully during EXECUTE (`715 passed, 5 skipped`, coverage `91.72%`).
+
+### 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,10 +2,11 @@
 
 ## Recently Archived
 
+- **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 (146/146)
+- **None** — All tasks completed (1/1)
diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -10,3 +10,20 @@ The previous workplan for release `0.4.0` was archived at:
 
 This file is intentionally reset for the next planning cycle.
 Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.md).
+
+## Tasks
+
+### Phase 1: Documentation
+
+#### ✅ P1-T1: Add the version badge in the README.md
+- **Status:** ✅ Completed (2026-02-28)
+- **Description:** Add a package version badge to `README.md` so users can quickly see the currently published version.
+- **Priority:** P2
+- **Dependencies:** none
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - `README.md` badge section updated with a version badge
+  - Badge target URL configured to an authoritative version source
+- **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
diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md
@@ -6,6 +6,12 @@ A Python wrapper that enables external AI agents to connect to Xcode via the Mod
 
 [https://github.com/SoundBlaster/XcodeMCPWrapper](https://github.com/SoundBlaster/XcodeMCPWrapper)
 
+<!-- version-badge:start -->
+[![Version](https://img.shields.io/badge/version-0.3.3-blue.svg)](https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.3.3)
+<!-- version-badge:end -->
+
+Version badge maintenance: run `make badge-version` (or `make badge-version-check` in CI).
+
 ## Overview
 
 Xcode 26.3+ includes an MCP bridge (`xcrun mcpbridge`) that exposes Xcode's internal capabilities to MCP clients. However, it has a protocol compatibility issue that prevents it from working with strict MCP spec followers like Cursor.