Merge remote-tracking branch 'origin/main' into rename

skills/builder/references/contract.md

@@ -43,10 +43,47 @@ Agent 只保留授权判断和歧义处理。**
 | 变量 | 默认 | 说明 |
 |------|------|------|
 | `ARCH` | `amd64` | 仅允许 `amd64` \| `arm64`，非法值必须 `$(error)` 报错并提示合法值 |
-| `VERSION` | `` （空） | 为空时由 make 从 `git describe --tags --always --dirty` 推导 |
+| `VERSION` | `` （空） | 为空时按「版本号」节从 Git 祖先稳定 tag 推导；禁止 `sort -V` 取全局最新 |
 | `DIST_DIR` | `dist` | DEB 产物目录 |
 | `PROJECT_NAME` | git 仓库名 | 包名/镜像名主体 |
 
+### 版本号
+
+`make version` 输出一行规范版本（无 `v` 前缀）。DEB 的 `Version` 与文件名
+直接用它；Docker tag 由它渲染。推导入口是 `scripts/version.sh`（`make` 通过
+`scripts/version.mk` 引用）；Builder 只读取 Git 状态，不调用
+manage-release，不猜测下一个正式 SemVer。正式 tag 由 manage-release 事先打好。
+`version.sh` 不执行 `git fetch`。
+
+推导前 `git fetch --tags`（本地 linked worktree 共享 tags，不必再 fetch 才
+能看见其它 worktree 新打的 tag）。基线是 **HEAD 祖先上最近的稳定 tag**，
+不是全仓库 `sort -V` 的最大号。稳定 tag 仅 `v<major>.<minor>.<patch>`。
+
+| 判定 | 规范版本 | DEB 文件 | Docker tag |
+| --- | --- | --- | --- |
+| HEAD exact-match 稳定 tag `v1.4.2` | `1.4.2` | `name_1.4.2_<arch>.deb` | `1.4.2` |
+| 其它 commit；祖先最近稳定 tag `v1.4.2` | `1.4.2~<branch>.<n>+g<sha>` | `name_1.4.2~<branch>.<n>+g<sha>_<arch>.deb` | `1.4.2-<branch>.<n>.g<sha>` |
+| 祖先中没有稳定 tag | `0.0.0~<branch>+g<sha>` | 同上替换规范版本 | 同上映射 |
+
+测试与正式进入同一 apt / Docker 仓库。测试 DEB 必须用 `~`，使
+`1.4.2~…` < `1.4.2`，`apt upgrade` 不会装上测试包。Docker tag 不得含
+`~`、`/`、`:`，由规范版本把 `~` → `-`、`+g` → `.g`。
+
+`<branch>`：`git rev-parse --abbrev-ref HEAD`，detached 时用
+`BUILD_BRANCH` / `CI_COMMIT_BRANCH` / `GITHUB_REF_NAME`，再没有则
+`detached`。清洗：小写；`/`、`_` → `-`；去掉非 `[a-z0-9-]`；压缩连续
+`-`；过长截断（给 base、距离、SHA 留位置；Docker tag 上限 128）。
+`<n>` 为基线 tag 到 HEAD 的 commit 数；`<sha>` 为 7 位短哈希。不要把
+`--dirty` 写入版本；脏树发布仍走既有门禁。显式 `VERSION=` / `IMAGE_TAG=`
+可覆盖推导，但不得把非 exact-match 的 commit 标成正式 `X.Y.Z`。
+
+项目 Makefile 不要内联 `git describe` 或 `sort -V`，include 本 skill 的
+`scripts/version.mk`：
+
+```makefile
+include $(HOME)/.skills/skills/builder/scripts/version.mk
+```
+
 ## 3. 发布环境变量
 
 ### DEB 轨道
@@ -64,7 +101,7 @@ Agent 只保留授权判断和歧义处理。**
 |------|------|------|
 | `DOCKER_REGISTRY` | 是 | registry 主机，无 scheme |
 | `DOCKER_REPOSITORY` | 否 | 默认取 git 仓库名 |
-| `IMAGE_TAG` | 否 | 默认 `git describe --tags --always --dirty` |
+| `IMAGE_TAG` | 否 | 默认由规范版本渲染：正式为 `X.Y.Z`；测试将 `~` 换成 `-`、`+g` 换成 `.g` |
 | `PLATFORMS` | 否 | 默认 `linux/amd64`；多平台如 `linux/amd64,linux/arm64` |
 
 配置来源优先级：shell 已显式设置的值 > 项目根 `.env` > 失败并询问用户。
@@ -78,7 +115,7 @@ Agent 只保留授权判断和歧义处理。**
 
 ## 4. 脚本解析顺序
 
-push 目标定位 builder 脚本时按以下顺序，命中即用，不做静默兜底：
+push 目标与 `version.sh` 定位 builder 脚本时按以下顺序，命中即用，不做静默兜底：
 
 1. `$BUILDER_SKILL_DIR/scripts/`（特殊安装位置）
 2. `$HOME/.pouch/skills/builder/scripts/`（标准 clone 位）

skills/builder/references/registry.md

@@ -34,7 +34,9 @@
 
 ## Tag 策略
 
-- release tag（如 `v1.2.3`）默认视为不可变。
-- Git SHA tag 应对应当前源 commit。
-- `latest`、`stable` 等浮动 tag 只有在用户明确要求时才发布。
-- 用户未给 tag 且项目没有唯一明确规则时，必须询问，不要自行选择。
+- 未显式给出 `--tag` / `IMAGE_TAG` 时，使用契约「版本号」渲染出的 tag
+  （正式 `1.4.2`，测试 `1.4.2-feat-login.7.gabc1234`），不要退回
+  `git describe`，不要询问后另选一套。
+- 正式产物 tag 与 Git tag `vX.Y.Z` 对应，但镜像 tag **不含** `v`；默认视为不可变。
+- `latest`、`stable`、裸分支名等浮动 tag 只有在用户明确要求时才额外发布，
+  不能代替上面那条唯一身份。