feat(release): release.py + version lockstep SSOT (P1)

.agents/skills/release/SKILL.md

@@ -21,8 +21,11 @@ confirm_versions: |md
   major only changes by explicit manual decision.
 |
 update_files: |md
-  Update the relevant pyproject.toml (and rust/Cargo.toml if root version changes),
-  CHANGELOG.md (keep the Unreleased header), and breaking-changes.md in both languages.
+  Run `uv run python scripts/release.py --set-version X.Y.Z [--bump-core A.B.C --bump-host A.B.C]`.
+  It rewrites pyproject.toml:3, the sub-package pins, uv.lock, all three changelog files
+  (preserving the authored Unreleased body), and the README/asset names from the single
+  source of truth, then runs the local gates and opens the `release/X.Y.Z` PR.
+  There is no `--bump-review` (review is frozen at 0.1.0).
 |
 root_change: "Is the root package version changing?"
 sync_pythinker_code: |md
@@ -32,7 +35,7 @@ sync_pythinker_code: |md
 sync_kagent: |md
   Sync rust/Cargo.toml workspace version to match the root package version.
 |
-uv_sync: "Run uv sync."
+uv_sync: "release.py already runs `uv lock` + `uv sync --frozen --all-extras --all-packages` as Phase-2/3 steps; no separate uv sync needed."
 gen_docs: |md
   Follow the gen-docs skill instructions to ensure docs are up to date.
 |

.github/workflows/ci-pythinker-cli.yml

@@ -212,6 +212,13 @@ jobs:
           python-version: "3.14"
           allow-prereleases: true
 
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # pinned from v8.1.0
+        with:
+          version: "0.8.5"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
       - name: Detect version bump
         id: version
         shell: python
@@ -250,10 +257,11 @@ jobs:
       - name: Check dependency versions
         if: steps.version.outputs.bump == 'true'
         run: |
-          python scripts/check_pythinker_dependency_versions.py \
+          uv run python scripts/check_pythinker_dependency_versions.py \
             --root-pyproject pyproject.toml \
             --pythinker-core-pyproject packages/pythinker-core/pyproject.toml \
-            --pythinker-host-pyproject packages/pythinker-host/pyproject.toml
+            --pythinker-host-pyproject packages/pythinker-host/pyproject.toml \
+            --pythinker-review-pyproject packages/pythinker-review/pyproject.toml
 
       - name: Check pythinker-code version alignment
         if: steps.version.outputs.bump == 'true'

.github/workflows/release-pythinker-cli.yml

@@ -46,6 +46,11 @@ jobs:
           python-version: "3.14"
           allow-prereleases: true
 
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # pinned from v8.1.0
+        with:
+          version: "0.8.5"
+
       - name: Check version tag
         run: |
           python scripts/check_version_tag.py \
@@ -54,10 +59,11 @@ jobs:
 
       - name: Check dependency versions
         run: |
-          python scripts/check_pythinker_dependency_versions.py \
+          uv run python scripts/check_pythinker_dependency_versions.py \
             --root-pyproject pyproject.toml \
             --pythinker-core-pyproject packages/pythinker-core/pyproject.toml \
-            --pythinker-host-pyproject packages/pythinker-host/pyproject.toml
+            --pythinker-host-pyproject packages/pythinker-host/pyproject.toml \
+            --pythinker-review-pyproject packages/pythinker-review/pyproject.toml
 
       # Hard release gate: every PyPI release must ship a matching README +
       # CHANGELOG update. README.md must contain a "What's New in <version>"

AGENTS.md

@@ -37,6 +37,12 @@ subagents, skills, web/visualization UIs, and multi-provider LLM authentication.
   commit status is `success`, not `pending`/`failure` or absent — and read the review summary and
   any "Actionable comments posted: N" findings. Do not merge while CodeRabbit is still reviewing or
   on an unreviewed commit; surface unresolved actionable findings instead of merging past them.
+- **When working on a PR or GitHub Actions failure, investigate and identify the root cause first.**
+  Provide the best-practice, most robust design solution; never provide fast fixes or workarounds.
+  This is a hard constraint.
+- **For session validation, check current authoritative sources before finalizing conclusions.** Use
+  Context7 MCP documentation lookups and targeted web search to verify the latest updates, APIs,
+  CI/GitHub Actions behavior, dependency guidance, and best practices relevant to the task.
 
 ## Simplicity and scope discipline
 

CHANGELOG.md

@@ -15,6 +15,7 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- **Release preparation now uses a version single source of truth.** `scripts/release.py` rewrites derived release files from `pyproject.toml`, verifies version lockstep on every PR, enforces the frozen `pythinker-review==0.1.0` pin, and managed-channel installs now show channel-native update guidance instead of trying to self-update.
 - CI and release workflows now run on Node.js 24-backed GitHub Actions, pin action revisions to immutable commits, and preflight optional website/tap GitHub App credentials with clear errors or notices instead of opaque token failures.
 - Release pipeline: migrate the pythinker-home website-sync dispatch to the org-owned `pythinker-release-bot` GitHub App and fail loud on an empty token; retire the dead pythinker-core API-docs gh-pages publish step; add exponential backoff to the native install scripts and fix the Windows installer's release-pagination cliff.
 - **Redesigned startup welcome banner.** The banner now uses a cleaner footer-chip layout: the "What's new / Update available" chip sits on the panel's bottom border, the headline/strapline/help lines align beside the robot logo, and the info grid drops its vertical separator. The robot art and palette are unchanged.

docs/en/release-notes/breaking-changes.md

@@ -2,6 +2,8 @@
 
 This page documents breaking changes in Pythinker Code releases and provides migration guidance.
 
+## Unreleased
+
 ## 0.27.0 (2026-05-31)
 
 No breaking changes. This release is compatible with 0.26.0 user configuration, native installs, and session data.

scripts/check_pythinker_dependency_versions.py

@@ -45,6 +45,7 @@ def main() -> int:
     parser.add_argument("--root-pyproject", type=Path, required=True)
     parser.add_argument("--pythinker-core-pyproject", type=Path, required=True)
     parser.add_argument("--pythinker-host-pyproject", type=Path, required=True)
+    parser.add_argument("--pythinker-review-pyproject", type=Path, required=True)
     args = parser.parse_args()
 
     try:
@@ -65,6 +66,7 @@ def main() -> int:
     for name, pyproject_path in (
         ("pythinker-core", args.pythinker_core_pyproject),
         ("pythinker-host", args.pythinker_host_pyproject),
+        ("pythinker-review", args.pythinker_review_pyproject),
     ):
         try:
             package_version = load_project_version(pyproject_path)