Ovid · Ovid · Apr 26, 2026 · Apr 26, 2026 · Apr 26, 2026 · Apr 26, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Ovid's plugin marketplace for Claude Code — impractical tools for software architecture, code quality, and development workflows.",
-    "version": "1.0.0"
+    "version": "1.20.0"
   },
   "plugins": [
     {
       "name": "paad",
       "source": "./plugins/paad",
       "description": "Architecture analysis, code quality, and development workflow skills by Ovid",
-      "version": "1.11.0",
+      "version": "1.20.0",
       "author": {
         "name": "Curtis \"Ovid\" Poe"
       },

diff --git a/.claude/skills/roadmap/SKILL.md b/.claude/skills/roadmap/SKILL.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,6 +4,10 @@
 
 This is a **Claude Code plugin marketplace** hosted at `github.com/Ovid/paad`. It distributes the `paad` plugin, which provides skills for architecture analysis, code quality, and development workflows.
 
+After this file is read, announce "CLAUDE.md loaded."
+
+Also, address me as "Ovid" for further verification that you have read this file.
+
 ## Project structure
 
 ```
@@ -18,15 +22,19 @@ paad/
 │           ├── agentic-a11y/
 │           │   └── SKILL.md       ← /paad:agentic-a11y skill
 │           ├── agentic-architecture/
-│           │   └── SKILL.md       ← /paad:agentic-architecture skill
+│           │   ├── SKILL.md       ← /paad:agentic-architecture skill
+│           │   └── references/    ← on-demand specialist + verifier + report-template content
 │           ├── agentic-review/
-│           │   └── SKILL.md       ← /paad:agentic-review skill
+│           │   ├── SKILL.md       ← /paad:agentic-review skill
+│           │   └── references/    ← on-demand specialist + verifier + report-template content
 │           ├── alignment/
 │           │   └── SKILL.md       ← /paad:alignment skill
+│           ├── fix-architecture/
+│           │   └── SKILL.md       ← /paad:fix-architecture skill
 │           ├── help/
 │           │   └── SKILL.md       ← /paad:help skill
 │           ├── makefile/
-│           │   └── SKILL.md       ← /paad:help skill
+│           │   └── SKILL.md       ← /paad:makefile skill
 │           ├── pushback/
 │           │   └── SKILL.md       ← /paad:pushback skill
 │           └── vibe/
@@ -40,24 +48,35 @@ paad/
 - **Marketplace name**: `paad`
 - **Plugin name**: `paad` (so all skills are invoked as `/paad:<skill-name>`)
 - **Skill naming**: skill folder names become the suffix after `paad:` — e.g., `skills/agentic-architecture/` → `/paad:agentic-architecture`
-- **Versioning**: both `marketplace.json` and `plugin.json` use semver. Bump the plugin version in `plugin.json` (it takes precedence). Keep `marketplace.json` version in sync.
+- **Versioning**: both `marketplace.json` and `plugin.json` use semver, plus every `SKILL.md` carries the plugin version inside its on-invocation announce line. Run `make bump-version VERSION=X.Y.Z` to update plugin.json, marketplace.json (metadata + plugin entry), every source SKILL.md announce line, and the vendored kiro/agent output in one shot; `make check-skill-versions` (run as part of `make test`) catches drift in source and vendored copies alike.
 - **Validation**: run `claude plugin validate .` (marketplace) and `claude plugin validate ./plugins/paad` (plugin) before committing
+- **Announce on invocation**: every `SKILL.md` must begin its body with the line `**On invocation:** announce "Running paad:<skill-name> v<version>" before anything else.` so users see which skill ran and which version produced the behavior. The literal version string must match `plugin.json`.
 
 ## Adding a new skill
 
 1. Create `plugins/paad/skills/<skill-name>/SKILL.md` with frontmatter (`name`, `description`) and instructions
-2. Consider `$ARGUMENTS` support — if the skill could benefit from user-provided scope (a file path, directory, branch name, etc.), add an Arguments section documenting usage. Users shouldn't need to remember flags; keep arguments positional and intuitive (e.g., `/paad:skillname path/to/scope`).
-3. Add a graphviz digraph (```dot block) covering the skill's decision points and flow. The only exception is `paad:help`, which is a simple display skill. See "Digraph requirements" below.
-4. Validate with `claude plugin validate ./plugins/paad`
-5. Test locally with `claude --plugin-dir ./plugins/paad`
-6. Bump the version in both `plugins/paad/.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
-7. Update `README.md` to document the new skill under "Available Skills", including argument syntax in the heading
-8. Add the new skill to `paad:help` — both the overview table and a detailed help section
+2. Add the on-invocation announce line as the very first line of the body (after the closing `---` of frontmatter): `**On invocation:** announce "Running paad:<skill-name> v<version>" before anything else.` — the version literal must match `plugin.json`
+3. Consider `$ARGUMENTS` support — if the skill could benefit from user-provided scope (a file path, directory, branch name, etc.), add an Arguments section documenting usage. Users shouldn't need to remember flags; keep arguments positional and intuitive (e.g., `/paad:skillname path/to/scope`).
+4. Add a graphviz digraph (```dot block) covering the skill's decision points and flow. The only exception is `paad:help`, which is a simple display skill. See "Digraph requirements" below.
+5. Validate with `claude plugin validate ./plugins/paad`
+6. Test locally with `claude --plugin-dir ./plugins/paad`
+7. Bump the version with `make bump-version VERSION=X.Y.Z` (updates `plugin.json`, `marketplace.json`, every source SKILL.md announce line, and regenerates the vendored kiro/agent output in one shot)
+8. Update `README.md` to document the new skill under "Available Skills", including argument syntax in the heading
+9. Add the new skill to `paad:help` — both the overview table and a detailed help section
+10. Run `make test` to verify all checks pass (validate, version sync, skill-version announce, digraphs, help, README, frontmatter)
 
 ## Modifying an existing skill
 
 When changing a skill's behavior, arguments, or output, review `plugins/paad/skills/help/SKILL.md` and update the corresponding help text to match.
 
