feat: add skill init/check and isolate builder makefile

Give ack, builder, and deployer an explicit init/check mode that reports
missing project config instead of failing mid-work. Point builder at
makefile.builder so its contract targets do not collide with an existing
Makefile.

skills/builder/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: builder
 description: >-
-  按统一契约构建并发布项目的 DEB 包与 Docker 镜像：先校验项目 Makefile 是否符合
-  builder 契约（check.py），再 make 构建产物，经授权后用 skill 自带脚本上传并验证。
-  触发词：构建 deb、发布 deb、上传 deb、推送 apt 仓库、打 Debian 包、构建镜像、
-  发布镜像、推送 Docker 镜像、make push、检查 Makefile 是否符合规范。仅分析打包
-  逻辑或只构建不上传时也可使用；不会在未获授权时执行任何上传。Docker 轨道保持
-  显式触发：用户点名（builder/publish docker）时才走镜像发布。
+  初始化或检查项目是否满足 DEB/Docker 构建发布契约，再按契约构建并发布：
+  先校验 makefile.builder（check.py），再 make -f makefile.builder 构建产物，
+  经授权后用 skill 自带脚本上传并验证。触发词：初始化 builder、接入 builder、
+  检查 makefile.builder、构建 deb、发布 deb、上传 deb、推送 apt 仓库、打 Debian
+  包、构建镜像、发布镜像、推送 Docker 镜像、make push。仅分析打包逻辑或只构建
+  不上传时也可使用；不会在未获授权时执行任何上传。Docker 轨道保持显式触发：
+  用户点名（builder/publish docker）时才走镜像发布。
 ---
 
 # Builder：DEB / Docker 构建发布
@@ -14,28 +15,91 @@ description: >-
 复用项目已有发布约定，安全地完成"校验 → 构建 → 检查 → 授权 → 上传 → 验证"。
 
 分工原则：**make 管构建，skill 脚本管发布，本 SKILL.md 只留脚本做不了的决策。**
+项目状态是根目录 `makefile.builder` 与发布用 `.env`，不要创建 `.pouch/builder/`，
+不要改用户的 `Makefile` / `makefile`。
+
+开始时解析当前 `SKILL.md` 所在目录，记为 `<skill-dir>`。优先
+`git rev-parse --show-toplevel` 解析项目根。
+
+## 选择模式
+
+- 用户要求初始化、接入 builder，或新项目还没有 `makefile.builder`：执行“初始化”。
+- 用户要求检查 builder 契约或发布配置是否齐全：执行“检查”。
+- 用户要求构建、发布、上传：执行“工作流”。不要静默初始化。
 
 ## 何时使用
 
+- 用户要求初始化或接入 builder。
 - 用户要求构建、发布、上传 `.deb` 包或 Docker/OCI 镜像。
-- 用户要求检查项目 Makefile 是否符合 builder 契约。
+- 用户要求检查 `makefile.builder` 是否符合 builder 契约。
 - 用户要求梳理或接通项目现有的 DEB/镜像发布流程。
 
 不适用：本地安装/卸载 DEB；RPM/APK/语言包管理器；从零设计全新打包体系（先出方案）；
 普通编码与 Dockerfile 编辑。
 
+## 初始化
+
+1. 确认项目根。探测 `makefile.builder`、用户 `Makefile`/`makefile`（只当证据，
+   不改）、`Dockerfile`、`debian/`、语言清单、`.env` 键名（只看键是否存在，不读、
+   不打印值）。
+2. 判定轨道：有 Dockerfile → docker；有 deb 信号或用户要打 deb → deb；都不清则问。
+   不要猜测 registry、token 或仓库名。
+3. 没有 `makefile.builder`：把 `<skill-dir>/templates/makefile.builder` 拷到项目根。
+   按轨道删掉未使用的 deb/docker/push* 段，把 `build` 的 TODO 换成仓库里已有的
+   真实编译命令（可从用户 Makefile 抄配方，但不要 `include` 或递归调用它）。
+   `include` builder 的 `scripts/version.mk`。双产物把 `push` 改成
+   `push: push-deb push-docker`。不要改用户的 `Makefile` / `makefile`。
+4. 已有 `makefile.builder`：跑检查；按 FAIL 给出修补说明。不覆盖该文件，除非
+   用户明确要求按契约改。不要调用 create-makefile（其版本规则与本契约冲突）。
+5. 不要创建 `.env`。缺发布键时在报告里给出可粘贴示例，并说明 `.env` 不进 Git。
+6. 运行：
+
+   ```bash
+   python3 -I -S <skill-dir>/scripts/check.py <project-dir> --ready
+   ```
+
+7. 按下面格式报告。结构校验通过且当前轨道能构建时才能称「完成」；只缺发布
+   键是「部分完成」（可构建，不可发布）。契约 FAIL 或轨道工具缺失是「阻塞」。
+   除非用户明确要求，不提交、不推送、不上传。
+
+```text
+## builder 初始化：完成 | 部分完成 | 阻塞
+
+已具备: …
+待配置: 路径 + 字段 + 可粘贴示例 + 缺了会挡住哪步
+工具链: make / docker / dpkg-deb（缺则怎么装，不擅自安装）
+下一步: 一句话
+```
+
+发布键示例（只示范键名）：
+
+```text
+DEB_SERVER_URL=https://deb.example.com
+DEB_REPOSITORY=main
+DEB_TOKEN=
+DOCKER_REGISTRY=registry.example.com
+```
+
+## 检查
+
+只读。运行 `check.py <project-dir> --ready`，用同一报告格式，标题改为
+`## builder 检查：…`。不写 `makefile.builder`、不改用户 Makefile、不创建 `.env`。
+用户明确要求修复后再转入初始化。
+
 ## 工作流
 
 ### 0. 校验契约
 
 ```bash
 python3 -I -S <skill-dir>/scripts/check.py <project-dir>          # 静态检查
+python3 -I -S <skill-dir>/scripts/check.py <project-dir> --ready  # 含工具链与发布键
 python3 -I -S <skill-dir>/scripts/check.py <project-dir> --build  # 额外实构 deb 并核对产物
 ```
 
