fix: release SpecSmith v0.22.2

.specsmith/requirements.json

@@ -2893,7 +2893,8 @@
     "source": "ARCHITECTURE.md §ESDB / ChronoStore",
     "status": "implemented",
     "test_ids": [
-      "TEST-305"
+      "TEST-305",
+      "TEST-478"
     ]
   },
   {
@@ -3234,7 +3235,8 @@
     "source": "ARCHITECTURE.md §CI Automation Manager — save/load Commands",
     "status": "implemented",
     "test_ids": [
-      "TEST-336"
+      "TEST-336",
+      "TEST-477"
     ]
   },
   {
@@ -3399,7 +3401,8 @@
     "source": "ARCHITECTURE.md §Session Governance Protocol",
     "status": "implemented",
     "test_ids": [
-      "TEST-351"
+      "TEST-351",
+      "TEST-479"
     ]
   },
   {
@@ -3600,7 +3603,8 @@
     "source": "user requirement",
     "status": "accepted",
     "test_ids": [
-      "TEST-370"
+      "TEST-370",
+      "TEST-476"
     ]
   },
   {
@@ -4546,5 +4550,27 @@
     "test_ids": [
       "TEST-470"
     ]
+  },
+  {
+    "id": "REQ-455",
+    "version": 1,
+    "title": "Environment-only SpecSmith CLI upgrades are non-blocking",
+    "description": "A preflight request limited to upgrading or installing the pipx-managed local SpecSmith CLI MUST return the explicit environment_only decision with exit code 0, no work item, no ESDB or ledger record, and instructions to use pipx. It MUST NOT require repository requirement matching or clarification.",
+    "source": "GitHub issue #299",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-474"
+    ]
+  },
+  {
+    "id": "REQ-456",
+    "version": 1,
+    "title": "SpecSmith CLI help is side-effect free",
+    "description": "Every SpecSmith CLI invocation containing --help MUST return usage without project migration, update checks, ledger writes, ESDB writes, work-item allocation, or project-file creation or modification. Migration remains available only through an explicit operational command.",
+    "source": "GitHub issue #300",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-475"
+    ]
   }
 ]

.specsmith/testcases.json

@@ -5134,5 +5134,77 @@
     "input": {},
     "expected_behavior": {},
     "confidence": 1.0
+  },
+  {
+    "id": "TEST-474",
+    "version": 1,
+    "title": "Pipx SpecSmith upgrades return a non-blocking environment-only preflight decision",
+    "description": "Verify pipx-managed local SpecSmith upgrade language returns environment_only, exits successfully, and does not create governance state.",
+    "requirement_id": "REQ-455",
+    "type": "cli",
+    "verification_method": "pytest tests/test_nexus.py",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
+  },
+  {
+    "id": "TEST-475",
+    "version": 1,
+    "title": "Preflight help does not mutate an outdated project",
+    "description": "Verify specsmith preflight --help leaves an older governed project byte-for-byte unchanged and does not create governance files.",
+    "requirement_id": "REQ-456",
+    "type": "cli",
+    "verification_method": "pytest tests/test_cli.py",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
+  },
+  {
+    "id": "TEST-476",
+    "version": 1,
+    "title": "Release metadata and embedded project schema versions agree",
+    "description": "Verify pyproject metadata, source fallback, default scaffold schema, and shipped wheel metadata use the same release version.",
+    "requirement_id": "REQ-369",
+    "type": "build",
+    "verification_method": "pytest tests/test_release_version_contract.py",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
+  },
+  {
+    "id": "TEST-477",
+    "version": 1,
+    "title": "Save falls back to the symbolic branch in the supplied worktree",
+    "description": "Verify save push resolves main from the supplied Git worktree when git branch --show-current returns no value and reports the inspected worktree if no branch exists.",
+    "requirement_id": "REQ-336",
+    "type": "unit",
+    "verification_method": "pytest tests/test_vcs_commands.py",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
+  },
+  {
+    "id": "TEST-478",
+    "version": 1,
+    "title": "ESDB migration repairs a verified legacy ChronoMemory WAL chain",
+    "description": "Verify an invalid ChronoStore chain is backed up, compacted, revalidated, and recorded in the migration manifest.",
+    "requirement_id": "REQ-305",
+    "type": "unit",
+    "verification_method": "pytest tests/test_esdb_migrate_wal_repair.py",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
+  },
+  {
+    "id": "TEST-479",
+    "version": 1,
+    "title": "Governance checkpoint anchor uses ASCII fixed-width rows",
+    "description": "Verify human checkpoint output uses ASCII borders and status words only, with every row the same fixed width.",
+    "requirement_id": "REQ-351",
+    "type": "cli",
+    "verification_method": "pytest tests/test_cli.py",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
   }
 ]

CHANGELOG.md

@@ -10,10 +10,25 @@ consolidated into the next published release.
 
 ## [Unreleased]
 
+## [0.22.2] - 2026-07-14
+
 ### Fixed
 - **Read the Docs latest deployment** - The manual RTD workflow now configures the
   canonical `layer1labs/specsmith` repository and `main` default branch, synchronizes
   versions, verifies `latest` maps to `main`, and fails on rejected API responses.
+- **Environment-only preflight loop** (#299) - `pipx`-managed local SpecSmith CLI
+  maintenance now returns a non-blocking `environment_only` decision without creating
+  project work items, ledger entries, or ESDB records.
+- **Mutating help path** (#300) - `--help` now bypasses automatic migration and update
+  checks, keeping help invocations side-effect free even for an outdated project.
+- **Release/schema provenance** (#301) - release metadata, source fallback, and the
+  default project schema are covered by a single version-parity contract.
+- **Save branch detection** (#302) - `save` falls back to Git's symbolic HEAD branch
+  and reports the inspected worktree when HEAD is genuinely detached.
+- **Legacy ChronoMemory WAL repair** (#303) - `esdb migrate` backs up and compacts a
+  detected invalid legacy chain, revalidates it, and records the outcome in its manifest.
+- **Governance anchor rendering** - checkpoint output now uses ASCII-only borders and
+  fixed-width rows with `OK`/`FAIL` status words.
 
 ## [0.22.1] - 2026-07-13
 ### Fixed
@@ -933,7 +948,8 @@ See git history for per-commit details on intermediate versions.
 
 ---
 
-[Unreleased]: https://github.com/layer1labs/specsmith/compare/v0.22.1...HEAD
+[Unreleased]: https://github.com/layer1labs/specsmith/compare/v0.22.2...HEAD
+[0.22.2]: https://github.com/layer1labs/specsmith/compare/v0.22.1...v0.22.2
 [0.22.1]: https://github.com/layer1labs/specsmith/compare/v0.22.0...v0.22.1
 [0.22.0]: https://github.com/layer1labs/specsmith/compare/v0.20.1...v0.22.0
 [0.20.1]: https://github.com/layer1labs/specsmith/compare/v0.20.0...v0.20.1

README.md

@@ -263,6 +263,10 @@ pipx upgrade specsmith   # preferred — upgrades the pipx-isolated CLI
 specsmith self-update    # alternative: self-update from within specsmith
 ```
 
+An intent limited to maintaining the local pipx CLI is returned as the non-blocking
+`environment_only` preflight decision. It exits successfully and creates no project
+work item, ledger entry, or ESDB record. All `--help` invocations are read-only.
+
 ---
 
 ## Quick Start

docs/COMPLIANCE.md

@@ -8,7 +8,7 @@
 - **Type**: python
 - **Language**: python
 - **VCS Platform**: github
-- **Spec Version**: 0.22.1
+- **Spec Version**: 0.22.2
 
 ## Verification Tools