chore: adopt automatic version updates

.github/workflows/version-policy.yml

@@ -0,0 +1,27 @@
+name: Version policy
+on:
+  pull_request:
+    types: [opened, reopened, edited, synchronize, ready_for_review]
+permissions:
+  contents: read
+concurrency:
+  group: version-policy-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+jobs:
+  version-policy:
+    name: Version policy
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.11'
+      - name: Check intended version against current base
+        env:
+          BASE_BRANCH: ${{ github.event.pull_request.base.ref }}
+        run: python3 scripts/mw-version.py check --base "refs/remotes/origin/$BASE_BRANCH" --event-file "$GITHUB_EVENT_PATH"

.version-policy.json

@@ -0,0 +1,21 @@
+{
+  "schema_version": 1,
+  "units": [
+    {
+      "name": "repo",
+      "paths": [
+        "**"
+      ],
+      "files": [
+        {
+          "path": "package.json",
+          "kind": "json"
+        },
+        {
+          "path": "package-lock.json",
+          "kind": "npm-lock"
+        }
+      ]
+    }
+  ]
+}

AGENTS.md

@@ -25,3 +25,7 @@ This repository is a MachineWisdom release-engineering toolkit for KissClaw and
 
 - Keep this file short and repo-specific.
 - Put long runbooks, architecture, and operational detail in docs/ or FAVA Trails.
+
+## Version updates
+
+For a versioned change PR, follow [the version policy](docs/version-policy.md) and run the repository-local updater before review and after updating the branch from main. Keep commit and PR titles in Conventional Commits format.

docs/version-policy.md

@@ -0,0 +1,44 @@
+# Repository version policy
+
+The updater needs Python 3.11 or newer and no third-party libraries. Select that
+interpreter explicitly if the system `python3` is older (for example,
+`python3.13 scripts/mw-version.py ...` on macOS).
+
+Every change PR updates affected versions before merge. Run the repository-local
+updater after your implementation and again after updating the branch from main:
+
+```bash
+git fetch origin main
+python3 scripts/mw-version.py update --base origin/main --title 'chore(deps): update transitive dependency'
+python3 scripts/mw-version.py check --base origin/main --title 'chore(deps): update transitive dependency'
+```
+
+Use the actual PR title. Supply `--body-file PATH` for its body, or `--event-file`
+with a GitHub pull-request event containing title/body. The updater also reads
+the PR branch's commits. One PR gets the largest applicable increment: features
+are minor; fixes and every other change (including chores, docs, tests, CI, and
+direct/transitive dependencies) are patch. `!`, `BREAKING CHANGE:`, or
+`BREAKING-CHANGE:` is major from 1.0 onward and minor before 1.0. A dependency's
+own major number does not establish a breaking change in this project.
+
+`.version-policy.json` lists version units, paths, and synchronized files. Changes
+outside all unit paths affect every unit, except configured `exclude_paths`.
+Root units use `**`. Lockfiles retain their resolved dependencies. Updating again
+uses the base version, so it does not accumulate bumps. Update your branch from
+current main before merging; the required check rejects a stale base.
+
+Prereleases advance the base and reset the counter: `0.1.0-rc.5` becomes
+`0.1.1-rc.1` for a patch. Python metadata serializes the same version as
+`0.1.1rc1`. Date prereleases retain that format and refresh the date; `--date`
+accepts YYYY-MM-DD for reproducible runs. CI accepts a valid date between the
+previous version's date and today, so an overnight review does not invalidate it.
+
+Explicit release promotion uses the exact title `chore(release): promote version`
+and changes only configured version values: `0.1.1-rc.1` becomes `0.1.1`, without
+another base increment. Existing release review and publication authority still
+apply. The updater never creates a tag, release, publication, or deployment.
+
+For a new versioned component, run the toolkit bootstrap again or run
+`python3 scripts/mw-version.py enroll --repo PATH --unit COMPONENT_PATH` from an
+installed copy. Review the generated configuration and add any runtime/plugin
+mirrors. Captured templates and vendored packages are not owned version units.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "kissclaw-tools",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared tooling for KissClaw and KissClawJJ — TypeScript-aware cherry-pick validation (kc-check-imports) and related release-engineering helpers.",
   "main": "kc-check-imports.mjs",
   "type": "module",