-任一 FAIL：停下修复（引导用 create-makefile skill 补齐），不要绕过校验继续发布。
-完整要求见 [contract.md](references/contract.md)。存量项目未接契约时走第 6 节
-fallback；成功交付一次后引导用户迁移到契约。
+契约 FAIL 或轨道工具缺失：停下，转入「初始化」按契约补齐 `makefile.builder`，
+不要绕过校验继续发布，不要改用户 Makefile。只缺发布键：允许构建，禁止上传。
+完整要求见 [contract.md](references/contract.md)。存量项目未接契约时走
+「存量项目 fallback」；成功交付一次后引导用户迁到 `makefile.builder`。
 
 ### 1. 确认发布边界
 
@@ -56,8 +120,8 @@ fallback；成功交付一次后引导用户迁移到契约。
 ### 2. 构建
 
 ```bash
-make build ARCH=<amd64|arm64> VERSION=<version>   # 主产物
-make deb   ARCH=<amd64|arm64>                     # DEB 项目
+make -f makefile.builder build ARCH=<amd64|arm64> VERSION=<version>   # 主产物
+make -f makefile.builder deb   ARCH=<amd64|arm64>                     # DEB 项目
 ```
 
 版本缺省按契约「版本号」从 Git 祖先稳定 tag 推导（正式 = HEAD exact-match
@@ -78,7 +142,7 @@ verify_deb.sh 输出元数据、关键内容清单和 SHA-256。匹配到多个
 
 ### 4. 发布
 
-优先 `make push[-deb|-docker]`（契约要求的薄包装）；直接调用等价：
+优先 `make -f makefile.builder push[-deb|-docker]`（契约要求的薄包装）；直接调用等价：
 
 ```bash
 DEB_SERVER_URL=… DEB_TOKEN=… DEB_REPOSITORY=… \
@@ -115,21 +179,23 @@ rg -n -i --hidden --glob '!.git' \
   'build-deb|upload-deb|publish-deb|dpkg-deb|debuild|curl.*deb|\.deb\b|aptly|reprepro'
 ```
 
-重点检查 Makefile、CI 配置、`debian/`、构建脚本和发布文档中的入口、变量传递方式、
-端点与认证方式。优先复用已有构建入口；上传仍用 builder 脚本。交付后引导迁移到契约
-（create-makefile + check.py 通过为准）。
+重点检查用户 Makefile、CI 配置、`debian/`、构建脚本和发布文档中的入口、变量传递方式、
+端点与认证方式。优先复用已有构建入口；上传仍用 builder 脚本。交付后引导迁移到
+`makefile.builder`（`templates/makefile.builder` + `check.py` 通过为准）。
 
 ## 修改 builder 自身时
 
 - 上传/发布脚本是 SSOT：通用行为修改落在 `skills/builder/scripts/`，不同步复制到
-  业务项目。产物版本只通过 `scripts/version.sh` 推导，不要在项目 Makefile 内联
+  业务项目。产物版本只通过 `scripts/version.sh` 推导，不要在 `makefile.builder` 内联
   `git describe` 或 `sort -V`。
-- 契约变更先改 `scripts/check.py`，再同步 `references/contract.md`。
+- 契约变更先改 `scripts/check.py`，再同步 `references/contract.md` 与
+  `templates/makefile.builder`。
 - 可用 `bash -n` 检查脚本语法；有 ShellCheck 时一并运行。
 - 不通过真实生产上传测试脚本，除非用户明确授权并给出测试版本/仓库。
 
 ## 完成标准
 
+- 初始化/检查：报告为完成、部分完成或阻塞；待配置项含文件、字段和示例。
 - 仅分析：入口、调用链、配置来源和风险已被准确说明。
 - 仅校验：check.py 结果逐条可解释，修复建议明确。
 - 仅构建：产物已生成并通过 verify_deb.sh，未发生上传。