chrispezza · Oct 13, 2026 · Oct 13, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,34 +7,88 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-10-12
+
+### Changed
+- The `/compile` handoff tells the implementation agent to re-read the spec files after a recompile, because the builder may have applied a requested change differently and the package wins. In a closed-loop trial one run in six searched for its own field name, missed the builder's renamed field, and stopped (issue #71)
+
+## [0.5.3] - 2026-10-12
+
+### Changed
+- The `/compile` handoff no longer tells the implementation agent to edit the spec package. `/compile` rebuilds the package from the source artifacts, so a hand edit was unvalidated and lost on the next compile; in a trial half of such edits failed validation. The agent now writes the agreed change to `spec-change-request.md`, names the source artifact for each spec file, asks the builder to recompile, and builds the feature from the recompiled package (issue #71)
+
+## [0.5.2] - 2026-10-12
+
+### Changed
+- The `/compile` handoff (`CLAUDE.md` for the implementation agent) now says what to do when asked for something the spec does not cover: check the exclusion ADRs, otherwise say so, propose the spec change, and ask before building. It previously said only to stop and check the ADRs, which list exclusions and so resolved nothing for an unlisted request (issue #65)
+- `manifest` check: a missing `claude` CLI is now a note locally and a finding only under `--require-validator`, which CI passes. With that fixed the check graduates warn → block (issue #63); 13 of 18 checks now block
+
+## [0.5.1] - 2026-10-12
+
+Also carries the repository changes merged since 0.5.0 that did not bump the plugin version.
+
 ### Added
-- ADR 0012: ADR Enforcement Architecture — classification buckets, warn-only launch, two-hook blocking core, per-check graduation (warn → block after 7 clean days or one real catch), deltas from the Astro-starter implementation
-- `checks/` — warn-only enforcement suite (14 checks: frontmatter, body structure, placeholders, dependency graph, word limits, manifest via `claude plugin validate --strict`, component census, legacy guards, self-containment, spec fixture, ADR status, filename convention); config `checks/enforcement.config.json`, CI job in `validate.yml`
-- Enforcement sections appended to all 11 prior ADRs: testable consequences, check mappings, honest not-machine-checkable lines, empty graduation logs
-- Two blocking hooks in checked-in `.claude/settings.json`: Stop-gate (suite BLOCKERs bounce the turn) and PreToolUse guard (existing ADRs append-only, Pattern Guide requires an ADR); kill-switches `PRODUCT_DEV_SKIP_STOP_GATE=1` / `PRODUCT_DEV_SKIP_ADR_GUARD=1`
 - ADR 0019: CLAUDE.md is the contributor guide; runtime canon lives in the plugin. New warn-level check `claude-md-scope` (links resolve; 1,000-word budget)
 - ADR index, generated: `checks/adr_index.py` renders the index of records (status, enforcing checks, amended-by links) from the ADR files and the enforcement config. Two new warn-level checks (ADR 0012 TC-3, TC-4): `adr-index` fails when the committed index is stale, `adr-amendment-link` fails when an ADR says it amends another and the amended one never names it
-- `skills-claude-ai/` — Claude.ai Agent Skill ports of product-ideation and product-flow (issue #12): bundled prompts with skill-relative paths, conversation-scoped artifact ledger with `product-dev-artifacts.md` export replacing the `.product-dev/` registry
+- ADR 0018: the enforcement CI job reports the suite's finding count to the ops dashboard on pushes to `main` (2026-08-26)
 
 ### Changed
-- Plugin 0.5.4: the `/compile` handoff tells the implementation agent to re-read the spec files after a recompile, because the builder may have applied a requested change differently and the package wins. In a closed-loop trial one run in six searched for its own field name, missed the builder's renamed field, and stopped (issue #71)
-- Plugin 0.5.3: the `/compile` handoff no longer tells the implementation agent to edit the spec package. `/compile` rebuilds the package from the source artifacts, so a hand edit was unvalidated and lost on the next compile; in a trial half of such edits failed validation. The agent now writes the agreed change to `spec-change-request.md`, names the source artifact for each spec file, asks the builder to recompile, and builds the feature from the recompiled package (issue #71)
-- Plugin 0.5.2: the `/compile` handoff (`CLAUDE.md` for the implementation agent) now says what to do when asked for something the spec does not cover: check the exclusion ADRs, otherwise say so, propose the spec change, and ask before building. It previously said only to stop and check the ADRs, which list exclusions and so resolved nothing for an unlisted request (issue #65)
-- `manifest` check: a missing `claude` CLI is now a note locally and a finding only under `--require-validator`, which CI passes. With that fixed the check graduates warn → block (issue #63); 13 of 18 checks now block
-- Plugin 0.5.1: tier escalation is now offered, not applied, in every workflow skill. Four rules that existed only in this repo's `CLAUDE.md` ship in `plugin/docs/registry-operations.md` § Workflow Rules (offer Tier 2 prompts and let the user pick; never auto-escalate to Tier 3; ask when a gate condition is unclear; entry points are exclusive). `product-ideation` previously inserted Tier 2 prompts on a signal; `product-flow` and `tech-spec` had no escalation procedure (issue #62)
+- Tier escalation is now offered, not applied, in every workflow skill. Four rules that existed only in this repo's `CLAUDE.md` ship in `plugin/docs/registry-operations.md` § Workflow Rules (offer Tier 2 prompts and let the user pick; never auto-escalate to Tier 3; ask when a gate condition is unclear; entry points are exclusive). `product-ideation` previously inserted Tier 2 prompts on a signal; `product-flow` and `tech-spec` had no escalation procedure (issue #62)
+- product-ideation: the escape hatch now respects the first explicit request to move on, recording the remaining unvalidated assumptions instead of requiring a second override
 - `CLAUDE.md` is now the contributor guide (ADR 0019): about 650 words of pointers and change rules, down from about 2,000 that restated the skills, the tier model, the plugin tree, and the ADR list. Four runtime rules that never shipped in the plugin stay in a labelled section pending issue #62
-- PreToolUse guard: an ADR is protected only once it exists in `HEAD`, so a draft can be revised before its first commit
-- README: the hand-kept ADR table is replaced by a pointer to the generated index
-- PreToolUse guard: the Bash rule for inline scripts now requires an existing protected file or iteration of the ADR folder, after it blocked two commands that only mentioned the folder in text
 - Enforcement suite: first graduation (ADR 0012 amendment, 2026-10-12). Twelve checks moved warn → block after 7+ clean days: `frontmatter-v2`, `name-uniqueness`, `body-structure`, `placeholder-syntax`, `placeholder-resolvability`, `dependency-graph`, `component-census`, `no-legacy`, `spec-fixture`, `adr-status`, `filename-convention`, `objective-parity`. Findings from these now fail CI and bounce the Stop-gate. `manifest`, `word-limit`, and `self-containment` stay at warn, with reasons in the amendment
+- PreToolUse guard (ADR 0012 amendment, 2026-10-12): appending to the end of an existing ADR is now allowed, so amendments and graduation-log entries no longer need the kill-switch; the guard also covers MultiEdit and Bash writes; rejections name moves an agent can actually take. Tests in `checks/tests/`, run in CI
+- PreToolUse guard: the Bash rule for inline scripts now requires an existing protected file or iteration of the ADR folder, after it blocked two commands that only mentioned the folder in text
+- PreToolUse guard: an ADR is protected only once it exists in `HEAD`, so a draft can be revised before its first commit
 - ADRs 0003, 0004, 0008, 0013: appended amendments recording what later ADRs changed (the 6-command / 5-skill / 2-subagent census, registry extensions, the reverse-pass checks that had landed)
+- README: the hand-kept ADR table is replaced by a pointer to the generated index
 - PR and bug-report templates, README, `scripts/README.md`, CONTRIBUTING: removed references to the deleted MCP server and to script paths that moved into `plugin/scripts/`; corrected component counts
-- PreToolUse guard (ADR 0012 amendment, 2026-10-12): appending to the end of an existing ADR is now allowed, so amendments and graduation-log entries no longer need the kill-switch; the guard also covers MultiEdit and Bash writes; rejections name moves an agent can actually take. Tests in `checks/tests/`, run in CI
-- product-ideation: the escape hatch now respects the first explicit request to move on, recording the remaining unvalidated assumptions instead of requiring a second override
-- ADR 0002: Superseded — MCP server removed; plugin is the sole delivery mechanism
 
 ### Removed
 - `docs/skills/` — eight skill specs for the pre-ADR 0004 eight-skill design, referenced by nothing
+
+## [0.5.0] - 2026-07-27
+
+Headings 0.2.0 to 0.5.0 were reconstructed on 2026-10-12 from the `plugin.json` history and the ADRs. Each lists the headline changes of that version bump, not every commit.
+
+### Added
+- ADR 0016: interrogation protocol and sequence gates in product-ideation, candidate directions in the solution-concept prompt, and input-version provenance (`inputs`) in the context registry
+- ADR 0017: adversarial review loops for the technical spec and the compiled package, decision classification in the tech-spec-writer, an owner scope walk in ux-optimization, and project-local process learnings (`.product-dev/learnings.jsonl`)
+- `plugin/docs/registry-operations.md`: the registry operations reference now ships inside the plugin (ADR 0011 amendment)
+- Optional template placeholders, `{{name?}}` (ADR 0003 amendment)
+- `objective-parity` check, and a verification-coverage line in the optimization spec (ADR 0014 amendment)
+
+### Changed
+- Prompt `<constraints>` blocks allow 3 to 6 rules, up from 3 to 5 (ADR 0009 amendment); every prompt now has a declared word limit
+- ADR 0001 and ADR 0006: amendments recording that the minimal frontmatter governs and that the tier tables are illustrative
+
+## [0.4.0] - 2026-07-18
+
+### Added
+- ADR 0015: runtime audit mode for locally runnable products (`11_runtime_audit`)
+
+## [0.3.0] - 2026-07-18
+
+### Added
+- ADR 0014: live-site audit (`10_live_site_audit`) and a core-objective prompt (`07_objective_metrics`) in the reverse pass
+
+## [0.2.0] - 2026-07-18
+
+Also carries the repository changes made after 0.1.0 that did not bump the plugin version.
+
+### Added
+- ADR 0013: the UX optimization reverse pass — the `ux-optimization` skill, the `/optimize` command, the `ux-extractor` subagent, and the `07_ux_optimization` prompts
+- ADR 0011: the prompt library and compile scripts are bundled inside the plugin and referenced through `${CLAUDE_PLUGIN_ROOT}` (2026-07-03)
+- ADR 0012: ADR Enforcement Architecture — classification buckets, warn-only launch, two-hook blocking core, per-check graduation (warn → block after 7 clean days or one real catch), deltas from the Astro-starter implementation
+- `checks/` — warn-only enforcement suite (14 checks: frontmatter, body structure, placeholders, dependency graph, word limits, manifest via `claude plugin validate --strict`, component census, legacy guards, self-containment, spec fixture, ADR status, filename convention); config `checks/enforcement.config.json`, CI job in `validate.yml`
+- Enforcement sections appended to all 11 prior ADRs: testable consequences, check mappings, honest not-machine-checkable lines, empty graduation logs
+- Two blocking hooks in checked-in `.claude/settings.json`: Stop-gate (suite BLOCKERs bounce the turn) and PreToolUse guard (existing ADRs append-only, Pattern Guide requires an ADR); kill-switches `PRODUCT_DEV_SKIP_STOP_GATE=1` / `PRODUCT_DEV_SKIP_ADR_GUARD=1`
+- `skills-claude-ai/` — Claude.ai Agent Skill ports of product-ideation and product-flow (issue #12): bundled prompts with skill-relative paths, conversation-scoped artifact ledger with `product-dev-artifacts.md` export replacing the `.product-dev/` registry
+
+### Changed
+- ADR 0002: Superseded — MCP server removed; plugin is the sole delivery mechanism
+
+### Removed
 - `mcp/prompt-server/` — MCP server (issue #13 closed as superseded; revisit triggers never fired, and ADR 0011 left it pointing at a prompt directory that no longer holds the framework library)
 
 ## [0.1.0] - 2026-04-06

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -163,7 +163,7 @@ When making architectural decisions:
 
 Existing ADRs are append-only. To change one, append a dated `## Amendment (YYYY-MM-DD)` section at the end of the file, or write a new ADR that supersedes it. When a new ADR amends an older one, say so in the new one with the words "amends ADR NNNN" and append a note to the older one naming the new one (the `adr-amendment-link` check verifies the pair). In Claude Code sessions a hook (`checks/hooks/pretooluse_guard.py`) blocks rewrites and allows appends.
 
-After adding or amending an ADR, regenerate the index with `python checks/adr_index.py --write` (never edit the index by hand). Run `python checks/run_checks.py --ci` before pushing. Checks at `block` fail CI; see `checks/README.md`.
+After adding or amending an ADR, regenerate the index with `python checks/adr_index.py --write` (never edit the index by hand). Run `python checks/run_checks.py --ci` before pushing. When a change bumps the version in `plugin/.claude-plugin/plugin.json`, update the README badge and move that version's entries in `CHANGELOG.md` under a `## [x.y.z] - YYYY-MM-DD` heading; a test fails otherwise. Checks at `block` fail CI; see `checks/README.md`.
 
 ## Code Style
 

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 > A Claude Code plugin that compiles fuzzy product ideas into validated, agent-consumable specification packages.
 
-[![Framework Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](CHANGELOG.md)
+[![Framework Version](https://img.shields.io/badge/version-0.5.4-blue.svg)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/license-Apache_2.0-yellow.svg)](LICENSE)
 [![validate](https://github.com/clownware/product-dev/actions/workflows/validate.yml/badge.svg)](https://github.com/clownware/product-dev/actions/workflows/validate.yml)
 
@@ -35,8 +35,24 @@ A validation pipeline checks referential integrity across all spec files before
 
 ## Install
 
+From the Clownware marketplace, inside Claude Code:
+
+```
+/plugin marketplace add clownware/plugins
+/plugin install product-dev@clownware
+```
+
+Or from a terminal:
+
+```bash
+claude plugin marketplace add clownware/plugins
+claude plugin install product-dev@clownware
+```
+
+To run it from a checkout of this repo without installing, for development:
+
 ```bash
-claude plugin install --plugin-dir ./plugin
+claude --plugin-dir ./plugin
 ```
 
 Works in Claude Code CLI, Desktop app, and VS Code extension.
@@ -52,6 +68,7 @@ Works in Claude Code CLI, Desktop app, and VS Code extension.
 | `/spec` | Generate technical specs (data models, API, business rules, NFRs) |
 | `/compile` | Assemble artifacts into a validated spec package + handoff instruction |
 | `/summary` | Generate a consolidated project brief |
+| `/optimize` | Audit an existing product and build a prioritized UX optimization spec |
 | `/product-dev:status` | Show project progress and suggest next steps |
 
 ### Typical Flow

diff --git a/checks/tests/test_release_metadata.py b/checks/tests/test_release_metadata.py
@@ -0,0 +1,38 @@
+"""The plugin version is stated in three places. plugin.json is the source;
+the README badge and the CHANGELOG must agree with it (issue #73).
+Run: python -m unittest discover -s checks/tests
+"""
+import json
+import re
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+VERSION = json.loads((ROOT / "plugin" / ".claude-plugin" / "plugin.json").read_text())["version"]
+
+
+class ReleaseMetadataCase(unittest.TestCase):
+    def test_readme_badge_matches_plugin_json(self):
+        m = re.search(r"badge/version-([0-9][^-]*)-", (ROOT / "README.md").read_text())
+        self.assertIsNotNone(m, "README.md has no version badge")
+        self.assertEqual(
+            m.group(1), VERSION,
+            f"README badge says {m.group(1)} but plugin.json is {VERSION} — update the badge",
+        )
+
+    def test_changelog_has_a_heading_for_the_current_version(self):
+        self.assertRegex(
+            (ROOT / "CHANGELOG.md").read_text(),
+            rf"(?m)^## \[{re.escape(VERSION)}\] - \d{{4}}-\d{{2}}-\d{{2}}$",
+            f"CHANGELOG.md has no '## [{VERSION}] - YYYY-MM-DD' heading — move the "
+            "entries for this version out of Unreleased when bumping plugin.json",
+        )
+
+    def test_readme_does_not_document_an_install_flag_that_does_not_exist(self):
+        # `claude plugin install` takes plugin@marketplace; --plugin-dir is a
+        # flag of `claude` itself.
+        self.assertNotIn("plugin install --plugin-dir", (ROOT / "README.md").read_text())
+
+
+if __name__ == "__main__":
+    unittest.main()