feat(pkm): bump to 0.2.0 for the audit change-set + first-party versioning policy

The pkm every-aspect audit (A01-A30 + A24, 29/29 verified) is new, backward-
compatible behavior + fixes on top of 0.1.0 — a SemVer MINOR change, not a
packaging revision. Bumped pkm 0.1.0 -> 0.2.0 (release reset to 1) across all
three places a first-party version is declared:
- pkm/__init__.py __version__ (pkm --version, User-Agent, min_pkm_version check)
- packages/core/pkm/package.yml version (pkgrel source)
- scripts/chroot-build-core-extra.sh run_package arg (pkgver / archive version)
(min_pkm_version stays 0.1.0 — it's the compatibility floor, not the current
version; the index format is unchanged. repo.py:80 stale version comment fixed.)

Origin: operator caught that a 29-finding audit left pkm reading "0.1.0" because
every prior change had bumped release only — we had never defined a versioning
policy for packages we author. Now documented in docs/operations/08-adding-
packages.md (new "Versioning policy" section): version = the software's own
version (SemVer for first-party, mirror-upstream for third-party); release =
packaging revision of the SAME code; the decision rule (source changed -> version,
packaging changed -> release); and the gotcha that a first-party version lives in
multiple files that must be bumped together (grep name+old-version before a bump).

Policy applies going forward; other first-party packages (intergen/theme/helper-
lib) reconcile to a real version the next time each changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Author: InterGenJLU

docs/operations/08-adding-packages.md

@@ -103,6 +103,51 @@ pending_acquisition: "<reason — e.g., Microsoft UEFI CA sponsorship still pend
 
 The pre-squashfs audit skips packages with `pending_acquisition` set. Don't use this as a workaround for unwilling-to-author cases; it's specifically for blocked-on-external dependencies.
 
+#### Versioning policy — `version` vs `release` (what declares a version change)
+
+`version` and `release` mean different things, and conflating them was a real
+defect (we caught it 2026-06-16: pkm had absorbed a 29-finding audit yet still read
+`0.1.0` because every change had bumped `release` only). The policy:
+
+- **`version`** = the *software's own* version.
+  - **Third-party packages:** mirror the upstream release exactly (e.g. `git`
+    `2.51.0`). It changes only when we package a new upstream version.
+  - **First-party packages** (we author them — pkm, intergen, forge, the theme,
+    helper-lib, etc.): **we are upstream, so `version` is ours to bump, by SemVer:**
+    - **PATCH** (`0.2.0 → 0.2.1`) — bug fixes only, no behavior/interface change.
+    - **MINOR** (`0.1.0 → 0.2.0`) — new, backward-compatible behavior or features.
+    - **MAJOR** (`0.x → 1.0`, `1.x → 2.0`) — a stability milestone or a breaking change.
+- **`release`** = the *packaging* revision of the **same** `version`. Bump it **only**
+  when the code is unchanged and the *packaging* changed: a `build.sh`/recipe tweak, a
+  rebuild against a new dependency, a `.PKGINFO` fix, or a mirror republish of identical
+  code. A `release` bump is **not** a substitute for a `version` bump when the software
+  itself changed.
+
+**Decision rule:** did the package's *own source* change in a way a user would
+notice (a fix, new behavior, new output)? → bump **`version`** (and reset `release`
+to `1`). Did only the *recipe/packaging* change? → bump **`release`**, keep `version`.
+
+> **Both still matter mechanically.** A `version` *or* `release` change flips the
+> template hash so `--skip-built` rebuilds it, and the mirror index orders by
+> `(version, release)` so a same-version republish must still advance `release` to be
+> visible to `pkm upgrade` (see `first-publish-runbook.md`). The policy above governs
+> *which* field is semantically correct; the mechanical "must change to rebuild/ship"
+> rule is unchanged.
+
+**⚠️ A first-party `version` is declared in MORE THAN ONE place — bump them together.**
+The build driver passes the version as a literal arg, separate from `package.yml`, and
+some packages also carry their own `__version__`. For **pkm** the version lives in
+THREE files that must all match, or the built archive/`pkm --version`/the recipe disagree:
+
+1. `packages/core/pkm/package.yml` — `version:` (and `release:`).
+2. `scripts/chroot-build-core-extra.sh` — the `run_package "pkm" "pkm" "<version>"` arg
+   (the driver supplies the build/archive `pkgver`; `package.yml` supplies `pkgrel`).
+3. `pkm/__init__.py` — `__version__` (what `pkm --version`, the User-Agent, and the
+   index `min_pkm_version` check report).
+
+When bumping any first-party package, grep its name + the old version across
+`packages/`, `scripts/`, and the package's own source to catch every literal.
+
 ### 2. Author build.sh
 
 For `build_style: custom`, `build.sh` defines `configure`, `build`, and `do_install` functions. The orchestrator sources the script inside the chroot's per-package work directory and calls each function in sequence.

packages/core/pkm/package.yml

@@ -1,6 +1,6 @@
 name: pkm
-version: "0.1.0"
-release: 6
+version: "0.2.0"
+release: 1
 description: InterGenOS package manager — install, remove, query, verify
 license: GPL-3.0-or-later
 homepage: https://github.com/InterGenJLU/intergenos

pkm/__init__.py

@@ -19,4 +19,4 @@
     pkm history                 Show operation history
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

pkm/repo.py

@@ -77,8 +77,8 @@
     _TRACE_AVAILABLE = False
 
 # L-020: _parse_index references __version__ for the min_pkm_version
-# envelope check. pkm/__init__.py:20 defines __version__ = "0.1.0".
-# Importing via the package surface keeps this single-sourced.
+# envelope check. pkm/__init__.py defines __version__ (the canonical pkm
+# software version). Importing via the package surface keeps this single-sourced.
 from . import __version__
 
 from .database import PackageDB

scripts/chroot-build-core-extra.sh

@@ -606,7 +606,7 @@ run_package "apparmor" "apparmor" "3.1.7" \
     "apparmor-v3.1.7.tar.gz" \
     "AppArmor MAC framework — libapparmor, parser, profiles"
 
-run_package "pkm" "pkm" "0.1.0" \
+run_package "pkm" "pkm" "0.2.0" \
     "" \
     "InterGenOS package manager — install, remove, query, verify"