feat: add plugin-doctor plugin for weekly update warnings

.claude-plugin/marketplace.json

@@ -59,6 +59,12 @@
       "description": "Hypothesis-first experiment workflow — scaffolding, eval packs, results, verdicts, and the two-commit discipline",
       "source": "./plugins/experiments",
       "category": "development"
+    },
+    {
+      "name": "plugin-doctor",
+      "description": "Warns when installed agentic-primitives plugins have updates available, checked weekly. Never auto-updates.",
+      "source": "./plugins/plugin-doctor",
+      "category": "observability"
     }
   ]
 }

.gitignore

@@ -5,6 +5,9 @@ build/
 dist/
 target/
 
+# Local git worktrees
+.worktrees/
+
 
 # Python
 __pycache__/

CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 🩺 plugin-doctor
+
+A new plugin that warns when installed `agentic-primitives` plugins have updates available.
+
+#### Added
+
+- **`plugins/plugin-doctor/`** — `SessionStart` hook compares installed plugin versions (from `~/.claude/plugins/cache/agentic-primitives/`) against the marketplace catalog (from `~/.claude/plugins/marketplaces/agentic-primitives/`), refreshing the catalog at most once a week. Emits `additionalContext` naming outdated plugins when found; instructs Claude to ask the user before updating anything. Never runs `claude plugin update` itself.
+- **37 unit/integration tests** in `tests/unit/claude/hooks/test_plugin_doctor.py` covering state I/O, cadence gating, semver comparison, and the handler end-to-end via subprocess.
+
 ### 🏗 Workspace Injection Contract (ADR-035)
 
 A small, cross-orchestrator file-injection seam that any consumer of the workspace image (agentic-domain-runner, Syntropic137, future Codex/Gemini wrappers) can target.

README.md

@@ -154,6 +154,7 @@ Replace `sdlc` with any plugin name from the [Available Plugins](#available-plug
 | **observability** | `claude plugin install observability@agentic-primitives --scope user` | Full-spectrum JSONL event observability |
 | **delegation** | `claude plugin install delegation@agentic-primitives --scope user` | Delegating work — `claude -p`, Codex, and session handoffs |
 | **experiments** | `claude plugin install experiments@agentic-primitives --scope user` | Hypothesis-first experiment workflow |
+| **plugin-doctor** | `claude plugin install plugin-doctor@agentic-primitives --scope user` | Warns when installed plugins are outdated |
 
 ### What's in each plugin
 
@@ -168,6 +169,7 @@ Replace `sdlc` with any plugin name from the [Available Plugins](#available-plug
 | **observability** | -- | -- | -- | All 14 lifecycle events → structured JSONL via agentic_events |
 | **delegation** | -- | `delegating-to-claude-p`, `delegating-to-codex`, `writing-handoffs` | -- | -- |
 | **experiments** | -- | `running-experiments` | -- | -- |
+| **plugin-doctor** | -- | -- | -- | SessionStart plugin-freshness check (weekly, never auto-updates) |
 
 ---