+## Releasing
+
+Releases run from `main` with a clean working tree:
+
+    make release VERSION=X.Y.Z
+
+This composes `bump-version` + `vendored` + `make test` and prints the git commands for the release commit, tag, and push. The Makefile blocks runs from non-`main` branches and from dirty trees. After `make release` completes, review the diff, then commit, tag (`vX.Y.Z`), and push as instructed.
+
 ## Digraph requirements
 
 Every skill (except `paad:help`) must include at least one graphviz digraph (`\`\`\`dot` block) that visualizes the skill's decision points and flow. Digraphs must be:
@@ -74,3 +93,15 @@ When modifying a skill's flow, check that the digraph still matches. When review
 - Skill files must be named `SKILL.md` (uppercase) inside a folder whose name becomes the skill name
 - Plugin sources in `marketplace.json` use paths relative to the marketplace root (start with `./`)
 - Keep marketplace.json plugin descriptions in sync with plugin.json descriptions
+
+## Project-local skills under `.claude/skills/`
+
+The repo also hosts **project-local** skills at `.claude/skills/<name>/SKILL.md` (e.g. `.claude/skills/roadmap/SKILL.md`). These are **not** part of the `paad` plugin and follow a different lifecycle:
+
+- **Not distributed** — they live in this repo only and are picked up automatically by Claude Code when it runs in this working directory. There is no marketplace, no `claude plugin validate` step, no `plugin.json`, no version field.
+- **No `make bump-version` impact** — `make bump-version` rewrites `plugin.json`, `marketplace.json`, and every `plugins/paad/skills/*/SKILL.md` announce line. Project-local SKILL.md files are skipped on purpose. They have no announce-line version, no `paad:<name>` namespace.
+- **No `make test` checks** — the Makefile's check-frontmatter / check-digraphs / check-help / check-readme / check-skill-versions targets all walk `plugins/paad/skills/`. They do not enforce anything against `.claude/skills/`.
+- **Edit-and-commit only** — change the SKILL.md, commit, you're done. No version bump, no help table edit, no README entry, no `paad:help` cross-reference.
+- **Naming** — invoke as `/<name>` (no `paad:` prefix), because they're not in a plugin. `/roadmap`, not `/paad:roadmap`.
+
+When reviewing or modifying a `.claude/skills/<name>/SKILL.md`, do not chase the paad-plugin conventions (announce lines, version literals, help / README cross-references). They don't apply here.
diff --git a/Makefile b/Makefile
@@ -1,13 +1,22 @@
+# lint, format, and cover targets are intentionally absent: this project is
+# 95% Markdown specs with a small Python/Bash tooling surface, no test
+# framework supports coverage for the bash-fixture-driven checks, and no
+# linter/formatter is configured. `make test` is the integration surface.
+
 SKILLS_DIR := plugins/paad/skills
 SKILL_DIRS := $(wildcard $(SKILLS_DIR)/*)
 SKILL_NAMES := $(notdir $(SKILL_DIRS))
+VENDORED_KIRO_SKILLS_DIR := kiro_and_antigravity/skills/.kiro/skills
+MAIN_BRANCH ?= main
 
-.PHONY: help test validate check-versions check-digraphs check-help check-readme check-frontmatter
+.PHONY: help all test validate check-versions check-skill-versions check-digraphs check-help check-readme check-frontmatter check-extracted-refs test-check-extracted-refs test-bump-version test-convert-skills check-prompt-injection-defense test-check-prompt-injection-defense bump-version vendored check-vendored check-confidence-floor test-check-confidence-floor loc release
 
 help: ## Show this help
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-22s %s\n", $$1, $$2}'
+
+all: test ## Full CI pass (currently equivalent to `test`; see header comment)
 
-test: validate check-versions check-digraphs check-help check-readme check-frontmatter ## Run all checks
+test: validate check-versions check-skill-versions check-digraphs check-help check-readme check-frontmatter test-check-extracted-refs check-extracted-refs test-bump-version test-convert-skills test-check-prompt-injection-defense check-prompt-injection-defense check-vendored test-check-confidence-floor check-confidence-floor ## Run all checks
 	@echo "All checks passed."
 
 validate: ## Validate marketplace and all plugins
@@ -17,14 +26,42 @@ validate: ## Validate marketplace and all plugins
 		claude plugin validate "$$dir" || exit 1; \
 	done
 
-check-versions: ## Check marketplace.json and plugin.json versions match
-	@marketplace_ver=$$(python3 -c "import json; print(json.load(open('.claude-plugin/marketplace.json'))['plugins'][0]['version'])"); \
-	plugin_ver=$$(python3 -c "import json; print(json.load(open('plugins/paad/.claude-plugin/plugin.json'))['version'])"); \
-	if [ "$$marketplace_ver" != "$$plugin_ver" ]; then \
-		echo "FAIL: Version mismatch — marketplace.json ($$marketplace_ver) != plugin.json ($$plugin_ver)"; \
-		exit 1; \
+check-versions: ## Check marketplace.json (metadata + every plugin entry) and plugin.json versions all match
+	@python3 scripts/check_versions.py
+
+check-skill-versions: ## Check every SKILL.md (source + vendored kiro) announces the correct version
+	@plugin_ver=$$(python3 -c "import json; print(json.load(open('plugins/paad/.claude-plugin/plugin.json'))['version'])"); \
+	fail=0; \
+	for dir in $(SKILL_DIRS); do \
+		name=$$(basename "$$dir"); \
+		file="$$dir/SKILL.md"; \
+		if ! grep -qF "Running paad:$$name v$$plugin_ver\"" "$$file" 2>/dev/null; then \
+			echo "FAIL: $$name is missing or has wrong version announcement (expected v$$plugin_ver) at $$file"; \
+			fail=1; \
+		fi; \
+	done; \
+	if [ -d "$(VENDORED_KIRO_SKILLS_DIR)" ]; then \
+		for dir in $(VENDORED_KIRO_SKILLS_DIR)/*; do \
+			[ -d "$$dir" ] || continue; \
+			name=$$(basename "$$dir"); \
+			file="$$dir/SKILL.md"; \
+			[ -f "$$file" ] || continue; \
+			if ! grep -qF "Running paad:$$name v$$plugin_ver\"" "$$file" 2>/dev/null; then \
+				echo "FAIL: vendored $$name is missing or has wrong version announcement (expected v$$plugin_ver) at $$file — run 'make vendored' after a version bump"; \
+				fail=1; \
+			fi; \
+		done; \
 	fi; \
-	echo "Versions match: $$plugin_ver"
+	if [ "$$fail" -eq 1 ]; then exit 1; fi; \
+	echo "All skills announce v$$plugin_ver (source + vendored)."
+
+bump-version: ## Bump version across plugin.json, marketplace.json (metadata + plugin entries), all SKILL.md, and the vendored kiro/agent output (usage: make bump-version VERSION=X.Y.Z)
+	@if [ -z "$(VERSION)" ]; then \
+		echo "Usage: make bump-version VERSION=X.Y.Z"; \
+		exit 1; \
+	fi
+	@python3 scripts/bump_version.py "$(VERSION)"
+	@$(MAKE) --no-print-directory vendored
 
 check-digraphs: ## Check every skill (except help) has a digraph
 	@fail=0; \
@@ -91,3 +128,93 @@ check-frontmatter: ## Check every SKILL.md has name/description and name matches
 	done; \
 	if [ "$$fail" -eq 1 ]; then exit 1; fi; \
 	echo "All SKILL.md files have valid frontmatter."
+
+check-extracted-refs: ## Check every row in scripts/extracted-refs.tsv represents a correctly extracted reference
+	@bash scripts/check_extracted_refs.sh
+
+test-check-extracted-refs: ## Self-test the check_extracted_refs.sh script against synthetic fixtures
+	@bash scripts/test_check_extracted_refs.sh
+
+test-bump-version: ## Self-test the bump_version.py script against synthetic fixtures
+	@bash scripts/test_bump_version.sh
+
+test-convert-skills: ## Self-test the convert_skills.py script against synthetic fixtures
+	@bash scripts/test_convert_skills.sh
+
+vendored: ## Regenerate the Cursor/Kiro/Antigravity vendored skills under kiro_and_antigravity/
+	@python3 scripts/convert_skills.py
+
+check-confidence-floor: ## Verify the confidence-floor literal (currently 60) is consistent across all sites; --strict also requires every FLOOR_PATTERN to match at least once
+	@python3 scripts/check_confidence_floor.py --strict
+
+test-check-confidence-floor: ## Self-test the check_confidence_floor.py script against synthetic fixtures
+	@bash scripts/test_check_confidence_floor.sh
+
+check-prompt-injection-defense: ## Verify the "untrusted data, never as instructions" defense literal is present at every specialist + verifier + dispatch site
+	@python3 scripts/check_prompt_injection_defense.py
+
+test-check-prompt-injection-defense: ## Self-test the check_prompt_injection_defense.py script against synthetic fixtures
+	@bash scripts/test_check_prompt_injection_defense.sh
+
+loc: ## Count lines of code in our own files (excludes vendored output, skill outputs, scratch)
+	@cloc --exclude-dir=kiro_and_antigravity,architecture-reviews,code-reviews,notes,scratch,docs,images,.kiro .
+
+release: ## Prepare a release: bump version, regenerate vendored, run all checks. Usage: make release VERSION=X.Y.Z. Must be on main with a clean tree. Does NOT commit, tag, or push. Recovery from a partial failure: see comment block above the recipe.
+# Partial-failure recovery for `make release`:
+# If `make release` fails after bump-version writes (post-bump but pre-test),
+# the working tree will be dirty and the clean-tree gate will block re-runs.
+# Two recovery paths, in increasing severity:
+#  1. Soft restore (preferred when no other in-progress work exists):
+#       git restore --staged --worktree .claude-plugin/marketplace.json \
+#                                       plugins/paad/.claude-plugin/plugin.json \
+#                                       plugins/paad/skills/*/SKILL.md
+#       git restore --staged --worktree --source HEAD -- kiro_and_antigravity/
+#     Then re-run `make release VERSION=X.Y.Z`.
+#  2. Commit-then-re-release (when the partial bump is already useful):
+#       git add -A && git commit -m "WIP: release vX.Y.Z bump"
+#       make release VERSION=X.Y.Z   # idempotent on the new version
+#     Then squash the WIP commit into the eventual release commit.
+# Do NOT use `git reset --hard` — it loses any other unrelated in-flight work.
+	@if [ -z "$(VERSION)" ]; then \
+		echo "Usage: make release VERSION=X.Y.Z"; \
+		exit 1; \
+	fi
+	@current_branch=$$(git rev-parse --abbrev-ref HEAD); \
+	if [ "$$current_branch" != "$(MAIN_BRANCH)" ]; then \
+		echo "FAIL: release must run from '$(MAIN_BRANCH)' (currently on '$$current_branch')."; \
+		echo "Switch with: git checkout $(MAIN_BRANCH)"; \
+		echo "Override the expected branch with: make release VERSION=$(VERSION) MAIN_BRANCH=<name>"; \
+		exit 1; \
+	fi
+	@if [ -n "$$(git status --porcelain)" ]; then \
+		echo "FAIL: working tree is not clean — release must start from a clean state."; \
+		echo "Run 'git status' to see what's pending; commit or stash before releasing."; \
+		exit 1; \
+	fi
+	@$(MAKE) bump-version VERSION=$(VERSION)
+	@$(MAKE) test
+	@echo ""
+	@echo "Release v$(VERSION) prepared. Review the diff, then:"
+	@echo "  git add -A && git commit -m 'Release v$(VERSION)'"
+	@echo "  git tag v$(VERSION)"
+	@echo "  git push origin $(MAIN_BRANCH) --tags"
+
+check-vendored: ## Verify kiro_and_antigravity/ is in sync with the converter's current output
+	@tmp=$$(mktemp -d); \
+	trap 'rm -rf "$$tmp"' EXIT; \
+	if ! TARGET_DIR="$$tmp" python3 scripts/convert_skills.py >/dev/null; then \
+		echo "FAIL: scripts/convert_skills.py exited non-zero — converter is broken (this is not a sync drift)."; \
+		echo "Re-run 'python3 scripts/convert_skills.py' to see the actual error."; \
+		exit 1; \
+	fi; \
+	if ! diff -r "$$tmp/.kiro" kiro_and_antigravity/skills/.kiro >/dev/null 2>&1 \
+	   || ! diff -r "$$tmp/.agent" kiro_and_antigravity/skills/.agent >/dev/null 2>&1; then \
+		echo "FAIL: kiro_and_antigravity/ is out of sync with scripts/convert_skills.py output."; \
+		echo "Run 'make vendored' to regenerate, then commit."; \
+		echo "--- diff (.kiro) ---"; \
+		diff -r "$$tmp/.kiro" kiro_and_antigravity/skills/.kiro || true; \
+		echo "--- diff (.agent) ---"; \
+		diff -r "$$tmp/.agent" kiro_and_antigravity/skills/.agent || true; \
+		exit 1; \
+	fi; \
+	echo "Vendored output is in sync with scripts/convert_skills.py."
diff --git a/README.md b/README.md
@@ -256,9 +256,10 @@ Discipline means reviewing before merging, every time. `agentic-review` uses mul
 Where typical AI review features tend to provide shallow, opportunistic feedback, `agentic-review` is designed as a deliberate pre-merge quality gate: parallel analysis, finding verification, deduplication, and severity ranking.
 
 * **Arguments:** `/paad:agentic-review` (diff against `main`) or `/paad:agentic-review develop` (diff against `develop`) or `/paad:agentic-review main src/auth/` (scoped to a directory)
-* **Parallel review** — five specialists examine your branch simultaneously, then findings are verified against actual code and deduplicated
+* **Parallel review** — six specialists examine your branch simultaneously (Logic & Correctness, Error Handling & Edge Cases, Contract & Integration, Concurrency & State, Security, Spec Compliance), then findings are verified against actual code and deduplicated
 * **Severity ranking** — Critical / Important / Suggestion
-* **Plan alignment** (conditional) — if design docs are found, checks implementation against the plan
+* **Spec Compliance** — pulls intent from PR description, plan/design docs, recent commits, or branch name; flags missing features, deviations, and out-of-scope additions (replaces the older Plan Alignment agent)
+* **Out-of-scope handling** — pre-existing bugs persist to `paad/code-reviews/backlog.md`; out-of-scope additions are flagged for per-PR decision (keep / split / revert) without backlog persistence
 * **Report** — written to `paad/code-reviews/`
 
 Requires a feature branch (not `main` or `master`) with committed changes.