feat(ack): add one-off delivery routing

Merge pull request 'feat(ack): add project delivery workflow' (#4 ) from add-extro-info into main
Reviewed-on: laily/.skills#4
2026-08-01 15:25:15 +08:00 · 2026-08-01 14:24:32 +08:00 · 2026-08-01 12:35:42 +08:00 · 2026-08-01 10:19:39 +08:00 · 2026-07-31 23:58:47 +08:00 · 2026-07-31 23:34:13 +08:00
90 changed files with 25515 additions and 392 deletions
@@ -1,12 +1,12 @@
 # Agent Skills 仓库

-自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容在本仓库维护；安装与管理由 [skiff](https://git.yumee.top/laily/skiff) CLI 负责。
+自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。Skill 内容、规范包与可运行的 skiff CLI 在本仓库一并维护。


 | 仓库              | 地址                                                                       | 职责                         |
-| --------------- | ------------------------------------------------------------------------ | --------------- |
-| **skills**（本仓库） | [https://git.yumee.top/laily/skills](https://git.yumee.top/laily/skills) | skill 内容与规范     |
-| **skiff**       | [https://git.yumee.top/laily/skiff](https://git.yumee.top/laily/skiff)   | 安装、symlink、健康检查 |
+| --------------- | ------------------------------------------------------------------------ | -------------------------- |
+| **skills**（本仓库） | [https://git.yumee.top/laily/skills](https://git.yumee.top/laily/skills) | skill、规范包、skiff CLI 的当前 SSOT |
+| **skiff**       | [https://git.yumee.top/laily/skiff](https://git.yumee.top/laily/skiff)   | skiff CLI 的独立来源 / 上游同步参考    |


 ---
@@ -15,13 +15,12 @@

 ```bash
 # 1. 克隆并关联
-git clone https://git.yumee.top/laily/skills.git ~/code/gitea/skills
-git clone https://git.yumee.top/laily/skiff.git ~/code/gitea/skiff
-cd ~/code/gitea/skiff && ./install.sh
-skiff setup ~/code/gitea/skills
+git clone https://git.yumee.top/laily/skills.git ~/.skills
+cd ~/.skills && ./install.sh

-# 2. 全局安装 skill
-skiff install declarative-openspec-loop
+# install.sh 会自动把 skiff 项目 skill 安装到所有 Agent
+# 2. 安装其他 skill
+skiff add declarative-openspec-loop -g

 # 3. 查看状态
 skiff list
@@ -35,49 +34,84 @@ skiff status
 ```
 skills/
 ├── _template/                  # 新建 skill 的脚手架
-├── declarative-openspec-loop/  # 自研 skill
+├── ack/                        # 完整 ACK skill，含 references/templates/scripts
+├── declarative-openspec-loop/  # 自研 skill，必须含 SKILL.md
 │   ├── SKILL.md
 │   └── reference.md
 ├── discussion-notes/           # 讨论沉淀笔记
 │   ├── SKILL.md
 │   └── reference.md
-registry.yaml                   # 外部 Git skill 来源目录
+skiff/                          # CLI 源码（Python 3）
+bin/skiff                       # CLI 入口
+catalog.yaml                   # skiff 预置 Skill 来源目录
 AGENTS.md                       # 本文档
 ```

-**本仓库包含**：`skills/`、`registry.yaml`、`AGENTS.md`  
-**本仓库不包含**：CLI 代码、各项目的 skill 启用清单
+**本仓库包含**：`skills/`、`skiff/`、`bin/skiff`、`catalog.yaml`、`AGENTS.md`
+**本仓库不包含**：各项目的 skill 启用清单

 ---

 ## Skill 目录

-### 自研（Owned）
+### 内置（Builtin）


 | Skill                                                                  | 说明                                                |
 | ---------------------------------------------------------------------- | ------------------------------------------------- |
+| [ack](skills/ack/SKILL.md)                                             | ACK 入口：显式初始化、检查并运行项目三角色协作闭环                  |
+| [skiff](skills/skiff/SKILL.md)                                         | 本项目工作流：创建、使用、反馈与更新 builtin skill               |
 | [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 |
 | [discussion-notes](skills/discussion-notes/SKILL.md)                   | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md                 |


 新建 skill：复制 `skills/_template/` → `skills/<name>/`，编辑 `SKILL.md`，在本仓库 commit。

-### 外部（External Git）
+Skill 需要的稳定规范、模板、示例和脚本直接放在自己的目录中，例如
+`skills/ack/references/`、`templates/`、`examples/` 和 `scripts/`。项目初始化只生成
+项目状态，不复制或链接 Skill 内容：

-在 `registry.yaml` 中注册，通过 skiff 拉取安装：
+```bash
+skiff init ack
+```
+
+### 预置目录（Catalog）
+
+在 `catalog.yaml` 中预置，通过 skiff 拉取安装：


-| Skill       | 来源                                                                         |
-| ----------- | -------------------------------------------------------------------------- |
-| superpowers | [https://github.com/obra/superpowers](https://github.com/obra/superpowers) |
+| Source | 来源 |
+| --- | --- |
+| waza | [https://github.com/tw93/Waza](https://github.com/tw93/Waza) |


 ```bash
-skiff fetch superpowers
-skiff install-external superpowers
+skiff fetch waza
+skiff add waza/think -g
 ```

+### 自定义仓库（Custom Sources）
+
+公司或团队维护、且一个仓库中包含多个 skill 时，使用命名 custom source：
+
+```bash
+skiff source add company \
+  git@git.company.com:platform/agent-skills.git \
+  --skills-path skills
+skiff list --source company
+skiff add company/internal-review -g
+```
+
+也可以接入已有本地 checkout：
+
+```bash
+skiff source add company --local ~/code/company-skills --skills-path skills
+```
+
+配置保存在 `~/.config/skiff/config.yaml`，Git source 默认 clone 到
+`~/.local/share/skiff/sources/<source>/`。项目 `.skills.yaml` 只记录逻辑
+source 名称，每台机器独立配置实际仓库地址。
+
 ### 社区（External NPM / GitHub）

 推荐使用 Vercel CLI 安装第三方 skill：
@@ -94,7 +128,8 @@ npx skills find typescript
 1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`，不在 Agent 目录直接创建
 2. **项目自治** — 每个项目自己维护 `.skills.yaml`，本仓库不维护项目清单
 3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
-4. **仓库分离** — skill 内容与 CLI 工具分仓库，互不影响更新
+4. **能力内聚** — Skill 使用的规范、模板和脚本与 `SKILL.md` 同目录维护
+5. **一体维护** — skill 与 CLI 同仓库维护；需要时再与独立 skiff 仓库同步

 ---

@@ -103,7 +138,8 @@ npx skills find typescript
 ```
 skills 仓库（本仓库）              skiff CLI
 skills/<name>/              ←──   skiff install / enable
-registry.yaml               ←──   skiff add / fetch
+skiff/                      ←──   python3 -m skiff
+catalog.yaml               ←──   skiff add / fetch
         ↑
    ~/.skills（symlink）
         │
@@ -119,10 +155,17 @@ registry.yaml               ←──   skiff add / fetch

 | 层级               | 位置                                 | 维护方式                            |
 | ---------------- | ---------------------------------- | ------------------------------- |
-| **Owned**        | `skills/<name>/`                   | 本仓库 commit                      |
-| **External Git** | `~/.local/share/skills/externals/` | `skiff fetch`                   |
+| **Builtin**        | `skills/<name>/`                   | 本仓库 commit                      |
+| **Catalog** | `catalog.yaml` + checkout 缓存 | `skiff catalog add / fetch` |
+| **Custom Source** | `~/.local/share/skiff/sources/` 或本地路径 | `skiff source add/fetch` |
 | **External NPM** | `node_modules/`                    | `npx skills add` / `skills-npm` |

+### 非 Skill 资料分类
+
+| 类型 | 位置 | 维护方式 |
+| --- | --- | --- |
+| **OpenSpec 配置** | `openspec/` | 本仓库 commit；服务于本仓库自身的规格流程 |
+

 ### 多 Agent 路径

@@ -143,10 +186,12 @@ registry.yaml               ←──   skiff add / fetch
 ```yaml
 # .skills.yaml（在项目根目录）
 skills:
-  - declarative-openspec-loop
-  - name: superpowers
-    source: registry
-    ref: main
+  - name: declarative-openspec-loop
+    source: builtin
+  - name: think
+    source: catalog:waza
+  - name: internal-review
+    source: company

 targets:          # 可选，默认 all
  - cursor
@@ -163,7 +208,7 @@ targets:          # 可选，默认 all
 | `skiff sync`   | `npm ci`                    |


-项目级命令（skiff 待实现）：
+项目级命令：

 ```bash
 cd ~/code/my-app
@@ -183,23 +228,23 @@ skiff sync

 | 命令                                     | 说明                  |
 | -------------------------------------- | ------------------- |
-| `skiff setup <path>`                   | 关联 `~/.skills` 到本仓库 |
+| `skiff bootstrap`                      | 将 skiff 项目 skill 全局安装到所有 Agent |
 | `skiff list`                           | 列出所有 skill          |
 | `skiff status`                         | 安装状态总览              |
-| `skiff install <name>`                 | 全局安装（symlink）       |
-| `skiff uninstall <name>`               | 移除 symlink          |
-| `skiff add / fetch / install-external` | 外部 Git skill        |
+| `skiff add <name> [-g]`                | 项目或全局安装（symlink） |
+| `skiff remove <name> [-g]`             | 移除 symlink |
+| `skiff catalog add` / `skiff fetch`    | 管理和拉取 catalog source |


-### 待实现
+### 草稿与健康检查


 | 命令 | 说明 |
-| ------------------------ | --------------------------- |
-| `skiff enable / disable` | 项目级启用/关闭                    |
-| `skiff sync`             | 按 `.skills.yaml` 重建 symlink |
-| `skiff create`           | 从 `_template/` 脚手架创建 skill  |
-| `skiff doctor`           | symlink 健康检查                |
+| --- | --- |
+| `skiff create <name> --idea TEXT [--from-project PATH]` | 从 `_template/` 创建草稿 |
+| `skiff check <name>` | 校验草稿或正式 skill |
+| `skiff finalize <name>` | 校验并将草稿转为正式 skill |
+| `skiff doctor [--fix]` | symlink 健康检查与修复 |


 ---
@@ -234,11 +279,12 @@ description: >-

 ### 新建流程

-1. `cp -r skills/_template skills/my-skill`
-2. 编辑 `skills/my-skill/SKILL.md`
-3. `skiff install my-skill --target cursor` 验证
-4. 在本仓库 commit
-5. 各项目 `skiff enable my-skill`（待实现）
+1. `skiff create my-skill --idea "..." --from-project .`
+2. Agent 编辑 `~/.skills/.drafts/my-skill/SKILL.md`
+3. `skiff check my-skill`
+4. 用户确认后执行 `skiff finalize my-skill`
+5. `skiff add my-skill -a cursor -g -y` 验证
+6. 在本仓库 commit；需要的项目再用 `skiff add my-skill` 启用

 **禁止**在 `~/.cursor/skills/` 或项目 Agent 目录直接创建非 symlink 的 skill。

@@ -265,7 +311,7 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入
 | -------------- | ----------------------------------------------------- |
 | Cursor / Codex | symlink，正常                                            |
 | Claude Code    | symlink 单个 skill 目录，不要 symlink 整个 `~/.claude/skills/` |
-| symlink 被替换    | `skiff doctor`（待实现）→ 重建 symlink                       |
+| symlink 被替换    | `skiff doctor --fix` → 重建 symlink                         |


 ---
@@ -288,8 +334,8 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入

 | 我要…        | 命令                                | 在哪   |
 | ---------- | --------------------------------- | ---- |
-| 首次 setup   | `skiff setup ~/code/gitea/skills` | 任意   |
-| 新建 skill   | 复制 `_template/` → 编辑 → commit     | 本仓库  |
+| 首次安装       | `git clone <repo> ~/.skills && ~/.skills/install.sh` | 任意   |
+| 新建 skill   | `skiff create` → Agent 完善 → `check/finalize` | 任意项目 |
 | 全局启用       | `skiff install <name>`            | 任意   |
 | 项目启用       | `skiff enable <name>`             | 项目目录 |
 | 看状态        | `skiff status`                    | 任意   |
@@ -306,4 +352,3 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入
 - [Vercel skills CLI](https://github.com/vercel-labs/skills)
 - [skills.sh](https://skills.sh)
 - [Cursor Skills 文档](https://cursor.com/docs/context/skills)
-
@@ -5,12 +5,12 @@
 ## 快速开始

 ```bash
-git clone https://git.yumee.top/laily/skills.git ~/code/gitea/skills
-cd ~/code/gitea/skills
-./install.sh
-skiff setup ~/code/gitea/skills
+git clone https://git.yumee.top/laily/skills.git ~/.skills
+cd ~/.skills
+./install.sh  # 安装 CLI，并将 skiff 项目 skill 安装到所有 Agent

-skiff install declarative-openspec-loop
+skiff add declarative-openspec-loop -g
+skiff select  # 交互式选择并批量安装
 skiff list
 skiff status
 ```
@@ -18,42 +18,58 @@ skiff status
 ## 仓库结构

 ```
-skills/           # 自研 skill（SSOT）
+skills/           # 自研 skill（SSOT）：每个子目录必须有 SKILL.md
 skiff/            # CLI 源码（Python 3）
 bin/skiff         # CLI 入口
-registry.yaml     # 外部 Git skill 目录
+catalog.yaml      # skiff 预置 Skill 来源目录
 AGENTS.md         # 详细规范与架构说明
 ```

 | 路径 | 说明 |
 |------|------|
-| [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md` |
+| [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md`，可附带 references、templates 和 scripts |
 | [skiff/](skiff/README.md) | 安装、软链、健康检查 CLI |
-| [registry.yaml](registry.yaml) | 外部 Git skill 注册表 |
+| [catalog.yaml](catalog.yaml) | skiff 预置 Skill 来源目录 |
 | [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 |

 ## 自研 Skill

 | Skill | 说明 |
 |-------|------|
+| [ack](skills/ack/SKILL.md) | 显式初始化、检查并运行 ACK 三角色协作及可选交付闭环 |
+| [skiff](skills/skiff/SKILL.md) | 在项目中创建、安装、反馈和维护 builtin skill |
 | [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 |
 | [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记 |

+ACK 是包含规范、模板与校验脚本的完整 Skill。安装 Skill 后可初始化当前项目状态：
+
+```bash
+skiff init ack
+skiff init ack --project ~/app
+```
+
+初始化会生成默认关闭的 `docs/ack/delivery.yaml`；项目可用自然语言让 `/ack` 维护
+DEB、镜像、PR、发布与部署 profile，任务验证通过后再按已确认计划执行。
+
 新建 skill：

 ```bash
-skiff create my-skill    # 从 _template/ 脚手架创建
-# 编辑 skills/my-skill/SKILL.md
-skiff install my-skill   # 全局安装验证
+skiff create my-skill --idea "描述要解决的重复问题" --from-project .
+# 由 Agent 完善 ~/.skills/.drafts/my-skill/SKILL.md
+skiff check my-skill
+skiff finalize my-skill
+skiff add my-skill -g   # 全局安装验证
 ```

+项目里使用 skill 发现通用问题或优化时，让 Agent 按 `skiff` skill 收集实际结果与期望结果，修改 `~/.skills/skills/<name>/` 的 SSOT，并执行 `skiff check <name>`。项目专属规则保留在项目内，不回流到通用 skill。
+
 ## 安装方式

 ### 全局（用户级）

 ```bash
-skiff install <name>                  # 安装到 ~/.cursor/skills/ 等
-skiff install <name> --target cursor
+skiff add <name> -g                   # 安装到 ~/.cursor/skills/ 等
+skiff add <name> -g -a cursor
 ```

 ### 项目级
@@ -62,10 +78,10 @@ skiff install <name> --target cursor

 ```yaml
 skills:
-  - declarative-openspec-loop
-  - name: superpowers
-    source: registry
-    ref: main
+  - name: declarative-openspec-loop
+    source: builtin
+  - name: think
+    source: catalog:waza

 targets:          # 可选，默认 all
  - cursor
@@ -74,18 +90,25 @@ targets:          # 可选，默认 all
 ```

 ```bash
-skiff enable declarative-openspec-loop
+skiff add declarative-openspec-loop
 skiff sync
-skiff disable declarative-openspec-loop
+skiff remove declarative-openspec-loop
 ```

-## 外部 Skill
+## Catalog 与 Custom Source

-**Git 来源**（经 skiff 管理）：
+安装 catalog 中预置的来源：

 ```bash
-skiff fetch superpowers
-skiff install-external superpowers
+skiff fetch waza
+skiff add waza/think -g
+```
+
+接入团队自己的本地目录或 Git 仓库：
+
+```bash
+skiff source add company --local ~/code/company-skills --skills-path skills
+skiff add company/internal-review -g
 ```

 **社区来源**（Vercel CLI）：
@@ -100,7 +123,7 @@ npx skills find typescript
 ```
 本仓库
 ├── skills/<name>/     ←── skiff install / enable
-├── registry.yaml      ←── skiff add / fetch
+├── catalog.yaml       ←── 预置来源发现与 fetch
 └── skiff/             ←── python3 -m skiff
         ↑
    ~/.skills（symlink）
@@ -117,7 +140,8 @@ npx skills find typescript
 1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`
 2. **项目自治** — 各项目自行维护 `.skills.yaml`
 3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
-4. **一体维护** — skill 与 CLI 同仓库，Python 3 直接运行，无需编译
+4. **能力内聚** — Skill 所需规范、模板和脚本与 `SKILL.md` 放在同一目录
+5. **一体维护** — skill 与 CLI 同仓库，Python 3 直接运行，无需编译

 ## 文档

@@ -1,5 +1,14 @@
 #!/usr/bin/env bash
 set -euo pipefail
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# 跟随软链，确保从 ~/.local/bin/skiff 调用时仍能找到仓库根目录
+SCRIPT="${BASH_SOURCE[0]}"
+while [ -L "$SCRIPT" ]; do
+  link_dir="$(cd "$(dirname "$SCRIPT")" && pwd)"
+  SCRIPT="$(readlink "$SCRIPT")"
+  [[ "$SCRIPT" != /* ]] && SCRIPT="$link_dir/$SCRIPT"
+done
+REPO_ROOT="$(cd "$(dirname "$SCRIPT")/.." && pwd)"
+
 export PYTHONPATH="${REPO_ROOT}${PYTHONPATH:+:$PYTHONPATH}"
 exec python3 -m skiff "$@"
@@ -0,0 +1,31 @@
+# Preconfigured Skill source catalog
+# Format:
+#   <name>:
+#     repo: <git-url>
+#     ref: <branch|tag>     (default: main)
+#     path: <subpath>       (default: .)
+#     description: <text>   (optional, shown by `skiff select`)
+#     tags:                 (optional)
+#       - <tag>
+#
+# Single-skill example (`path` contains SKILL.md):
+#   example-skills:
+#     repo: https://github.com/example/skills
+#     ref: main
+#     path: .
+#
+# Collection example (`path` contains skill directories):
+#   example-collection:
+#     repo: https://github.com/example/skill-collection
+#     ref: main
+#     path: skills
+
+waza:
+  repo: https://github.com/tw93/Waza.git
+  ref: main
+  path: skills
+  description: Waza engineering workflow skills for planning, UI, review, debugging, writing, research, reading, and agent health.
+  tags:
+    - engineering
+    - workflow
+    - skill-collection
@@ -0,0 +1,752 @@
+---
+title: ACK 设计评审记录
+date: "2026-07-31T17:15:37+08:00"
+updated: "2026-07-31T23:31:48+08:00"
+---
+
+# ACK 设计评审记录
+
+> 这是对 ACK v0.8.1 的设计评审快照，用于推动后续版本改进。文中的文件行号对应
+> 2026-07-31 的仓库状态，不作为 ACK 的运行规范。
+
+本文同时记录后续方案和实施结果。带“建议”“目标”或“待验证”的内容默认是设计
+方向，不代表当前版本已经具备；实际运行契约仍以 `skills/ack/SKILL.md`、schema、
+校验器和测试为准。知识护栏方案的 v0.9.0 落地边界、model-routing v0.10.0 的
+实施结论见下文状态表。
+
+## 背景
+
+本轮评审覆盖 `skills/ack/` 的入口、角色规范、闭环流程、项目模板、任务板
+schema、校验脚本、Orca 适配器，以及 `skiff init ack` 的真实运行路径。
+
+评审主要回答两个问题：
+
+- ACK 的三角色协作方向是否合理。
+- 当前实现是否已经能稳定完成初始化、派发、独立复测、状态恢复和结果审计。
+
+## 结论
+
+ACK 的核心方向合理。显式触发、三角色分权、可观测验收、用户确认、Test 独立
+复测、Coordinator 单写任务板和三轮止损都值得保留。
+
+当前版本适合描述为“任务级受监督验收闭环”。它可以组织单个工作空间里的实现和
+复测，但还没有覆盖批准状态持久化、跨 worktree 交接、编排状态恢复、目标分支集成
+和交付状态，因此暂时不应把 `verified` 等同于“已集成”或“已交付”。
+
+概念设计约为 8/10，当前可操作性约为 5 至 6/10。下一阶段应该补齐控制面契约，
+不需要推翻三角色模型。
+
+## 值得保留的设计
+
+- Coordinator、Developer 和 Test 的职责分开，Developer 不能给自己的实现做最终
+  判定。
+- 新需求先写产品文档、任务拆分和可观测验收信号，用户确认后再派发。
+- `tasks.yaml` 由 Coordinator 单写，worker 消息只负责传递证据。
+- Test 在复测前核对 worktree、服务实例和构建产物，减少测错代码和旧进程造成的
+  假通过。
+- 每个任务最多三轮，失败后进入 `leftover`，不会无限消耗同一个 worker。
+- 通用规范留在 Skill，项目只保存覆盖层与任务状态。
+- 闭环核心不依赖 Orca，手动模式仍能保留相同的角色与验收逻辑。
+
+## P0：状态和证据必须先成为可验证协议
+
+### `verified` 目前可以没有证据
+
+`roles-and-permissions.md` 定义的完成条件包括 Developer 白盒证据、Test 独立证据、
+环境对齐和 Coordinator 终检，但任务 schema 只强制 `id`、`title` 和 `status`。
+内置校验器同样没有检查 `verified` 所需的证据。
+
+本轮探针确认，下面这种任务可以通过内置校验：
+
+```yaml
+version: 1
+project:
+  name: demo
+tasks:
+  - id: T-1
+    title: hollow green
+    status: verified
+```
+
+相关位置：
+
+- `skills/ack/templates/tasks.schema.json:76`
+- `skills/ack/scripts/validate_tasks.py:70`
+- `skills/ack/references/roles-and-permissions.md:140`
+
+建议为不同状态定义语义约束。`verified` 至少要求：
+
+- Developer 的修改文件、验证命令和结果。
+- 独立 Test 的身份、逐条验收结果和原始证据。
+- 被测代码或构建产物的不可变指纹。
+- worktree、服务进程、Base URL 和测试时间。
+- Coordinator 的 gate 结果与写入时间。
+
+### 用户确认没有持久化
+
+Skill 要求用户确认后再派发，但状态机从 `open` 直接进入 `dispatched`。会话在确认前
+中断后，新的 Coordinator 无法知道任务是待确认，还是已经批准。
+
+建议增加 `proposed` 和 `approved`，并记录 `approvedAt`、`approvedBy` 与验收版本。
+
+### 推荐状态流
+
+```text
+proposed
+  -> approved
+  -> implementing
+  -> retesting
+  -> verified_in_workspace
+  -> integrated
+  -> verified
+
+blocked
+  -> approved
+  -> cancelled
+
+product_failed x 3
+  -> leftover
+```
+
+`verified_in_workspace` 只说明指定工作空间中的代码已经通过独立复测。只有目标分支
+集成并完成集成后验证，才能进入最终 `verified`。
+
+## P0：Orca 适配器需要改成双任务模型
+
+当前文档让 Developer 对一个 Orca task 发送 `worker_done`，然后把同一个 task 再次
+派给 Test。截至评审日期，当前 Orca 的 orchestration 规则会在收到有效
+`worker_done` 后自动把 task 和 dispatch 标记为 completed。第二次派发同一个 task
+缺少可靠的生命周期语义。
+
+相关位置：
+
+- `skills/ack/references/orca-adapter.md:144`
+- `skills/ack/references/orca-adapter.md:164`
+- `skills/ack/references/orca-adapter.md:199`
+
+建议每个 ACK attempt 创建两个 Orca 子任务：
+
+```text
+ACK task
+  Developer task
+  Test task, depends on Developer task
+```
+
+任务板分别保存：
+
+```yaml
+devTaskId: null
+devDispatchId: null
+testTaskId: null
+testDispatchId: null
+```
+
+Developer 和 Test 都对自己的 dispatch 发送 `worker_done`，Coordinator 最后只读
+证据并执行 gate。
+
+## P0：明确 worktree 和代码交接方式
+
+当前流程先在 Coordinator worktree 写 PRD 和 `tasks.yaml`，随后才决定是否创建隔离
+worktree。权威任务板只保留在 Coordinator worktree，但 worker prompt 又要求在自己
+的 worktree 读取相对路径。Developer 的未提交代码如何传给独立的 Test worktree
+也没有定义。
+
+相关位置：
+
+- `skills/ack/references/kickoff.md:30`
+- `skills/ack/references/closed-loop.md:65`
+- `skills/ack/references/closed-loop.md:87`
+- `skills/ack/references/prompt-templates.md:31`
+- `skills/ack/references/orca-adapter.md:74`
+
+建议默认让 Developer 和 Test 串行使用同一个 worktree。必须隔离时，在 attempt 中
+明确：
+
+```yaml
+transfer:
+  type: commit | patch | artifact
+  source: "<immutable reference>"
+  digest: "<sha256 or diff hash>"
+```
+
+派发内容应携带验收快照和规范的绝对路径，不能假设每个 worktree 都有同一份未提交
+文档。
+
+## P0：Worker 启动策略改为安全默认
+
+> v0.10 已以结构化 profile 和可信 launcher 取代本节描述的自由 command。下方是
+> 当时的评审记录，不再代表当前实现；其中“full-access 写入任务板授权”的建议已被
+> v0.10 决策取代，当前明确为 Deferred。
+
+当前校验器强制 Codex 使用 bypass、Cursor 使用 YOLO，并写死模型和 CLI。项目文档
+允许收紧权限或替换模型，但合法的安全覆盖会被校验器拒绝。
+
+校验器还只检查自由 shell 字符串里的部分 token。本轮探针确认，带有 shell 控制符
+和额外命令的字符串仍可通过校验。这样的结果会给调用方错误的安全感。
+
+相关位置：
+
+- `skills/ack/scripts/validate_worker_command.py:49`
+- `skills/ack/references/model-routing.md:98`
+- `skills/ack/templates/project.template.md:31`
+
+建议把项目覆盖层改成结构化配置：
+
+```yaml
+orchestration:
+  mode: orca
+
+workers:
+  developer:
+    cli: codex
+    model: "<project-approved-model>"
+    effort: medium
+    permissionMode: sandbox
+  test:
+    cli: codex
+    model: "<project-approved-model>"
+    effort: low
+    permissionMode: sandbox
+```
+
+可信代码根据这些字段构造 argv，不接受自由 shell 拼接。安全模式默认通过。
+原建议设想 full-access 由用户单独授权并写入任务板；v0.10 没有实现这条授权通道，
+项目文件也不能充当授权证据。full-access 的可信授权、期限、撤销和外层隔离均为
+Deferred，当前 launcher 必须 fail closed。
+
+## P0：初始化需要原子化
+
+`skiff init ack` 会先写 `project.md` 和 `tasks.yaml`，再运行任务板校验。缺少 PyYAML
+时，命令会失败但保留两个文件。再次运行又会因为拒绝覆盖而失败。
+
+相关位置：
+
+- `requirements.txt:1`
+- `skills/ack/scripts/validate_tasks.py:37`
+- `skiff/cli.py:1144`
+- `skiff/cli.py:1156`
+
+本轮在不含第三方包的隔离 Python 环境中复现了这个状态。
+
+建议：
+
+- 在临时目录渲染和校验，全部通过后再原子 rename。
+- 失败时只清理由本次调用创建的临时文件。
+- 提供 `skiff init ack --repair` 或等价恢复路径。
+- 默认模板使用 `tasks: []`，完整示例继续放在 `examples/`。
+- CLI 输出“脚手架已创建，待配置”，检查通过后再称为“初始化完成”。
+
+## P1：任务板改成追加式 attempts
+
+当前 `dispatch.rounds` 只记录轮次、结果和一段证据，无法支持恢复、并发和审计。
+建议改成追加式 `attempts[]`：
+
+```yaml
+attempts:
+  - id: "T-1-A1"
+    round: 1
+    idempotencyKey: "<stable key>"
+    startedAt: "<timestamp>"
+    workspace:
+      path: "<worktree>"
+      baseCommit: "<sha>"
+      diffHash: "<hash>"
+    developer:
+      worker: "<identity>"
+      taskId: "<runtime task id>"
+      dispatchId: "<runtime dispatch id>"
+      evidence: {}
+    test:
+      worker: "<independent identity>"
+      taskId: "<runtime task id>"
+      dispatchId: "<runtime dispatch id>"
+      evidence: {}
+    gate:
+      result: pending | passed | failed
+    failureKind: null
+```
+
+`failureKind` 建议区分：
+
+- `product_failed`：实现不满足验收，消耗三轮预算。
+- `environment_blocked`：环境或服务不可用，不消耗轮次。
+- `needs_decision`：需要用户决定范围，不消耗轮次。
+- `acceptance_invalid`：验收标准有误，返回 `proposed`。
+- `worker_lost`：worker 消失，由 Coordinator 重新派发。
+
+外部 dispatch 前先持久化 intent。Coordinator 重启后，用 `idempotencyKey` 和 runtime
+ID 查询 Orca，再决定继续等待、恢复状态或重新派发。
+
+## P1：统一 schema 和语义校验
+
+安装 `jsonschema` 时，`validate_tasks.py` 只运行 schema；未安装时只运行内置规则。
+两条路径的约束不同。schema 会放过重复 ID、四轮 dispatch 和空
+`leftoverReason`，内置规则也会放过部分错误结构。
+
+建议：
+
+- 始终先执行 schema，再无条件执行语义 invariant。
+- 为 `structural` 和 `ready` 提供两个显式模式。
+- `ready` 模式检查状态对应的证据、环境、批准和轮次。
+- 显式传入的 schema 路径不存在时直接失败，不能静默降级。
+- `summary` 从 `tasks` 派生，避免双写。
+- 收紧 `additionalProperties`，扩展字段统一放入 `extensions`。
+
+## P1：补齐完成边界和批次验证
+
+ACK 默认不提交、不推送。隔离 worktree 中的任务即使复测通过，也可能尚未进入目标
+分支。最终报告需要明确区分：
+
+- 已在指定工作空间验证。
+- 已集成到目标分支。
+- 已完成集成后回归。
+- 已提交、已推送或已发布。
+
+多个任务分别通过后，还需要一次批次级集成回归，避免组合后出现冲突或行为变化。
+
+## P2：减少规范重复和模型漂移
+
+- 保留一份权威状态机、一份角色权限表和一份模型档位规则。
+- `kickoff.md` 只做一页运行手册，adapter 只保存工具命令。
+- 具体模型名称放到可更新的映射或项目覆盖层，稳定核心只描述能力档位和升级条件。
+- `ackVersion` 不能只记录旧版本。需要独立的 `schemaVersion`、兼容范围和迁移命令。
+- 用真实运行数据观察首轮通过率、环境失败率、平均轮次、`leftover` 原因、耗时和
+  token，再决定三轮规则是否需要按任务风险调整。
+- 为低风险文档或机械改动提供轻量模式，高风险和用户可见行为继续使用完整三角色
+  闭环。
+
+## 低成本清理
+
+- `skills/ack/SKILL.md:66` 的旧字段应为 `kitVersion`。
+- `skills/ack/templates/project.template.md:8` 建议修改或替换 `AGENTS.md`，与 Skill
+  的禁止规则冲突。
+- `skills/ack/references/orca-adapter.md:201` 应引用 prompt §4。
+- `skills/ack/scripts/validate_worker_command.py:2` 残留 “Music Pilot”。
+- `skills/ack/examples/tasks.example.yaml` 缺少 checklist 要求的 `overlayFile`。
+- Test 负责黑盒与集成测试，Developer 负责单元测试；当前优化文档对单元测试所有权
+  的表述需要统一。
+
+## 建议实施顺序
+
+1. 收紧任务状态、批准状态和 `verified` 证据门。
+2. 把 Orca adapter 改成每轮 Developer/Test 双任务。
+3. 定义同 worktree 默认策略和跨 worktree transfer。
+4. 改造 worker launcher 与安全授权。
+5. 原子化 `skiff init ack`，空任务板作为默认模板。
+6. 引入追加式 attempts、幂等恢复和失败分类。
+7. 统一 schema 与语义校验，补齐对抗性 fixture。
+8. 区分工作空间验证、集成验证和发布状态。
+9. 去重文档，补版本迁移和运行指标。
+
+## 验证记录
+
+本轮执行了：
+
+- `skiff check ack`：通过。这个命令只证明 Skill 的元数据和基础结构有效。
+- `validate_tasks.py examples/tasks.example.yaml`：通过，当前机器使用内置规则。
+- `validate_worker_command.py --self-test`：7 项通过。
+- `python3 -m unittest discover -s tests -v`：58 项通过。
+- 隔离全局安装 smoke：通过，安装结果为指向 ACK SSOT 的 symlink。
+- 隔离初始化探针：缺少 PyYAML 时失败，留下半初始化文件，重试被拒绝。
+- 对抗性任务板探针：无证据的 `verified` 可以通过。
+- 对抗性 worker 命令探针：附加 shell 控制符的命令字符串可以通过。
+- 当前 Orca orchestration 指南复核：有效 `worker_done` 会自动完成对应 task 和
+  dispatch。
+
+现有 ACK 测试主要覆盖字符串、Skill 元数据和初始化冒烟，没有覆盖状态机语义、
+schema 与 fallback 一致性、Orca 双阶段生命周期、Coordinator 崩溃恢复和跨 worktree
+代码交接。
+
+## 待验证
+
+- [ ] 用真实项目跑一轮同 worktree 的 Developer/Test 闭环。
+- [ ] 用独立 worktree 验证 commit、patch 和 artifact 三种交接方式。
+- [ ] 验证 Coordinator 在 task-create、dispatch 和 Test 完成三个时间点崩溃后的
+      恢复行为。
+- [ ] 为安全 worker profile、路径 containment 和 shell 注入增加对抗性测试。
+- [ ] 定义 ACK v0.9 的 schema 迁移策略，再决定是否保留旧状态名称。
+
+## 扩展方案：项目知识护栏库
+
+### v0.9.0 落地边界
+
+| 能力 | v0.9.0 状态 |
+|------|-------------|
+| `knowledge.yaml` 模板、schema、初始化和跨文件校验 | 已实现 |
+| active/stale/superseded/archived、作用域、冲突、复查时间和来源校验 | 已实现 |
+| 确定性选择、全项目规则优先、固定 revision 引用 | 已实现 |
+| registry ID + 结构化 argv + fd 固定根目录的安全检查入口 | 已实现 |
+| Developer candidate、Test check、Coordinator 单写的协作约定 | 已实现为协议和校验字段 |
+| 不同 revision 的历史内容不可篡改或可独立恢复 | 延后；v0.9.0 没有外部不可变账本 |
+| 依赖或路径变化后自动转 stale | 延后；当前由 `reviewAfter` 和人工复核驱动 |
+| 在运行时强制只有获授权身份能写入或激活知识 | 延后；当前依赖 Coordinator 单写边界 |
+| 自动识别任意提示注入、PII 或所有秘密 | 延后；当前只有结构禁区和常见秘密模式 |
+| `approved`、追加式 attempts、崩溃恢复和最终集成 gate | 延后到控制面改造 |
+
+### 定位
+
+ACK 需要增加第三类项目事实，用来保存跨任务复用、会改变后续开发或验证行为的已
+验证知识。它不保存聊天记忆，也不承担项目 Wiki 的职责。
+
+| 项目事实 | 保存内容 | 写入者 |
+|----------|----------|--------|
+| `project.md` | 相对稳定的项目配置、路径和命令 | Coordinator 或项目维护者 |
+| `tasks.yaml` | 当前任务状态、attempt 和执行证据 | Coordinator |
+| `knowledge.yaml` | 跨任务复用的已验证经验 | Coordinator |
+
+建议新增项目级 SSOT：`docs/ack/knowledge.yaml`。知识归项目所有，与 Orca 等编排
+工具无关；ACK 负责在任务闭环中生产、选择和消费这些知识。
+
+这项设计会修改当前“`docs/ack/` 只保存 `project.md` 与 `tasks.yaml`”的边界。
+新增文件保存项目事实，不复制 ACK Skill 的通用规范，因此不违反 Skill 内容仍以
+`skills/ack/` 为 SSOT 的原则。
+
+### 知识类型
+
+第一版只支持三类知识：
+
+| 类型 | 含义 | 例子 |
+|------|------|------|
+| `guardrail` | 必须执行或明确禁止的项目约束 | 修改数据库迁移时必须验证回滚 |
+| `pitfall` | 已证实的失败模式、触发条件和避免方法 | Test 连到了另一个 worktree 的旧服务 |
+| `verification` | 特定条件下必须增加的检查 | 修改缓存键后执行跨版本兼容测试 |
+
+架构决策正文继续写入 ADR 或正式规格，知识项只引用决策及其适用条件。任务进度和
+单次失败证据继续留在 `tasks.yaml`。通用且可跨项目复用的规则应回流 ACK Skill，
+不能作为某个项目的知识长期保存。
+
+### 生命周期
+
+```text
+Developer / Test 发现经验
+  -> candidate
+  -> Test 独立验证 + Coordinator gate
+  -> active
+  -> stale
+  -> superseded | archived
+```
+
+- Developer 和 Test 只能提交 candidate，不能直接写入或激活知识。
+- candidate 保存在当前 task 或 attempt 的证据中，不参与后续任务的自动选择。
+- 根因得到证实、修复通过独立 Test、Coordinator 完成 gate 后，candidate 才能转为
+  `active`。
+- 全项目范围的 `must`、`never` 或权限类规则需要 User 或 Decision Owner 确认。
+- 依赖、配置、路径或适用版本发生变化后，相关知识转为 `stale`，默认不再派发。
+- 新知识替代旧知识时必须记录 `supersedes`，不能静默改写历史。
+- 临时 workaround 必须有复查时间和移除条件，不能无限期保持 `active`。
+
+同一 Agent 不能把自己读到的旧知识直接作为新证据再次激活。新的 candidate 必须
+包含当前任务产生的独立观测，避免形成自我强化的错误闭环。
+
+### 最小数据结构
+
+每条知识至少包含：
+
+```yaml
+id: K-001
+revision: 1
+kind: pitfall
+status: active
+title: "复测前确认服务来自当前 worktree"
+
+scope:
+  components: [web]
+  paths: ["web/**"]
+  dependencies: []
+  versions: []
+  tags: [long-running-service]
+
+appliesWhen: "修改常驻 Web 服务或前端构建产物"
+directive: "复测前重启服务，并核对服务实例对应的 commit"
+rationale: "曾因复测旧进程产生假通过"
+
+verification:
+  ref: service-worktree-alignment
+  expected: "服务实例、worktree 和 commit 一致"
+
+provenance:
+  taskId: BUG-017
+  attemptId: BUG-017-A2
+  codeRef: "<commit or tree hash>"
+  evidenceRef: "tasks.yaml#BUG-017"
+
+owner: "<owner>"
+author: "<candidate author>"
+reviewer: "<independent reviewer>"
+createdAt: "<timestamp>"
+lastValidatedAt: "<timestamp>"
+reviewAfter: "<timestamp or null>"
+removalCondition: null
+supersedes: []
+conflictsWith: []
+```
+
+`revision` 是逻辑版本标识。修改知识的约束含义时必须新增 revision，并保留被引用
+的旧条目；任务引用 `K-001@1` 后，可以说明当时选择的逻辑版本。v0.9.0 尚未用
+content hash、签名或外部账本封存条目内容，因此不能只凭这个字符串证明历史字节
+不可变；项目需要把状态纳入版本控制，强不可变审计留待后续实现。
+
+`directive` 只能描述应采取的动作。需要执行命令时，`verification.ref` 应引用项目中
+已审查的测试或检查 ID，由可信配置解析成结构化 argv。知识库不保存可自动执行的
+自由 shell 命令。
+
+### 与三角色闭环的集成
+
+| 角色 | 权限和职责 |
+|------|------------|
+| Coordinator | 单写 `knowledge.yaml`；选择本轮适用知识；激活、废弃和处理冲突 |
+| Developer | 只读本轮知识；回报遵守情况；提交 `knowledgeCandidates` |
+| Test | 只读本轮知识；执行额外检查；独立验证 candidate |
+| User / Decision Owner | 批准全项目强制规则、权限规则和无法通过测试证明的政策 |
+
+`prepare(task)` 时，Coordinator 按 component、path、dependency、version、tag 和失败
+特征筛选 `active` 知识。匹配结果只作为候选，Coordinator 确认后把固定版本引用
+写入本轮上下文：
+
+```yaml
+knowledgeRefs:
+  - K-001@1
+  - K-014@2
+```
+
+引入前文建议的追加式 `attempts[]` 后，引用和回报建议放在：
+
+```text
+attempts[].context.knowledgeRefs
+attempts[].developer.knowledgeApplied
+attempts[].developer.knowledgeCandidates
+attempts[].test.knowledgeChecks
+```
+
+派发时把已引用知识的必要内容内联到 Developer 和 Test 的 prompt，避免 worker 因
+worktree 不同而读不到 Coordinator worktree 中未提交的知识文件。每次只派发当前
+任务命中的少量条目，不全量注入知识库。
+
+Developer 回报实际遵守了哪些知识，以及新发现的 candidate。Test 对每条适用的
+`verification` 回报 pass、fail 和证据。要求执行的知识检查没有覆盖时，
+Coordinator 不得把任务写成 `verified_in_workspace` 或 `verified`。
+
+### 检索和冲突规则
+
+第一版使用确定性匹配，不引入向量数据库、Embedding 或语义 RAG：
+
+- 先按 path、component、dependency、version 和 tag 选择条目。
+- 失败排查时可以额外匹配错误签名和相关 symbol。
+- 只返回 `active` 且适用条件成立的条目。
+- 设置条目数和上下文预算，详情按需读取。`scope.all=true` 的全项目规则优先占用
+  预算；全项目规则本身超过预算时显式失败，不能静默丢弃。
+- `stale`、`superseded` 和 `archived` 默认不返回。
+- 没有匹配结果只表示本轮没有找到知识，不能据此声称项目没有相关约束。
+
+同一 subject 和 scope 不能存在互相矛盾的 `active` 条目。校验器发现冲突时应阻止
+进入 ready 状态，由 Coordinator 或 Decision Owner 选择保留项并记录
+`supersedes`。运行时不能使用“最后写入者获胜”解决冲突。
+
+自动匹配只负责推荐。Coordinator 写入当前 attempt 的显式 `knowledgeRefs` 才是
+本轮权威上下文。这个边界可以降低作用域标注不准造成的漏选和误选。
+
+### 知识晋升后的去向
+
+知识库不是所有经验的最终归宿。不同内容应继续进入对应的权威载体：
+
+| 内容 | 最终位置 |
+|------|----------|
+| 当前任务状态和单次验证证据 | `tasks.yaml` |
+| 稳定项目路径、命令和运行配置 | `project.md` |
+| 架构或产品决策及其取舍 | ADR 或正式规格 |
+| 安全、正确性和兼容性约束 | 测试、lint、CI 或正式规范 |
+| 原始日志、截图和构建产物 | 受控 artifact 存储 |
+| 跨项目通用规则 | ACK Skill |
+| 项目特有且跨任务复用的经验 | `knowledge.yaml` |
+
+关键 `verification` 应逐步转成可执行测试或 CI gate。知识项继续保存触发条件、原因
+和证据引用，不能用自然语言规则替代可执行控制。
+
+### 禁止写入的内容
+
+- Token、密钥、Cookie、含凭据 URL、生产数据、PII、客户内容和未脱敏日志。
+- 系统提示、开发者提示、角色或权限覆盖，以及绕过审批、测试和安全限制的指令。
+- 可自动执行的破坏性命令或生产命令。
+- 原始聊天、整段 issue 或网页内容、巨量日志、截图和构建产物。
+- 未复现猜测、LLM 单方推断、一次性巧合和个人评价。
+- PID、临时端口、个人 worktree 绝对路径等短命机器状态。
+- 对代码、配置和正式文档的重复抄写。
+- 没有作用域、证据和失效条件的 `always`、`never` 或 workaround。
+- 需要权限隔离的漏洞 PoC、敏感内部拓扑和安全调查材料。
+
+issue、日志和外部网页只能作为不可信 evidence。进入知识库前必须提炼为可审查的
+项目结论，不能原样晋升，也不能获得高于用户指令、批准规格、当前代码、配置和测试
+的优先级。
+
+### 第一版范围
+
+第一版只实现一个 `docs/ack/knowledge.yaml`，不拆目录。活跃条目达到几十条、单文件
+开始影响审阅和选择时，再平滑迁移为 `docs/ack/knowledge/index.yaml` 加独立知识卡，
+条目 schema 和引用格式保持不变。
+
+第一版包括：
+
+1. `knowledge.yaml` schema 与语义校验。
+2. task 或 attempt 的 `knowledgeRefs`。
+3. Developer 的 `knowledgeApplied` 与 `knowledgeCandidates`。
+4. Test 的 `knowledgeChecks`。
+5. Coordinator 在 prepare、gate 和任务收尾三个节点处理知识。
+6. 基于 scope 的确定性匹配。
+7. stale、冲突、revision 和 supersedes 校验。
+
+第一版不包括：
+
+- 自动抓取或总结全部对话。
+- Agent 自动激活、删除或提交知识。
+- 向量数据库、Embedding 和语义 RAG。
+- 自动改写 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+- 从知识正文直接执行 shell 命令。
+- 组织级、跨仓库知识同步。
+
+### 目标验收与当前状态
+
+| 目标 | v0.9.0 状态 |
+|------|-------------|
+| candidate 不会作为 active 派发 | 已实现 |
+| 未授权 worker 不能激活、废弃或删除知识 | 协议约束；运行时身份授权延后 |
+| path、component、version 只返回匹配条目 | 已实现确定性匹配；准确率仍取决于 scope 标注 |
+| 非 active 条目默认不返回 | 已实现 |
+| 冲突 active 规则被拒绝 | 已实现显式冲突和相同 subject/scope 检查 |
+| 历史 attempt 的知识内容不可变 | 延后；当前只有 revision 约定，没有不可变账本 |
+| `verification.ref` 无法解析时校验失败 | 已实现 |
+| evidence 中的提示注入不会变成命令 | 部分实现；禁止自由执行字段，语义晋升仍需人工 gate |
+| 秘密和生产数据不能进入知识库 | 部分实现；常见秘密模式会阻断，不能替代完整 DLP |
+| 依赖、路径变化后自动转 stale | 延后；当前依赖复查日期和 Coordinator |
+| 增长后仍在预算内且不漏全项目规则 | 已实现；全项目规则超预算时显式失败 |
+
+### 与 ACK 改造顺序的关系
+
+知识护栏库最终仍依赖可信的任务状态、attempt、证据来源和 ready 校验。v0.9.0 先
+落地存储、选择和基础 gate，不能据此声称前述控制面问题已经解决。后续应继续：
+
+1. 确定知识 schema、生命周期和角色权限。
+2. 在 attempt 中固定 `knowledgeRefs` 和 candidate 证据。
+3. 接入 Coordinator 的匹配、派发和晋升流程。
+4. 增加 stale、冲突、权限、注入和敏感信息的对抗性 fixture。
+5. 选一个真实项目试运行，再根据活跃条目数量决定是否拆分存储。
+
+这套方案最依赖 scope 标注的质量。项目知识如果很难用组件、路径、依赖、版本或
+触发条件限定，自动匹配会漏掉关键项或产生大量噪声。这类知识应继续由人维护在 ADR
+或项目文档中，不能强行进入自动派发流程。
+
+## v0.10.0 实施结论：结构化 model-routing
+
+### 当前决策
+
+旧的 `validate_worker_command.py --command '<shell>'` 只能检查少量 token，无法证明
+整段 shell 没有追加命令、重复参数、环境注入或 cwd 漂移。v0.10 删除这条自由命令
+配置面：旧脚本只保留 fail-closed 迁移提示；自动 worker 的唯一入口是
+`launch_worker.py profile-hash|plan|launch`。
+
+机器 SSOT 固定为 `tasks.yaml.project.orchestration`。profile 只声明 role、CLI、
+tier、model、reasoning effort 和 permission mode；model 必须命中按
+CLI/role/tier 分组的 allowlist。自动权限只允许 `read-only` 与
+`workspace-write`，full-access、Codex bypass、Cursor YOLO/force 和关闭 sandbox
+全部 fail closed。
+
+### 已落地约束
+
+| 控制面 | v0.10.0 实现 |
+|--------|--------------|
+| 自由 command / extra argv / env / cwd | schema 与语义校验拒绝；旧 validator fail closed |
+| Agent argv | 由 `worker_profiles.py` 按 profile 生成唯一 argv；子进程 `shell=False` |
+| plan → launch 漂移 | `launch` 强制接收刚审阅的 `--expected-launch-fingerprint`，slot 也纳入 hash |
+| PATH / loader / 凭据串用 | 不按调用者 PATH 找可执行文件；固定可信目录；控制进程无供应商凭据，worker 使用 `per-cli-allowlist-v1` |
+| worktree 冒充 | 绝对规范路径、无 symlink、同 Git common-dir，并命中 `git worktree list -z` |
+| Orca command 注入 | `--command` 只含固定 bootstrap 和随机 launch ID |
+| bootstrap 抢跑 | 先绑定 runtime/handle/incarnation/worktree，再用 terminal stdin nonce/proof 授权 |
+| cleanup / bootstrap 竞态 | Popen 前在同一 record lock 内复核 awaiting 状态；cleanup 先发生则拒绝启动 Agent |
+| create 部分失败 | 取得确定 handle 前的超时、transport/解码异常、中断、非零、畸形/缺字段响应均记为 indeterminate，禁止自动重试 |
+| handle 后失败清理 | record 写失败不阻断 close；只有 `terminal close --tab --json` 完整匹配且最终 failed 状态可靠落盘才记普通失败，否则保持 indeterminate/reconcile-required |
+| receipt 漂移 | 规范化 profileHash、argvHash、slot、launchFingerprint 与 receiptHash 交叉校验 |
+| dispatch 旧 receipt 改挂 | 每个角色显式记录 attemptId；receipt 必须绑定当前 ACK task.id、同 role/profile/attempt，receiptId/attemptId 同空同填 |
+| 配置兼容 | ackVersion 必须是合法 SemVer；v0.10+ 的 orchestration/workerReceipts 必须同时存在，v0.9 旧板仍可只读校验和手动协作 |
+
+### 不能被弱证明掩盖的边界
+
+`receiptHash` 是无密钥 checksum，不是签名。项目内可写方能修改 receipt 后重算
+hash；而当前 Orca terminal metadata 不提供原始 Agent argv、模型或权限
+attestation。因此 v0.10 **不根据持久化 receipt 自动复用旧终端**。每次自动派发都
+重新执行 plan，并用 expected fingerprint 启动 fresh worker；持久化 receipt 只作
+审计和 dispatch 关联。
+
+`launchFingerprint` 只证明完整计划没有漂移，不是一次性授权或幂等键；同一计划重复
+执行仍会创建新的 fresh terminal。成功后不得重放，结果不确定时必须先 reconcile。
+自动防重放要依赖后端原子 idempotency/claim 或项目外可信 launch intent，不能由
+checksum 伪装提供。
+
+任务板里的 dispatch 关联也不是宽松的历史索引。`dispatch.<role>` 显式记录
+`profileId`、`receiptId` 和 `attemptId`，校验器要求 receipt 的 `createdFor` 精确绑定
+当前 ACK `tasks[].id`、同一角色和同一 attempt，并要求 profile 一致。该约束阻止把
+旧任务、旧角色或旧轮次 receipt 改挂到当前 dispatch，但不会把无密钥 receipt 升级成
+可信 attestation。
+
+同样，receipt 证明的是 launcher 请求和本地 CLI/runtime 绑定，不证明模型供应商最终
+执行的模型。开放自动复用需要 Orca/ACP 提供启动参数 attestation，或项目外可信签发
+与校验通道。开放 full-access 还需要不可由项目文本伪造的用户授权、期限、撤销和外层
+隔离。这两项均留待后续版本。
+
+威胁模型也明确到 Coordinator 账户边界：v0.10 防止任务板、任务内容、普通环境和
+受限 worker 把数据变成第二个启动命令入口；不抵御已经完全控制 Coordinator OS
+账户、Orca runtime、受信 Agent/Orca 可执行文件或用户级 Agent 配置/插件/MCP 的
+攻击者。`permissionMode` 也不是模型供应商或外部工具能力 attestation；后者必须依赖
+独立 OS 身份、受控 Agent 配置或平台能力。
+
+## 后续版本提案：ACP 与可替换编排后端
+
+### 当前决策
+
+ACK 当前版本继续以 **Orca** 作为唯一自动编排后端。闭环语义保持工具无关，但
+worker 创建、终端身份绑定、dispatch 和 wait 的可执行适配仍由 Orca 完成。
+
+ACP（Agent Client Protocol）作为后续版本的优先候选，当前只记录方案，不加入运行
+时依赖、不新增半成品 adapter，也不让现有流程在 Orca 与 ACP 之间自动猜测。
+
+| 能力 | 当前版本 | 后续方向 |
+|------|----------|----------|
+| 自动创建并监督 worker | Orca | ACP capability negotiation 后可增加 ACP adapter |
+| 结构化模型与权限 profile | ACK 自己定义，Orca 只承载启动 | 保持为 ACK 稳定契约，不交给后端自由解释 |
+| dispatch / wait / terminal identity | Orca runtime handle | 映射到 ACP session / request / event identity |
+| 无自动后端时运行闭环 | 手动模式 | 可增加 PTY / Zellij 类低层 fallback，但不冒充语义协议 |
+| 后端选择 | 项目显式配置 | 未来仍需显式配置，不按已安装命令静默切换 |
+
+### 后端无关的最小语义
+
+未来 adapter 只应实现以下能力，不应接管 ACK 的角色、状态机或安全策略：
+
+1. `createWorker(profile, worktree)`：按 ACK 已验证的结构化 profile 创建 worker。
+2. `inspectWorker(identity)`：返回可绑定的 runtime、session/incarnation 和活性。
+3. `dispatch(identity, taskContext)`：把一个明确任务投递给已验证 worker。
+4. `wait(identity, eventTypes)`：等待完成、复测、升级或 decision gate 事件。
+5. `closeWorker(identity)`：只关闭本次创建且身份仍匹配的 worker。
+
+模型、reasoning effort、权限模式、worktree 和 receipt hash 仍由 ACK 校验。adapter
+不能重新开放自由 shell、任意 argv、任意环境变量或“后端默认模型”作为旁路。
+
+### ACP 采用门槛
+
+满足以下条件后再实现 ACP adapter：
+
+- 目标 Agent CLI 对 ACP 的启动、会话身份、取消和事件语义足够稳定。
+- 能把 Developer/Test 的独立身份、worktree 和结构化 profile 映射到可核对字段。
+- 能区分“已请求的模型/权限”和“运行时可观测事实”，不把客户端请求冒充供应商证明。
+- 超时、重连、重复 dispatch 和 runtime 重启具有明确的幂等或恢复语义。
+- 与 Orca adapter 使用同一组 ACK conformance tests，且不会降低安全默认。
+
+在这些门槛满足前，ACP 保持 **Deferred**。PTY 或 Zellij 一类方案只能作为较低层的
+进程/终端承载，不提供 session 语义、模型证明或任务状态机；如果以后加入，也必须
+经过独立 adapter，不能散落为文档中的自由命令。
+
+### 参考依据
+
+- [GitHub 仓库自定义指令](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions)
+  区分仓库级、路径级和就近生效的 Agent 指令。
+- [Claude Code 项目记忆](https://code.claude.com/docs/zh-CN/memory)区分持久指令与
+  自动记忆，并建议把较大的内容按作用域拆分、按需加载。
+- [Architectural Decision Records](https://adr.github.io/)用于保存单个重要决策的
+  理由、取舍和后果，适合承载不应混入项目知识库的决策正文。
@@ -9,6 +9,8 @@ mkdir -p "$BIN_DIR"
 ln -sf "$REPO/bin/skiff" "$BIN_DIR/skiff"
 echo "已安装 skiff -> $BIN_DIR/skiff"

+PYTHONPATH="$REPO${PYTHONPATH:+:$PYTHONPATH}" python3 -m skiff bootstrap
+
 path_already_configured() {
  local file="$1"
  [[ -f "$file" ]] && grep -qF "$PATH_MARKER" "$file"
@@ -1,17 +0,0 @@
-# External skills registry
-# Format:
-#   <name>:
-#     repo: <git-url>
-#     ref: <branch|tag>     (default: main)
-#     path: <subpath>       (default: .)
-#
-# Example:
-#   superpowers:
-#     repo: https://github.com/obra/superpowers
-#     ref: main
-#     path: .
-
-superpowers:
-    repo: https://github.com/obra/superpowers
-    ref: main
-    path: .
@@ -9,41 +9,76 @@ cd /path/to/skills   # 本仓库根目录
 ./install.sh         # 软链到 ~/.local/bin/skiff
 ```

-确保 `~/.local/bin` 在 `PATH` 中。开发时也可直接运行：
+确保 `~/.local/bin` 在 `PATH` 中。
+
+## 命令风格
+
+接口对齐 [Vercel skills CLI](https://github.com/vercel-labs/skills) 的 `add` / `remove`，
+统一管理 builtin skill、预置 catalog source 和用户命名的 custom source。
+
+```bash
+# 浏览可用自研 skill
+skiff add --list
+
+# 装到当前项目 / 全局
+skiff add discussion-notes -a cursor -y
+skiff add discussion-notes -a cursor -g -y
+
+# 卸载
+skiff remove discussion-notes -a cursor -y
+skiff rm discussion-notes -g -y
+
+# 改完 skill 后提交推送（在任意目录执行，操作 ~/.skills）
+skiff publish skills/discussion-notes -m "update discussion-notes" --push
+```
+
+开发时也可直接运行：

 ```bash
 PYTHONPATH=/path/to/skills python3 -m skiff <command>
 ```

-## 首次配置
+## 首次安装

 ```bash
-skiff setup ~/code/gitea/skills   # 将 ~/.skills 软链到仓库
+git clone https://git.yumee.top/laily/skills.git ~/.skills
+~/.skills/install.sh
 ```

-若仓库本身就在 `~/.skills`（开发场景），`setup` 会自动识别，无需额外操作。
+`install.sh` 会安装 CLI，并自动执行 `skiff bootstrap`，将本仓库的 `skiff` skill 全局软链到 Cursor、Claude Code 和 Codex。也可以随时手动重跑：
+
+```bash
+skiff bootstrap
+```

 ## 命令参考

-### 仓库关联
-
-| 命令 | 说明 |
-|------|------|
-| `skiff setup <path>` | 关联 `~/.skills` 到 skills 仓库 |
-
 ### 查看

 | 命令 | 说明 |
 |------|------|
-| `skiff list` | 列出自研 skill 与 registry 中的外部 skill |
+| `skiff list [--source NAME]` | 列出所有来源或指定 source 中的 skill |
 | `skiff status [--target all\|cursor\|claude\|codex]` | 安装状态总览 |

-### 全局安装（自研 skill）
+### 项目初始化

 | 命令 | 说明 |
 |------|------|
-| `skiff install <name> [--target all]` | 软链到 Agent 全局目录 |
-| `skiff uninstall <name> [--target all]` | 移除软链 |
+| `skiff bootstrap` | 将本项目的 `skiff` skill 全局安装到所有 Agent |
+| `skiff update` | 在 `~/.skills` 执行 `git pull`，更新 skiff 自身 |
+| `skiff init <name> [--project DIR]` | 使用 builtin skill 自带模板初始化项目状态 |
+
+### Skill 安装
+
+| 命令 | 说明 |
+|------|------|
+| `skiff add <name> [--global] [-a AGENT...] [-y]` | 安装到 Agent 目录（软链） |
+| `skiff select [--global] [-a AGENT...]` | 打开终端多选界面，批量安装 skill |
+| `skiff remove <name> [--global] [-a AGENT...] [-y]` | 移除软链（`rm` / `r` 别名） |
+| `skiff add --list` | 列出可用 builtin skill |
+| `skiff publish [paths] -m MSG [--push]` | 在 ~/.skills 内 git add/commit/push |
+
+旧命令 `install` / `uninstall` 已移除，请改用 `add` / `remove`。

 全局目标路径：

@@ -53,13 +88,73 @@ skiff setup ~/code/gitea/skills   # 将 ~/.skills 软链到仓库
 | claude | `~/.claude/skills/` |
 | codex | `~/.codex/skills/` |

-### 外部 Git skill
+### 预置 Catalog Source

 | 命令 | 说明 |
 |------|------|
-| `skiff add <name> <repo-url> [--ref main] [--path .]` | 写入 `registry.yaml` |
-| `skiff fetch <name>` | 克隆/更新到 `~/.local/share/skills/externals/<name>/` |
-| `skiff install-external <name> [--target all]` | 安装外部 skill 到 Agent 目录 |
+| `skiff catalog add <name> <repo-url> [--ref main] [--path .]` | 写入 `catalog.yaml` |
+| `skiff fetch <name>` | 克隆或更新 catalog source checkout |
+| `skiff add <name> [-g] [-a AGENT...]` | 安装 catalog 中的单个 skill 或完整 collection（缺失时自动 fetch） |
+| `skiff add <collection>/<skill> [...]` | 只安装 collection 中指定的 skill |
+
+`catalog.yaml` 条目可额外提供 `description` 和 `tags`。`description`
+会显示在 `skiff select` 的候选列表中。`path` 可以直接指向含
+`SKILL.md` 的单个 skill，也可以指向由多个 skill 目录组成的 collection。
+collection 会自动发现下一层所有含 `SKILL.md` 的目录；`skiff add <name>`
+安装全部，`skiff select` 则展开为 `<name>/<skill>` 供分别勾选。同一
+`repo` 与 `ref` 共享一份 Git checkout。
+
+### 交互式批量安装
+
+```bash
+skiff select                         # 当前项目，全部 Agent
+skiff select -a codex                # 当前项目，仅 Codex
+skiff select -g                      # 全局安装
+skiff select --project ~/code/app    # 指定项目
+```
+
+使用方向键移动、空格勾选、`/` 搜索、Enter 安装，按 `q` 或 Esc
+取消。普通 `skiff select` 只安装到项目，并在每一项旁只读显示各 Agent 的
+全局安装状态；`skiff select -g` 只安装到全局。已经安装到目标范围的 skill
+默认勾选；取消勾选不会卸载已有 skill，卸载请使用 `skiff remove`。如果全局
+存在同名但指向其它来源的 skill，项目选择器会显示“全局同名冲突”。
+项目模式会把成功选择的项目写入 `.skills.yaml`。非交互环境请使用
+`skiff add <name>...`。使用 `-a` 限定 Agent 时，该范围会记录在对应的
+skill 条目中，后续 `skiff sync` 不会扩散到其他 Agent。
+
+### Custom source（多-skill 仓库）
+
+公司或团队维护的仓库通常包含多个 skill。使用命名 source 接入：
+
+```bash
+# Git 仓库，默认 clone 到 ~/.local/share/skiff/sources/company
+skiff source add company \
+  git@git.company.com:platform/agent-skills.git \
+  --ref main \
+  --skills-path internal/skills
+
+# 或接入已有本地仓库
+skiff source add company \
+  --local ~/code/company-agent-skills \
+  --skills-path skills
+
+skiff source list
+skiff source fetch company
+skiff list --source company
+skiff add company/code-review -g -a codex
+```
+
+| 命令 | 说明 |
+|------|------|
+| `skiff source add <name> <repo> [--ref REF] [--checkout PATH] [--skills-path PATH]` | 注册并克隆 Git source |
+| `skiff source add <name> --local PATH [--skills-path PATH]` | 接入已有本地仓库 |
+| `skiff source list` / `show <name>` | 查看 source |
+| `skiff source fetch <name>` / `fetch --all` | clone 或 fast-forward 更新 |
+| `skiff source remove <name>` | 移除配置并保留 checkout |
+
+配置保存在 `~/.config/skiff/config.yaml`。Git/SSH 认证复用本机 Git 配置，
+skiff 不保存 token。可以使用 `company/code-review`，也可以使用
+`skiff add code-review --source company`。多个来源包含同名 skill 时，必须明确来源。

 ### 项目级

@@ -81,7 +176,9 @@ skiff setup ~/code/gitea/skills   # 将 ~/.skills 软链到仓库

 | 命令 | 说明 |
 |------|------|
-| `skiff create <name>` | 从 `skills/_template/` 创建自研 skill |
+| `skiff create <name> [--idea TEXT] [--from-project PATH]` | 从模板创建含 `SKILL.md`、`README.md` 的草稿 |
+| `skiff check <name>` | 校验草稿或正式 skill，包括人类使用说明 |
+| `skiff finalize <name>` | 校验草稿并移动到正式 `skills/` |
 | `skiff doctor [--target all] [--fix]` | 检查软链健康状态，`--fix` 自动修复 |

 ## 常用工作流
@@ -89,26 +186,28 @@ skiff setup ~/code/gitea/skills   # 将 ~/.skills 软链到仓库
 ### 新建并全局启用自研 skill

 ```bash
-skiff create my-skill
-# 编辑 skills/my-skill/SKILL.md
-skiff install my-skill --target cursor
-skiff doctor --target cursor
+skiff create my-skill --idea "描述要解决的重复问题" --from-project .
+# 由 Agent 完善草稿中的 SKILL.md 和 README.md
+skiff check my-skill
+skiff finalize my-skill
+skiff publish skills/my-skill -m "add my-skill" --push
+skiff add my-skill -a cursor -g -y
+skiff doctor -a cursor
 ```

 ### 在项目中启用 skill

 ```bash
 cd ~/code/my-app
-skiff enable declarative-openspec-loop --target cursor
-skiff sync
+skiff add declarative-openspec-loop -a cursor -y
 ```

-### 安装外部 Git skill
+### 添加 Catalog Source

 ```bash
-skiff add my-ext https://github.com/org/repo --ref main
+skiff catalog add my-ext https://github.com/org/repo --ref main
 skiff fetch my-ext
-skiff install-external my-ext
+skiff add my-ext -g
 ```

 ## 源码结构
@@ -119,8 +218,9 @@ skiff/
 ├── __main__.py      # python3 -m skiff 入口
 ├── cli.py           # 命令定义与调度
 ├── paths.py         # 路径常量与 Agent 目标
-├── skills.py        # 自研 skill 发现
-├── registry.py      # registry.yaml 读写
+├── skills.py        # builtin/catalog/custom 统一解析
+├── catalog.py       # catalog.yaml 读写与 Skill 发现
+├── sources.py       # custom source 配置、发现与 Git 管理
 ├── project.py       # .skills.yaml 管理
 ├── symlinks.py      # 软链创建/检查/修复
 └── yaml_io.py       # 轻量 YAML 解析（无第三方依赖）
@@ -133,9 +233,11 @@ skiff/
 | 变量 | 路径 | 说明 |
 |------|------|------|
 | `SKILLS_HOME` | `~/.skills` | skills 仓库（软链） |
-| `SKILLS_DIR` | `~/.skills/skills/` | 自研 skill 目录 |
-| `REGISTRY_FILE` | `~/.skills/registry.yaml` | 外部 skill 注册表 |
-| `EXTERNALS_DIR` | `~/.local/share/skills/externals/` | 已 fetch 的外部仓库 |
+| `SKILLS_DIR` | `~/.skills/skills/` | builtin skill 目录 |
+| `CATALOG_FILE` | `~/.skills/catalog.yaml` | 预置 Skill 来源目录 |
+| `CATALOG_CACHE_DIR` | `~/.local/share/skills/externals/` | catalog checkout 兼容缓存；按 repo/ref 共享 |
+| `CONFIG_FILE` | `~/.config/skiff/config.yaml` | custom source 配置 |
+| `SOURCES_DIR` | `~/.local/share/skiff/sources/` | custom Git source 默认 checkout |

 ## 注意事项

@@ -1,3 +1,3 @@
 """skiff — Agent Skills 安装与管理 CLI。"""

-__version__ = "0.1.0"
+__version__ = "0.6.0"
@@ -0,0 +1,40 @@
+"""Agent 名称解析（兼容 Vercel skills CLI 别名）。"""
+
+from __future__ import annotations
+
+from skiff.paths import ALL_TARGETS
+
+AGENT_ALIASES: dict[str, str] = {
+    "cursor": "cursor",
+    "claude": "claude",
+    "claude-code": "claude",
+    "codex": "codex",
+    "*": "*",
+}
+
+AGENT_CHOICES = sorted({*ALL_TARGETS, *AGENT_ALIASES.keys()})
+
+
+def flatten_agent_args(groups: list[list[str]] | None) -> list[str] | None:
+    if not groups:
+        return None
+    flat = [item for group in groups for item in group]
+    return flat or None
+
+
+def resolve_agent_args(agents: list[str] | None) -> list[str]:
+    if not agents or agents == ["*"] or "*" in agents:
+        return list(ALL_TARGETS)
+
+    resolved: list[str] = []
+    for raw in agents:
+        key = raw.lower()
+        if key == "*":
+            return list(ALL_TARGETS)
+        target = AGENT_ALIASES.get(key)
+        if target is None:
+            choices = ", ".join(AGENT_CHOICES)
+            raise SystemExit(f"未知 agent: {raw!r}，可选: {choices}")
+        if target != "*" and target not in resolved:
+            resolved.append(target)
+    return resolved
@@ -0,0 +1,105 @@
+"""预置 Skill catalog 的配置、发现与本地 checkout 路径。"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from skiff import yaml_io
+from skiff.paths import CATALOG_FILE, LEGACY_REGISTRY_FILE
+
+
+def load_catalog(path: Path | None = None) -> dict[str, dict[str, Any]]:
+    path = path or (
+        CATALOG_FILE if CATALOG_FILE.is_file() else LEGACY_REGISTRY_FILE
+    )
+    if not path.is_file():
+        return {}
+    data = yaml_io.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise SystemExit(f"catalog 格式错误: {path}")
+    return {k: v for k, v in data.items() if isinstance(v, dict) and not k.startswith("#")}
+
+
+def save_catalog(data: dict[str, dict[str, Any]], path: Path | None = None) -> None:
+    path = path or CATALOG_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml_io.safe_dump(data, allow_unicode=True, sort_keys=False), encoding="utf-8")
+
+
+def catalog_repo(entry: dict[str, Any]) -> str:
+    """Expand a local home-relative repo while leaving remote URLs unchanged."""
+    repo = str(entry.get("repo", ""))
+    return str(Path(repo).expanduser()) if repo.startswith("~") else repo
+
+
+def catalog_repo_path(entry: dict[str, Any]) -> Path:
+    """Return the shared checkout path for a repo/ref pair."""
+    from skiff.paths import CATALOG_CACHE_DIR
+
+    repo = str(entry.get("repo", ""))
+    ref = str(entry.get("ref", "main"))
+    digest = hashlib.sha256(f"{repo}\0{ref}".encode()).hexdigest()[:16]
+    return CATALOG_CACHE_DIR / "_repos" / digest
+
+
+def catalog_checkout_path(name: str, entry: dict[str, Any]) -> Path:
+    """Use a local repo directly, otherwise return its external checkout."""
+    from skiff.paths import CATALOG_CACHE_DIR
+
+    configured_repo = str(entry.get("repo", ""))
+    local_repo = Path(catalog_repo(entry))
+    if configured_repo.startswith("~") and local_repo.is_dir():
+        return local_repo.resolve()
+
+    legacy = CATALOG_CACHE_DIR / name
+    return legacy if legacy.is_dir() else catalog_repo_path(entry)
+
+
+def catalog_skill_path(name: str, entry: dict[str, Any] | None = None) -> Path:
+    entry = entry or load_catalog().get(name, {})
+    subpath = entry.get("path", ".") or "."
+    checkout = catalog_checkout_path(name, entry).resolve()
+    skill_path = (checkout / subpath).resolve()
+    try:
+        skill_path.relative_to(checkout)
+    except ValueError as exc:
+        raise SystemExit(
+            f"catalog 条目 {name!r} 的 path 超出来源仓库: {subpath!r}"
+        ) from exc
+    return skill_path
+
+
+def discover_catalog_skills(
+    name: str,
+    entry: dict[str, Any] | None = None,
+) -> dict[str, Path]:
+    """Discover a catalog provider containing one or more skills."""
+    entry = entry or load_catalog().get(name, {})
+    root = catalog_skill_path(name, entry)
+    if (root / "SKILL.md").is_file():
+        return {name: root}
+    if not root.is_dir():
+        return {}
+    resolved_root = root.resolve()
+    skills: dict[str, Path] = {}
+    for item in sorted(root.iterdir()):
+        skill_md = item / "SKILL.md"
+        if (
+            item.name.startswith("_")
+            or item.is_symlink()
+            or not item.is_dir()
+            or skill_md.is_symlink()
+            or not skill_md.is_file()
+        ):
+            continue
+        resolved_item = item.resolve()
+        resolved_skill_md = skill_md.resolve()
+        try:
+            resolved_item.relative_to(resolved_root)
+            resolved_skill_md.relative_to(resolved_item)
+        except ValueError:
+            continue
+        skills[item.name] = item
+    return skills
@@ -0,0 +1,59 @@
+"""~/.skills 仓库内的 git 操作。"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from skiff.paths import SKILLS_HOME
+
+
+def _run_git(repo: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", str(repo), *args],
+        check=check,
+        text=True,
+        capture_output=not sys.stdout.isatty(),
+    )
+
+
+def ensure_git_repo(repo: Path) -> None:
+    if not (repo / ".git").exists():
+        raise SystemExit(f"不是 git 仓库: {repo}")
+
+
+def has_staged_changes(repo: Path) -> bool:
+    result = _run_git(repo, "diff", "--cached", "--quiet", check=False)
+    return result.returncode == 1
+
+
+def publish(
+    *,
+    paths: list[str],
+    message: str | None,
+    push: bool,
+    no_commit: bool,
+) -> None:
+    repo = SKILLS_HOME.resolve()
+    ensure_git_repo(repo)
+
+    _run_git(repo, "add", "--", *paths)
+
+    if not has_staged_changes(repo):
+        print("没有可提交的变更", file=sys.stdout)
+        return
+
+    if no_commit:
+        print(f"已暂存变更: {', '.join(paths)}", file=sys.stdout)
+        return
+
+    if not message:
+        raise SystemExit("提交需要 -m/--message")
+
+    _run_git(repo, "commit", "-m", message)
+    print(f"已提交: {message}", file=sys.stdout)
+
+    if push:
+        _run_git(repo, "push")
+        print("已推送到远程", file=sys.stdout)
@@ -8,8 +8,12 @@ HOME = Path.home()
 SKILLS_HOME = HOME / ".skills"
 SKILLS_DIR = SKILLS_HOME / "skills"
 TEMPLATE_DIR = SKILLS_DIR / "_template"
-REGISTRY_FILE = SKILLS_HOME / "registry.yaml"
-EXTERNALS_DIR = HOME / ".local" / "share" / "skills" / "externals"
+DRAFTS_DIR = SKILLS_HOME / ".drafts"
+CATALOG_FILE = SKILLS_HOME / "catalog.yaml"
+LEGACY_REGISTRY_FILE = SKILLS_HOME / "registry.yaml"
+CATALOG_CACHE_DIR = HOME / ".local" / "share" / "skills" / "externals"
+CONFIG_FILE = HOME / ".config" / "skiff" / "config.yaml"
+SOURCES_DIR = HOME / ".local" / "share" / "skiff" / "sources"
 PROJECT_MANIFEST = ".skills.yaml"

 AGENT_GLOBAL: dict[str, Path] = {
@@ -44,5 +48,5 @@ def agent_skill_dir(target: str, *, project_root: Path | None = None) -> Path:
 def ensure_skills_home() -> None:
    if not SKILLS_HOME.is_dir():
        raise SystemExit(
-            f"~/.skills 未配置。请先运行: skiff setup <skills-repo-path>"
+            "~/.skills 不存在。请将 skills 仓库克隆到 ~/.skills"
        )
@@ -7,7 +7,7 @@ from typing import Any

 from skiff import yaml_io
 from skiff.paths import PROJECT_MANIFEST
-from skiff.skills import resolve_skill_source
+from skiff.skills import normalize_source, resolve_skill_source


 def load_manifest(path: Path | None = None) -> tuple[Path, dict[str, Any]]:
@@ -31,11 +31,13 @@ def save_manifest(path: Path, data: dict[str, Any]) -> None:

 def normalize_skill_entry(entry: str | dict[str, Any]) -> dict[str, Any]:
    if isinstance(entry, str):
-        return {"name": entry, "source": "owned"}
+        return {"name": entry, "source": "builtin"}
    name = entry.get("name")
    if not name:
        raise SystemExit(f".skills.yaml 条目缺少 name: {entry}")
-    source = entry.get("source", "owned")
+    source = normalize_source(str(entry.get("source", "builtin")))
+    if source == "catalog" and entry.get("registry"):
+        source = f"catalog:{entry['registry']}"
    return {"name": name, "source": source, **{k: v for k, v in entry.items() if k not in ("name", "source")}}


@@ -44,8 +46,6 @@ def manifest_skill_names(data: dict[str, Any]) -> list[str]:


 def _entry_to_yaml(entry: dict[str, Any]) -> str | dict[str, Any]:
-    if entry.get("source", "owned") == "owned" and set(entry.keys()) <= {"name", "source"}:
-        return entry["name"]
    return entry


@@ -53,7 +53,7 @@ def add_skill_to_manifest(
    manifest_path: Path,
    name: str,
    *,
-    source: str = "owned",
+    source: str = "builtin",
    extra: dict[str, Any] | None = None,
 ) -> None:
    path = manifest_path
@@ -65,13 +65,16 @@ def add_skill_to_manifest(
        file_path = path

    entries = [normalize_skill_entry(e) for e in data.get("skills", [])]
-    if any(e["name"] == name for e in entries):
-        return
-
    item: dict[str, Any] = {"name": name, "source": source}
    if extra:
        item.update(extra)
+    existing_index = next((i for i, entry in enumerate(entries) if entry["name"] == name), None)
+    if existing_index is None:
        entries.append(item)
+    elif entries[existing_index] == item:
+        return
+    else:
+        entries[existing_index] = item

    data["skills"] = [_entry_to_yaml(e) for e in entries]
    save_manifest(file_path, data)
@@ -97,5 +100,7 @@ def iter_manifest_skills(data: dict[str, Any]) -> list[dict[str, Any]]:

 def resolve_manifest_skill(entry: dict[str, Any]) -> tuple[Path, str]:
    name = entry["name"]
-    source = entry.get("source", "owned")
+    source = normalize_source(entry.get("source", "builtin"))
+    if source == "catalog" and entry.get("registry"):
+        source = f"catalog:{entry['registry']}"
    return resolve_skill_source(name, source=source)
@@ -1,33 +0,0 @@
-"""registry.yaml 读写。"""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any
-
-from skiff import yaml_io
-from skiff.paths import REGISTRY_FILE
-
-
-def load_registry(path: Path | None = None) -> dict[str, dict[str, Any]]:
-    path = path or REGISTRY_FILE
-    if not path.is_file():
-        return {}
-    data = yaml_io.safe_load(path.read_text(encoding="utf-8")) or {}
-    if not isinstance(data, dict):
-        raise SystemExit(f"registry 格式错误: {path}")
-    return {k: v for k, v in data.items() if isinstance(v, dict) and not k.startswith("#")}
-
-
-def save_registry(data: dict[str, dict[str, Any]], path: Path | None = None) -> None:
-    path = path or REGISTRY_FILE
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(yaml_io.safe_dump(data, allow_unicode=True, sort_keys=False), encoding="utf-8")
-
-
-def external_skill_path(name: str, entry: dict[str, Any] | None = None) -> Path:
-    from skiff.paths import EXTERNALS_DIR
-
-    entry = entry or load_registry().get(name, {})
-    subpath = entry.get("path", ".") or "."
-    return (EXTERNALS_DIR / name / subpath).resolve()
@@ -0,0 +1,228 @@
+"""Terminal multi-select UI for skills."""
+
+from __future__ import annotations
+
+import unicodedata
+from dataclasses import dataclass
+from typing import Callable, Iterable
+
+
+@dataclass(frozen=True)
+class SkillChoice:
+    name: str
+    kind: str
+    description: str = ""
+    installed: bool = False
+    readonly_status: str = ""
+    children: tuple[str, ...] = ()
+    indent: int = 0
+
+
+def fit_to_width(text: str, width: int) -> str:
+    """Trim text to terminal display width without splitting wide characters."""
+    if width <= 0:
+        return ""
+    result: list[str] = []
+    used = 0
+    for char in text:
+        if unicodedata.combining(char):
+            char_width = 0
+        else:
+            char_width = 2 if unicodedata.east_asian_width(char) in {"W", "F"} else 1
+        if used + char_width > width:
+            break
+        result.append(char)
+        used += char_width
+    return "".join(result)
+
+
+def display_width(text: str) -> int:
+    return sum(
+        0
+        if unicodedata.combining(char)
+        else 2
+        if unicodedata.east_asian_width(char) in {"W", "F"}
+        else 1
+        for char in text
+    )
+
+
+def filter_choices(choices: Iterable[SkillChoice], query: str) -> list[SkillChoice]:
+    needle = query.casefold().strip()
+    if not needle:
+        return list(choices)
+    return [
+        choice
+        for choice in choices
+        if needle in choice.name.casefold()
+        or needle in choice.kind.casefold()
+        or needle in choice.description.casefold()
+        or needle in choice.readonly_status.casefold()
+    ]
+
+
+def select_skills(
+    choices: list[SkillChoice],
+    *,
+    scope_label: str = "当前作用域",
+    wrapper: Callable[..., set[str] | None] | None = None,
+) -> set[str] | None:
+    """Open the selector. Return names, or None when cancelled."""
+    if not choices:
+        return set()
+
+    try:
+        import curses
+    except ImportError as exc:
+        raise RuntimeError("当前 Python 环境不支持 curses，无法打开交互界面") from exc
+
+    selected = {
+        choice.name
+        for choice in choices
+        if choice.installed and not choice.children
+    }
+
+    def mark_for(choice: SkillChoice) -> str:
+        if not choice.children:
+            return "x" if choice.name in selected else " "
+        selected_children = selected.intersection(choice.children)
+        if len(selected_children) == len(choice.children):
+            return "x"
+        return "-" if selected_children else " "
+
+    def draw(stdscr: object) -> set[str] | None:
+        curses.curs_set(0)
+        stdscr.keypad(True)
+        current = 0
+        query = ""
+        source_attr = curses.A_NORMAL
+        status_attr = curses.A_NORMAL
+        description_attr = curses.A_DIM
+        try:
+            if curses.has_colors():
+                curses.start_color()
+                curses.use_default_colors()
+                curses.init_pair(1, curses.COLOR_CYAN, -1)
+                curses.init_pair(2, curses.COLOR_GREEN, -1)
+                source_attr = curses.color_pair(1)
+                status_attr = curses.color_pair(2)
+        except curses.error:
+            pass
+
+        while True:
+            visible = filter_choices(choices, query)
+            current = min(current, max(0, len(visible) - 1))
+            stdscr.erase()
+            height, width = stdscr.getmaxyx()
+            text_width = max(0, width - 1)
+            stdscr.addnstr(
+                0,
+                0,
+                fit_to_width(f"安装目标: {scope_label}", text_width),
+                text_width,
+            )
+            header = "↑↓ 移动  Space 选择  / 搜索  Enter 安装  q 退出"
+            stdscr.addnstr(1, 0, fit_to_width(header, text_width), text_width)
+            if query:
+                stdscr.addnstr(
+                    2,
+                    0,
+                    fit_to_width(f"搜索: {query}", text_width),
+                    text_width,
+                )
+
+            item_capacity = max(1, (height - 4) // 3)
+            start = max(0, current - item_capacity + 1)
+            for offset, choice in enumerate(visible[start : start + item_capacity]):
+                index = start + offset
+                row = 3 + offset * 3
+                mark = mark_for(choice)
+                description = f"    {choice.description}" if choice.description else ""
+                focus_attr = curses.A_REVERSE if index == current else curses.A_NORMAL
+                parts = [
+                    (f"{'  ' * choice.indent}[{mark}] ", focus_attr),
+                    (choice.name, focus_attr | curses.A_BOLD),
+                    (f"  {choice.kind}", focus_attr | source_attr),
+                ]
+                if choice.readonly_status:
+                    parts.append(
+                        (f"  {choice.readonly_status}", focus_attr | status_attr)
+                    )
+                column = 0
+                for text, attr in parts:
+                    available = text_width - column
+                    if available <= 0:
+                        break
+                    fitted = fit_to_width(text, available)
+                    stdscr.addnstr(row, column, fitted, available, attr)
+                    column += display_width(fitted)
+                stdscr.addnstr(
+                    row + 1,
+                    0,
+                    fit_to_width(description, text_width),
+                    text_width,
+                    focus_attr | description_attr,
+                )
+
+            footer = (
+                f"已选择 {len(selected)} 项  ·  取消选择不卸载，卸载用 skiff remove"
+            )
+            stdscr.addnstr(
+                height - 1,
+                0,
+                fit_to_width(footer, text_width),
+                text_width,
+            )
+            stdscr.refresh()
+            key = stdscr.get_wch()
+
+            if key in ("q", "Q", "\x1b"):
+                return None
+            if key in ("\n", "\r") or key == curses.KEY_ENTER:
+                return set(selected)
+            if key == curses.KEY_UP and visible:
+                current = (current - 1) % len(visible)
+            elif key == curses.KEY_DOWN and visible:
+                current = (current + 1) % len(visible)
+            elif key == " " and visible:
+                choice = visible[current]
+                if choice.children:
+                    children = set(choice.children)
+                    if children.issubset(selected):
+                        selected.difference_update(children)
+                    else:
+                        selected.update(children)
+                else:
+                    selected.symmetric_difference_update({choice.name})
+            elif key == "/":
+                curses.curs_set(1)
+                query = _read_query(stdscr, curses, width, row=2)
+                curses.curs_set(0)
+                current = 0
+
+    runner = wrapper or curses.wrapper
+    return runner(draw)
+
+
+def _read_query(stdscr: object, curses: object, width: int, *, row: int = 1) -> str:
+    query = ""
+    while True:
+        stdscr.move(row, 0)
+        stdscr.clrtoeol()
+        text_width = max(0, width - 1)
+        stdscr.addnstr(
+            row,
+            0,
+            fit_to_width(f"搜索: {query}", text_width),
+            text_width,
+        )
+        stdscr.refresh()
+        key = stdscr.get_wch()
+        if key in ("\n", "\r") or key == curses.KEY_ENTER:
+            return query
+        if key == "\x1b":
+            return ""
+        if key in ("\b", "\x7f") or key == curses.KEY_BACKSPACE:
+            query = query[:-1]
+        elif isinstance(key, str) and key.isprintable():
+            query += key
@@ -2,13 +2,23 @@

 from __future__ import annotations

+import re
 from pathlib import Path

 from skiff.paths import SKILLS_DIR, TEMPLATE_DIR, ensure_skills_home
-from skiff.registry import external_skill_path, load_registry
+from skiff.catalog import (
+    catalog_skill_path,
+    discover_catalog_skills,
+    load_catalog,
+)
+from skiff.sources import (
+    discover_source_skills,
+    list_source_skills,
+    load_sources,
+)


-def list_owned_skills() -> list[str]:
+def list_builtin_skills() -> list[str]:
    ensure_skills_home()
    if not SKILLS_DIR.is_dir():
        return []
@@ -23,36 +33,174 @@ def list_owned_skills() -> list[str]:
    return names


-def owned_skill_path(name: str) -> Path:
+def builtin_skill_path(name: str) -> Path:
    path = SKILLS_DIR / name
    if not (path / "SKILL.md").is_file():
-        raise SystemExit(f"自研 skill 不存在: {name}")
+        raise SystemExit(f"builtin skill 不存在: {name}")
    return path


-def resolve_skill_source(name: str, *, source: str | None = None) -> tuple[Path, str]:
-    """返回 (skill_path, kind)，kind 为 owned 或 external。"""
-    ensure_skills_home()
+def normalize_source(source: str | None) -> str | None:
+    if source == "owned":
+        return "builtin"
+    if source == "registry":
+        return "catalog"
+    if source and source.startswith("registry:"):
+        return f"catalog:{source.split(':', 1)[1]}"
+    return source

-    owned = SKILLS_DIR / name
-    if source in (None, "owned") and (owned / "SKILL.md").is_file():
-        return owned, "owned"

-    registry = load_registry()
-    if source in (None, "registry") and name in registry:
-        path = external_skill_path(name, registry[name])
-        if not path.exists():
+def split_skill_spec(spec: str, source: str | None = None) -> tuple[str, str | None]:
+    if "/" not in spec:
+        return spec, normalize_source(source)
+    qualified_source, name = spec.split("/", 1)
+    if not qualified_source or not name or "/" in name:
+        raise SystemExit(f"skill 限定名称无效: {spec!r}（应为 source/name）")
+    qualified_source = normalize_source(qualified_source)
+    source = normalize_source(source)
+    if source and source != qualified_source:
        raise SystemExit(
-                f"外部 skill {name!r} 尚未 fetch。请先运行: skiff fetch {name}"
+            f"skill 来源冲突: {spec!r} 与 --source {source!r} 不一致"
        )
-        return path, "external"
+    return name, qualified_source

-    if (owned / "SKILL.md").is_file():
-        return owned, "owned"
+
+def list_custom_skills(source: str | None = None) -> dict[str, list[str]]:
+    sources = load_sources()
+    if source:
+        if source not in sources:
+            raise SystemExit(f"未配置 source: {source}")
+        return {source: list_source_skills(source, sources[source])}
+    return {name: list_source_skills(name, entry) for name, entry in sources.items()}
+
+
+def resolve_skill_source(name: str, *, source: str | None = None) -> tuple[Path, str]:
+    """返回 (skill_path, source)，未指定来源时拒绝同名歧义。"""
+    ensure_skills_home()
+    name, source = split_skill_spec(name, source)
+
+    builtin = SKILLS_DIR / name
+    if source == "builtin":
+        if not (builtin / "SKILL.md").is_file():
+            raise SystemExit(f"builtin source 中找不到 skill: {name}")
+        return builtin, "builtin"
+
+    catalog = load_catalog()
+    sources = load_sources()
+    if source and source.startswith("catalog:"):
+        provider = source.split(":", 1)[1]
+        if provider not in catalog:
+            raise SystemExit(f"catalog 中找不到 source: {provider}")
+        skills = discover_catalog_skills(provider, catalog[provider])
+        if name not in skills:
+            available = ", ".join(skills) or "(无)"
+            raise SystemExit(
+                f"catalog source {provider!r} 中找不到 skill {name!r}。可用: {available}"
+            )
+        return skills[name], f"catalog:{provider}"
+
+    if source == "catalog":
+        if name not in catalog:
+            raise SystemExit(f"catalog 中找不到 skill source: {name}")
+        path = catalog_skill_path(name, catalog[name])
+        if not (path / "SKILL.md").is_file():
+            raise SystemExit(
+                f"catalog skill {name!r} 尚未 fetch 或 path 中缺少 SKILL.md。"
+                f"请运行: skiff fetch {name}"
+            )
+        return path, f"catalog:{name}"
+
+    if source:
+        if source not in sources:
+            raise SystemExit(
+                f"项目依赖 source {source!r}，但本机尚未配置。"
+                f"请运行: skiff source add {source} <repo>"
+            )
+        skills = discover_source_skills(source, sources[source])
+        if name not in skills:
+            raise SystemExit(f"source {source!r} 中找不到 skill: {name}")
+        return skills[name], source
+
+    candidates: list[tuple[Path, str]] = []
+    if (builtin / "SKILL.md").is_file():
+        candidates.append((builtin, "builtin"))
+    if name in catalog:
+        path = catalog_skill_path(name, catalog[name])
+        if (path / "SKILL.md").is_file() or not path.exists():
+            candidates.append((path, f"catalog:{name}"))
+    for provider, entry in catalog.items():
+        if provider == name:
+            continue
+        skills = discover_catalog_skills(provider, entry)
+        if name in skills:
+            candidates.append((skills[name], f"catalog:{provider}"))
+    for source_name, entry in sources.items():
+        skills = discover_source_skills(source_name, entry)
+        if name in skills:
+            candidates.append((skills[name], source_name))
+
+    unique_candidates: list[tuple[Path, str]] = []
+    seen_paths: set[Path] = set()
+    for path, candidate_source in candidates:
+        resolved = path.resolve()
+        if resolved in seen_paths:
+            continue
+        seen_paths.add(resolved)
+        unique_candidates.append((path, candidate_source))
+    candidates = unique_candidates
+
+    if len(candidates) > 1:
+        choices = ", ".join(f"{candidate_source}/{name}" for _, candidate_source in candidates)
+        raise SystemExit(f"skill 名称存在多个来源，请明确指定: {choices}")
+    if candidates:
+        path, resolved_source = candidates[0]
+        if resolved_source.startswith("catalog:") and not path.exists():
+            provider = resolved_source.split(":", 1)[1]
+            raise SystemExit(f"catalog source {provider!r} 尚未 fetch。请先运行: skiff fetch {provider}")
+        return path, resolved_source

    raise SystemExit(f"找不到 skill: {name}")


+def read_skill_meta(skill_dir: Path) -> dict[str, str]:
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.is_file():
+        return {}
+    text = skill_md.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    frontmatter = text[3:end]
+    meta: dict[str, str] = {}
+
+    name_match = re.search(r"^name:\s*(.+)$", frontmatter, re.MULTILINE)
+    if name_match:
+        meta["name"] = name_match.group(1).strip().strip("\"'")
+
+    desc_match = re.search(
+        r"^description:\s*(?:>-|>\||>|-)?\s*\n((?:[ \t].+\n?)+)",
+        frontmatter,
+        re.MULTILINE,
+    )
+    if desc_match:
+        lines = [line.strip() for line in desc_match.group(1).splitlines() if line.strip()]
+        meta["description"] = " ".join(lines)
+    else:
+        inline = re.search(r"^description:\s*(.+)$", frontmatter, re.MULTILINE)
+        if inline:
+            meta["description"] = inline.group(1).strip().strip("\"'")
+
+    return meta
+
+
+def skill_description(name: str) -> str | None:
+    meta = read_skill_meta(SKILLS_DIR / name)
+    desc = meta.get("description")
+    return desc.strip() if desc else None
+
+
 def validate_skill_name(name: str) -> None:
    import re

@@ -62,3 +210,84 @@ def validate_skill_name(name: str) -> None:
        )
    if name == "_template":
        raise SystemExit("不能使用保留名 _template")
+
+
+_PLACEHOLDER_PATTERNS = (
+    (r"^name:\s*skill-name\s*$", "skill-name"),
+    (r"^#\s+Skill 名称\s*$", "Skill 名称"),
+    (r"简要描述 skill 做什么、何时触发", "简要描述 skill 做什么"),
+    (r"^-\s*触发场景 1\s*$", "触发场景 1"),
+    (r"^\d+\.\s*第一步\s*$", "第一步"),
+)
+
+
+def validate_skill_dir(skill_dir: Path, expected_name: str) -> list[str]:
+    """返回 skill 目录中的校验问题；空列表表示通过。"""
+    issues: list[str] = []
+    skill_md = skill_dir / "SKILL.md"
+    readme = skill_dir / "README.md"
+    if not skill_md.is_file():
+        return ["缺少 SKILL.md"]
+    if not readme.is_file():
+        issues.append("缺少 README.md（面向人类的使用说明）")
+    else:
+        readme_text = readme.read_text(encoding="utf-8")
+        if not readme_text.strip():
+            issues.append("README.md 为空")
+        if re.search(r"^#\s+skill-name\s*$", readme_text, re.MULTILINE):
+            issues.append("README.md 存在模板占位内容: skill-name")
+        for placeholder in (
+            "用一句话告诉使用者这个 skill 能解决什么问题",
+            "给出用户可以直接说出的典型请求",
+            "给出一条可以直接交给 Agent 的示例请求",
+        ):
+            if placeholder in readme_text:
+                issues.append(f"README.md 存在模板占位内容: {placeholder}")
+
+    text = skill_md.read_text(encoding="utf-8")
+    if not text.strip():
+        return ["SKILL.md 为空"]
+    if not text.startswith("---\n"):
+        return ["SKILL.md 缺少 YAML frontmatter"]
+
+    end = text.find("\n---", 4)
+    if end == -1:
+        return ["SKILL.md frontmatter 未闭合"]
+    frontmatter = text[4:end]
+    keys = re.findall(r"^([A-Za-z0-9_-]+):", frontmatter, re.MULTILINE)
+    unexpected = sorted(set(keys) - {"name", "description"})
+    missing = sorted({"name", "description"} - set(keys))
+    if missing:
+        issues.append(f"frontmatter 缺少字段: {', '.join(missing)}")
+    if unexpected:
+        issues.append(f"frontmatter 只允许 name、description，发现: {', '.join(unexpected)}")
+
+    meta = read_skill_meta(skill_dir)
+    if meta.get("name") != expected_name:
+        issues.append(
+            f"目录名与 frontmatter name 不一致: {expected_name} != {meta.get('name', '(缺失)')}"
+        )
+    description = meta.get("description", "").strip()
+    if not description:
+        issues.append("description 不能为空")
+
+    found_placeholders = [
+        label
+        for pattern, label in _PLACEHOLDER_PATTERNS
+        if re.search(pattern, text, re.MULTILINE | re.IGNORECASE)
+    ]
+    if found_placeholders:
+        issues.append(f"存在模板占位内容: {', '.join(found_placeholders)}")
+
+    link_pattern = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")
+    for target in link_pattern.findall(text):
+        target = target.strip().split("#", 1)[0]
+        if not target or "://" in target or target.startswith(("mailto:", "/")):
+            continue
+        if not (skill_dir / target).resolve().is_file():
+            issues.append(f"引用文件不存在: {target}")
+
+    for draft_file in ("brief.yaml",):
+        if (skill_dir / draft_file).exists():
+            issues.append(f"正式 skill 不应包含草稿文件: {draft_file}")
+    return issues
@@ -0,0 +1,217 @@
+# Skill 来源模型
+
+## 背景
+
+skiff 当前使用 `owned` 表示本仓库 `skills/` 中维护的 Skill，同时还支持
+`registry` 外部仓库和用户配置的 custom source。
+
+这些名称混合了不同维度：
+
+- `owned` 表示所有权。
+- `registry` 表示来源配置存放在哪里。
+- `external` 表示内容不在当前仓库。
+- `collection` 表示一个来源中包含多个 Skill。
+
+它们不能作为同一层级的互斥类型。例如 custom source 既可能来自外部 Git 仓库，
+也可能是 collection；因此 `custom` 与 `external` 并不互斥。
+
+本文建议将用户可见的来源注册方式统一为三类：
+
+- `builtin`：随当前 skiff 仓库提供的 Skill。
+- `catalog:<name>`：由 skiff 自带目录预先登记的来源。
+- `custom:<name>`：用户在本机显式配置的命名来源。
+
+来源注册方式与获取方式、仓库布局相互独立。builtin、catalog 和 custom 中的任意
+来源都可以包含一个或多个 Skill；除 builtin 外，catalog 和 custom 都可以使用
+Git 仓库或本地目录。
+
+## 迁移前模型
+
+```mermaid
+flowchart TD
+    S[skiff 可发现的 Skills]
+
+    S --> O["owned<br/>~/.skills/skills/*"]
+    S --> C["custom source<br/>~/.config/skiff/config.yaml"]
+    S --> R["registry<br/>registry.yaml"]
+
+    O --> O1["本仓库维护<br/>随 skiff 一起分发"]
+
+    C --> C1["本地目录<br/>--local PATH"]
+    C --> C2["指定 Git 仓库<br/>repo + skills_path"]
+
+    R --> R1["外部单 Skill 仓库"]
+    R --> R2["外部 Skill Collection"]
+    R1 --> E["~/.local/share/skills/externals/"]
+    R2 --> E
+```
+
+迁移前实现中：
+
+- `list` 和 `status` 支持 owned、registry 和 custom source。
+- `resolve_skill_source` 可以解析三种来源并处理同名歧义。
+- `select` 只组装 owned 和 registry 条目，尚未展示 custom source。
+- `.skills.yaml` 默认将未声明来源的 Skill 解释为 `owned`。
+- custom source 的 `skills_path` 已经可以包含多个 Skill，本质上也是 collection。
+
+## 现行模型
+
+```mermaid
+flowchart TD
+    A[Skill Provider]
+
+    A --> B["builtin<br/>仓库内隐式注册"]
+    A --> C["catalog:waza<br/>skiff 预置目录"]
+    A --> D["custom:company<br/>用户本机配置"]
+
+    B --> B1["skills/ack"]
+    B --> B2["skills/skiff"]
+    B --> B3["skills/deb-publisher"]
+
+    C --> C1["Git 或本地目录"]
+    C1 --> C2["单 Skill"]
+    C1 --> C3["Collection"]
+    C3 --> C4["waza/think"]
+    C3 --> C5["waza/check"]
+
+    D --> D1["Git 或本地目录"]
+    D1 --> D2["单 Skill"]
+    D1 --> D3["Collection"]
+    D3 --> D4["company/security-review"]
+    D3 --> D5["company/release"]
+```
+
+### 来源注册方式
+
+| 类型 | 含义 | 配置来源 | 用户界面展示 |
+| --- | --- | --- | --- |
+| `builtin` | 随当前 skiff 仓库提供 | `skills/` | `builtin` |
+| `catalog` | skiff 预先登记、所有用户可发现的来源 | `catalog.yaml` | `catalog:<name>` |
+| `custom` | 用户在本机显式注册的命名来源 | `~/.config/skiff/config.yaml` | `custom:<name>` |
+
+`builtin` 比 `owned` 更适合作为用户可见名称，因为它表达 Skill 的分发位置和可用
+方式，而不是仓库的所有权关系。
+
+`catalog` 比 `registry` 更准确：当前文件只是 skiff 随仓库维护的预置来源目录，
+并不是远程注册中心，也不是一种 Skill 来源协议。
+
+### 三个正交维度
+
+每个 provider 应由三个维度描述：
+
+```text
+registration: builtin | catalog | custom
+transport:    bundled | local | git
+layout:       single | collection
+```
+
+custom source 示例：
+
+```text
+registration: custom
+name:         company
+transport:    local | git
+layout:       single | collection
+```
+
+catalog entry 示例：
+
+```text
+registration: catalog
+name:         waza
+transport:    local | git
+layout:       single | collection
+```
+
+`external` 只适合描述物理位置，可作为 catalog 和部分 custom provider 的统称，
+不应成为与 builtin、custom 并列的持久化类型。
+
+## `select` 展示
+
+`skiff select` 应同时展示 builtin、catalog 和 custom Skill：
+
+```text
+[ ] ack                         builtin
+[ ] deb-publisher               builtin
+[-] company                     custom source
+    [ ] company/release         custom:company
+    [ ] company/security-review custom:company
+[-] waza                        catalog source
+    [ ] waza/check              catalog:waza
+    [ ] waza/think              catalog:waza
+```
+
+建议遵循以下规则：
+
+- builtin Skill 直接显示 Skill 名称。
+- catalog 和 custom collection 都使用来源名称作为父节点。
+- catalog 和 custom Skill 都使用 `<source>/<skill>` 作为选择器键。
+- 单 Skill 来源可以省略父节点，但仍显示注册方式和来源名称。
+- 不同来源安装后名称相同时，继续拒绝同时选择，避免覆盖同一安装路径。
+
+## 配置表示
+
+新写入的 `.skills.yaml` 使用以下形式：
+
+```yaml
+skills:
+  - name: ack
+    source: builtin
+  - name: security-review
+    source: company
+  - name: think
+    source: catalog:waza
+```
+
+custom source 在 manifest 中继续保存其逻辑名称，例如 `company`。这样不同机器可以
+独立配置仓库地址，而项目只依赖稳定的来源名称。
+
+## 兼容策略
+
+用户可见术语已经调整，并保留以下读取兼容，避免已有项目立即失效：
+
+1. 对外文档、CLI 输出和 selector 统一使用 `builtin`、`catalog:<name>` 和
+   `custom:<name>`。
+2. 新生成的 `.skills.yaml` 对内置 Skill 写入 `source: builtin`。
+3. 读取旧 manifest 时继续接受 `source: owned`，并在解析时归一化为 `builtin`。
+4. CLI 参数在过渡期继续接受 `--source owned`，但帮助和输出只推荐 `builtin`。
+5. 读取旧 manifest 中的 `source: registry` 和 `registry: <name>`，归一化为
+   `catalog:<name>`。
+6. 主文件使用 `catalog.yaml`；不存在时兼容读取旧 `registry.yaml`。
+7. custom source 的逻辑名称和现有 `config.yaml` 结构保持不变。
+8. 将 `builtin`、`catalog` 和兼容别名 `owned`、`registry` 设为 custom source
+   保留字。
+9. `select` 同步接入 custom Skill，并让 custom collection 与 catalog collection
+   使用相同的父子展示逻辑。
+
+## 实现范围
+
+当前实现覆盖：
+
+- `skiff/skills.py`：来源解析、归一化和 builtin 命名。
+- `skiff/project.py`：manifest 默认值、序列化与旧值兼容。
+- `skiff/sources.py`：来源保留字。
+- `skiff/catalog.py`：catalog 配置、checkout 与 Skill 发现。
+- `skiff/cli.py`：`list`、`status`、`add`、`select` 和输出文案。
+- `skiff/selector.py`：统一 catalog/custom collection 的父子展示。
+- CLI 与来源解析测试。
+- 根 README、`skiff/README.md`、`skills/skiff/SKILL.md` 和相关示例。
+
+## 验证要求
+
+实施完成后至少覆盖：
+
+- builtin Skill 可以通过新名称列出、选择、安装和写入 manifest。
+- 旧的 `source: owned` manifest 仍可同步。
+- custom local source 和 custom Git source 都出现在 selector 中。
+- catalog 单 Skill 和 Collection 都保持可选择。
+- custom 单 Skill 和 Collection 都保持可选择。
+- 多来源同名 Skill 必须显式指定来源。
+- 两个选择最终安装为同一个名称时，selector 拒绝冲突。
+- `list`、`status`、`select` 对同一来源使用一致术语。
+
+## 设计前提
+
+迁移前 `registry.yaml` 的真实职责只是维护 skiff 预置的来源目录，而不是提供远程
+发布、版本解析或可信签名等注册中心能力，因此现已改为 `catalog.yaml`。如果未来
+实现真正的远程 registry，应单独定义其协议和与 catalog 的同步关系，不复用旧名称。
@@ -0,0 +1,124 @@
+"""命名 custom skill source 的配置、发现与 Git 管理。"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from skiff import yaml_io
+from skiff.paths import CONFIG_FILE, SOURCES_DIR
+
+RESERVED_SOURCES = {"builtin", "catalog", "owned", "registry"}
+
+
+def validate_source_name(name: str) -> None:
+    from skiff.skills import validate_skill_name
+
+    validate_skill_name(name)
+    if name in RESERVED_SOURCES:
+        raise SystemExit(f"source 名称为保留字: {name}")
+
+
+def load_sources(path: Path | None = None) -> dict[str, dict[str, Any]]:
+    path = path or CONFIG_FILE
+    if not path.is_file():
+        return {}
+    data = yaml_io.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise SystemExit(f"skiff 配置格式错误: {path}")
+    raw = data.get("sources", {})
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise SystemExit(f"skiff 配置 sources 格式错误: {path}")
+    return {str(name): entry for name, entry in raw.items() if isinstance(entry, dict)}
+
+
+def save_sources(sources: dict[str, dict[str, Any]], path: Path | None = None) -> None:
+    path = path or CONFIG_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        yaml_io.safe_dump({"sources": sources}, allow_unicode=True, sort_keys=False),
+        encoding="utf-8",
+    )
+
+
+def source_checkout(name: str, entry: dict[str, Any]) -> Path:
+    local_path = entry.get("local_path")
+    if local_path:
+        return Path(str(local_path)).expanduser().resolve()
+    checkout = entry.get("checkout")
+    if checkout:
+        return Path(str(checkout)).expanduser().resolve()
+    return (SOURCES_DIR / name).resolve()
+
+
+def source_skills_root(name: str, entry: dict[str, Any]) -> Path:
+    checkout = source_checkout(name, entry)
+    raw_subpath = str(entry.get("skills_path", "skills") or "skills")
+    subpath = Path(raw_subpath)
+    if subpath.is_absolute():
+        raise SystemExit(f"source {name!r} 的 skills_path 必须是仓库内相对路径")
+    root = (checkout / subpath).resolve()
+    try:
+        root.relative_to(checkout)
+    except ValueError:
+        raise SystemExit(f"source {name!r} 的 skills_path 不能超出仓库目录") from None
+    return root
+
+
+def discover_source_skills(name: str, entry: dict[str, Any]) -> dict[str, Path]:
+    root = source_skills_root(name, entry)
+    if (root / "SKILL.md").is_file():
+        return {name: root}
+    if not root.is_dir():
+        return {}
+    return {
+        item.name: item
+        for item in sorted(root.iterdir())
+        if item.is_dir()
+        and not item.name.startswith("_")
+        and (item / "SKILL.md").is_file()
+    }
+
+
+def list_source_skills(name: str, entry: dict[str, Any]) -> list[str]:
+    return list(discover_source_skills(name, entry))
+
+
+def fetch_source(name: str, entry: dict[str, Any]) -> Path:
+    if entry.get("local_path"):
+        checkout = source_checkout(name, entry)
+        if not checkout.is_dir():
+            raise SystemExit(f"source {name!r} 的本地仓库不存在: {checkout}")
+        return checkout
+
+    repo = entry.get("repo")
+    if not repo:
+        raise SystemExit(f"source {name!r} 缺少 repo 或 local_path")
+    checkout = source_checkout(name, entry)
+    ref = str(entry.get("ref", "main") or "main")
+    if checkout.exists():
+        if not (checkout / ".git").exists():
+            raise SystemExit(f"source checkout 已存在但不是 Git 仓库: {checkout}")
+        subprocess.run(["git", "-C", str(checkout), "fetch", "--all", "--tags"], check=True)
+        subprocess.run(["git", "-C", str(checkout), "checkout", ref], check=True)
+        subprocess.run(["git", "-C", str(checkout), "pull", "--ff-only"], check=True)
+    else:
+        checkout.parent.mkdir(parents=True, exist_ok=True)
+        subprocess.run(
+            [
+                "git",
+                "clone",
+                "--depth",
+                "1",
+                "--branch",
+                ref,
+                "--",
+                str(repo),
+                str(checkout),
+            ],
+            check=True,
+        )
+    return checkout
@@ -68,6 +68,9 @@ def find_repo_root(start: Path | None = None) -> Path | None:
    for directory in [start, *start.parents]:
        if (directory / ".skills.yaml").is_file():
            return directory
-        if (directory / "skills").is_dir() and (directory / "registry.yaml").is_file():
+        if (directory / "skills").is_dir() and (
+            (directory / "catalog.yaml").is_file()
+            or (directory / "registry.yaml").is_file()
+        ):
            return directory
    return None
@@ -236,11 +236,12 @@ def _dump_list_dict_item(item: dict[str, Any], indent: int) -> list[str]:
    lines: list[str] = []
    first = True
    for key, value in item.items():
-        prefix = f"{pad}- " if first else f"{pad}  "
+        is_first = first
+        prefix = f"{pad}- " if is_first else f"{pad}  "
        first = False
        if isinstance(value, (dict, list)):
            lines.append(f"{prefix}{key}:")
-            nested = _dump(value, indent + 4 if first else indent + 2)
+            nested = _dump(value, indent + 2 if is_first else indent + 4)
            lines.append(nested.rstrip())
        else:
            lines.append(f"{prefix}{key}: {_scalar(value)}")
@@ -0,0 +1,28 @@
+# skill-name
+
+用一句话告诉使用者这个 skill 能解决什么问题。
+
+## 什么时候使用
+
+- 给出用户可以直接说出的典型请求。
+- 说明适用范围。
+
+## 使用前准备
+
+- 列出需要用户提前提供或确认的信息、权限和依赖。
+
+## 使用示例
+
+```text
+给出一条可以直接交给 Agent 的示例请求。
+```
+
+## Agent 会做什么
+
+1. 用面向使用者的语言概括主要步骤。
+2. 说明可能发生的外部写操作或重要边界。
+
+## 如何判断完成
+
+- 说明使用者最终会得到什么，以及如何确认结果正确。
+
@@ -1,7 +1,7 @@
 ---
 name: skill-name
 description: >-
-  简要描述 skill 做什么、何时触发。Include trigger keywords so agents can match automatically.
+  简要描述 skill 做什么、何时触发。写入用户可能使用的触发表达，让 Agent 能自动匹配。
 ---

 # Skill 名称
@@ -15,6 +15,10 @@ description: >-
 - 触发场景 1
 - 触发场景 2

+## 不适用
+
+- 不应触发的相近场景
+
 ---

 ## 步骤
@@ -28,3 +32,7 @@ description: >-
 ## 注意事项

 - 约束或边界条件
+
+## 验证
+
+- 说明如何确认 skill 的执行结果正确
@@ -0,0 +1,252 @@
+# ACK
+
+ACK 是一个显式调用的 Agent Skill，用三种独立角色运行工程协作闭环：
+
+- Coordinator 拆解需求、派发任务并终检。
+- Developer 实现并执行白盒验证。
+- Test 独立执行黑盒复测。
+
+关键约束是验证者不等于实现者。每个任务最多修复三轮，仍未通过时记录为
+`leftover`，然后继续处理其它任务。
+
+项目还可以声明一个可选的交付阶段：任务全部验证后，ACK 按项目维护的 profile
+构建 DEB 或镜像、发布产物、创建 PR，并在授权范围内部署。交付配置默认关闭，
+稳定发布与生产部署始终保留人工批准点。
+
+显式调用 `$ack` 也可以直接处理一次性交付：ACK 根据请求把源码发布/发布 PR、DEB、
+Docker 镜像分别路由给 `manage-release`、`deb-publisher` 或
+`publish-docker-image`。实际操作由独立 Operator 执行；它使用与 Test 相同的低成本
+模型和 reasoning effort，但不复用 Test terminal，也不进入 Developer → Test 闭环。
+
+## 安装
+
+全局安装：
+
+```bash
+skiff add ack -g
+```
+
+或只安装到当前项目：
+
+```bash
+skiff add ack
+```
+
+ACK 只在用户显式调用 `/ack` 或 `$ack` 时运行。
+
+## 初始化项目
+
+```bash
+skiff init ack
+skiff init ack --project ~/code/my-app
+```
+
+初始化后，项目只保存自己的 ACK 状态：
+
+```text
+docs/ack/
+├── project.md
+├── tasks.yaml
+├── knowledge.yaml
+└── delivery.yaml       # 默认 enabled: false
+```
+
+不会在项目中复制或链接 ACK Skill。通用规范、模板和脚本始终从已安装的 Skill
+目录读取。
+
+## Skill 结构
+
+```text
+skills/ack/
+├── SKILL.md
+├── README.md
+├── VERSION
+├── references/     # 三角色规范、闭环流程和初始化说明
+├── templates/      # project.md、tasks.yaml、knowledge.yaml、delivery.yaml 模板和 schema
+├── examples/       # 完整示例
+└── scripts/        # 状态校验、知识选择、安全验证执行与结构化 worker launcher
+```
+
+`SKILL.md` 是 Agent 的工作流入口。`references/` 是按需读取的稳定规范；
+`docs/ack/project.md` 只保存当前项目的命令、路径和权限差异；
+`docs/ack/tasks.yaml` 保存当前任务状态；`docs/ack/knowledge.yaml` 保存跨任务复用、
+已经独立验证的项目知识护栏。
+`docs/ack/delivery.yaml` 声明项目特有的构建、发布和部署能力；每次执行结果另记在
+`tasks.yaml.deliveryRuns`，配置与运行状态不会混在一起。
+
+## 检查项目状态
+
+Agent 会从当前 ACK Skill 目录解析校验脚本：
+
+```bash
+python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
+python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml \
+  --tasks docs/ack/tasks.yaml
+python3 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml \
+  --tasks docs/ack/tasks.yaml --project-root <project-root>
+```
+
+Coordinator 可以按当前任务上下文做确定性推荐：
+
+```bash
+python3 <ack-skill-dir>/scripts/select_knowledge.py docs/ack/knowledge.yaml \
+  --component web --path web/app.py --tag long-running-service --limit 10
+```
+
+默认 JSON 输出会同时给出固定知识引用和已解析的 `verificationTarget.path/args`；
+选择器只输出数据，不执行检查。`scope.all=true` 的全项目 active 规则优先占用
+`--limit`；如果全项目规则本身超过预算，选择器会显式失败，不会静默漏派。
+
+需要执行知识项引用的检查时，只传 registry ID 给 ACK 的安全执行入口：
+
+```bash
+python3 <ack-skill-dir>/scripts/run_verification.py \
+  docs/ack/knowledge.yaml check-api-contract --project-root <project-root>
+```
+
+该入口会在执行前重新校验知识库，只打开一次项目根目录 fd，再从同一个 fd 逐段以
+`O_NOFOLLOW` 打开知识库和检查文件；检查内容复制到匿名、尽可能 sealed 的稳定
+快照，再以结构化 argv 和 `shell=False` 启动。它不接受临时命令或额外参数。
+选择器输出的 path/args 只用于审阅，不应由 Agent 自行拼接执行。Runner 只读取
+项目内无 symlink 的权威
+`docs/ack/knowledge.yaml`，不接受替代知识文件或放宽后的项目根。检查进程的 cwd
+和 `ACK_PROJECT_ROOT` 都固定到该根 fd；后者是只在检查进程存活期间有效的
+`/proc/self/fd/...` 或 `/dev/fd/...` 路径。原始可读路径另放在
+`ACK_PROJECT_ROOT_DISPLAY`，只能用于日志，不能用于资源访问。Runner 还提供
+`ACK_VERIFICATION_REF` 和 `ACK_VERIFICATION_PATH`；检查脚本必须据此定位资源，
+不能依赖 `$0` 或 `__file__` 所在目录，因为实际执行的是匿名快照。
+
+知识先由 Developer 或 Test 作为 `candidate` 提名，经独立验证和 Coordinator gate
+后才能成为 `active`。Coordinator 按路径、组件、依赖、版本和标签推荐相关知识，
+确认后将固定 revision 的 `knowledgeRefs` 写入任务上下文；每轮只派发命中的少量
+条目，不全量注入知识库。
+
+旧项目只有 `project.md` 和 `tasks.yaml` 时，不要重跑初始化。由 `/ack` 检查现有
+状态，获得用户授权后补一个空的 `knowledge.yaml`；如果任务板尚未声明知识库，
+同时只补 `project.knowledgeFile: docs/ack/knowledge.yaml`，再运行跨文件校验。
+
+只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`。知识正文不能作为自由 shell
+执行；关键约束应继续下沉到测试、lint、CI 或正式规范。ACK 不自动修改项目的
+`AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+
+## 配置与运行交付
+
+用户可以直接向 `/ack` 描述项目差异，例如“这个项目用 `make deb` 构建 DEB，推到
+preview APT 源，再部署到开发机”。ACK 会把它维护成
+`docs/ack/delivery.yaml` 中的声明式 entrypoint、artifact、destination、environment
+和 profile，校验后展示 diff；首次配置保持关闭，确认后才启用。
+
+交付配置只允许声明式工具 target 或仓库内可执行脚本，不接受自由 shell，也不保存
+凭据值。ACK 在任务进入 `verified` 后，按用户确认的 profile 执行，并把 revision、
+PR、产物摘要、部署目标、健康检查和日志引用写入 `tasks.yaml.deliveryRuns`。默认
+profile 只能停在 `review_ready`；稳定发布或生产部署必须经过对应 approval 步骤。
+具体契约见 `references/delivery.md`。
+
+## 一次性交付路由
+
+直接发布时可以说：
+
+```text
+$ack 为 v1.4.0 创建 release PR，合并后打 tag。
+$ack 把 1.4.0 的 amd64 DEB 发布到 testing 仓库。
+$ack 把当前提交发布成 registry.example.com/team/app:1.4.0。
+```
+
+源码版本生命周期和一次性 PR/MR 路由到 `manage-release`，DEB/APT 路由到
+`deb-publisher`，Docker/OCI 镜像路由到 `publish-docker-image`。普通 PR/MR 只执行
+`manage-release` 的 `PR-only` 流程，不会被误当成完整版本发布；功能任务 verified 后
+按 profile 自动开 PR 时仍使用 ACK 原有的 `pull-request` 动作。一次性交付要求任务板配置
+`defaults.operator`；当前模板已经提供，并强制其 CLI、standard 模型和 reasoning
+effort 与 Test default 相同。详见 `references/delivery-routing.md`。
+
+## 启动 Worker
+
+worker 的机器配置位于 `tasks.yaml.project.orchestration`：项目显式维护模型
+allowlist、结构化 profile、默认 profile 和允许的 worktree。不得在 `project.md`
+或任务里保存完整启动命令、额外 argv 或环境变量。
+
+先审阅计划，不产生终端：
+
+```bash
+python3 <ack-skill-dir>/scripts/launch_worker.py plan \
+  --project-root <project-root> \
+  --task-id <task-id> \
+  --attempt-id <task-id>-A<round> \
+  --role developer \
+  --profile-id codex-dev-standard \
+  --worktree <allowed-worktree>
+```
+
+确认后执行 `launch`，并显式绑定刚审阅的 fingerprint：
+
+```bash
+python3 <ack-skill-dir>/scripts/launch_worker.py launch \
+  --project-root <project-root> \
+  --task-id <task-id> \
+  --attempt-id <task-id>-A<round> \
+  --role developer \
+  --profile-id codex-dev-standard \
+  --worktree <allowed-worktree> \
+  --expected-launch-fingerprint <plan 中的 sha256:...>
+```
+
+launcher 是自动创建 worker 的唯一入口：它从权威任务板重读 profile，构造固定
+argv，忽略调用者 PATH、使用环境 allowlist，并验证真实 Git worktree 注册；然后
+通过仓库外的单次启动记录、terminal-bound nonce/proof 和受限 bootstrap 调用 Orca。
+返回的 receipt 含 `runtimeId`、handle、incarnation、profile hash、slot 和 worktree
+identity。Coordinator 将 receipt 追加到顶层 `workerReceipts`，再把 receipt ID
+写入任务的 `dispatch.developer`、`dispatch.test` 或 `dispatch.operator`，并同步写入
+本轮 `attemptId`。
+校验器要求 receipt 与当前 ACK task、角色、profile 和 attempt 完全一致；历史 receipt
+不能跨任务或跨轮次改挂。
+
+v0.10 自动 launcher 仅支持 `read-only` 与 `workspace-write`。full-access、
+Codex bypass、Cursor YOLO/force 和关闭 sandbox 都会 fail closed；在有可信平台
+审批或独立签发通道之前，不用项目文件伪装成用户授权。旧任务板没有结构化
+`project.orchestration` 时仍可读取和手动协作，但不得自动创建 worker。
+
+持久化 `receiptHash` 是无密钥 checksum，不是 launcher 身份证明。由于 Orca 当前
+不能证明旧终端的原始 argv/模型/权限，v0.10 不自动复用既有 worker；每次自动派发
+都重新 `plan` 并用 expected fingerprint 启动 fresh worker。
+fingerprint 只校验完整计划没有漂移，不是一次性令牌；成功后不得用同一 fingerprint
+重复启动，结果不确定时必须先 reconcile。
+若创建或关闭回执不完整，或外部 launch record 状态无法可靠持久化，launcher 会返回
+`indeterminate/reconcile-required`；必须先核对 record 与 Orca live state，不能
+直接重试。
+
+## 开始一个需求
+
+初始化完成后可以直接说：
+
+```text
+/ack 处理这个需求：<一句话需求>
+```
+
+Coordinator 会先读取项目状态和 `references/kickoff.md`，生成产品文档、任务拆分与
+可观测验收信号；用户确认后才派发实现和复测。
+
+首次配置交付可以说：
+
+```text
+/ack 更新项目交付配置：用 make build-deb 构建 DEB，发布到 preview APT 仓库，
+部署到 test-server 并跑健康检查；完成后创建 PR，停在 review_ready 给我审核。
+```
+
+之后处理需求时只需在确认计划中选择 profile：
+
+```text
+/ack 处理这个需求：<一句话需求>。任务验证通过后执行 review profile。
+```
+
+ACK 会自动读取 `delivery.yaml`，无需再逐步提醒它构建、上传、部署或开 PR；目标或
+权限发生漂移、缺少凭据、进入 stable/production approval 时才停下来请求决策。
+
+## 版本
+
+当前 Skill 版本见 `VERSION`。新项目在 `tasks.yaml` 中以合法 SemVer 记录
+`ackVersion`。从 `0.10.0` 起，`project.orchestration` 与顶层 `workerReceipts` 必须
+同时存在；从 `0.11.0` 起，新项目还会生成默认关闭的 `delivery.yaml`，并在任务板声明
+`project.deliveryFile` 与 `deliveryRuns`；从 `0.12.0` 起，新模板包含与 Test 同档模型的
+Operator，用于一次性交付路由。旧项目可以不迁移而继续使用原闭环，但补齐 Operator
+前不能使用一次性交付。旧项目的 `kitVersion` 可以继续读取，但建议迁移为
+`ackVersion`。
@@ -0,0 +1,221 @@
+---
+name: ack
+description: >-
+  初始化、检查并运行 ACK 三角色协作闭环。仅在用户显式调用 /ack 或 $ack，并要求
+  初始化 ACK、检查 docs/ack 配置、按 ACK 规划需求、指挥 Coordinator/Developer/Test
+  工作、配置并执行任务验证后的项目交付流程，或把一次性 PR/发布请求路由给
+  manage-release、deb-publisher、publish-docker-image 普通 worker 时使用。
+---
+
+# ACK 项目协作入口
+
+本 Skill 是 ACK 的完整能力包：`references/` 保存通用规范，`templates/` 保存项目
+状态模板，`scripts/` 保存校验工具。目标项目只在 `docs/ack/` 保存 `project.md`、
+`tasks.yaml`、`knowledge.yaml` 和默认关闭的 `delivery.yaml`，不要复制或链接 Skill
+内容。
+
+开始时解析当前 `SKILL.md` 所在目录，记为 `<ack-skill-dir>`。所有通用规范、模板和
+脚本都相对此目录访问，不依赖固定的全局安装路径。
+
+## 选择模式
+
+- 用户要求初始化、接入或安装 ACK：执行“初始化”。
+- 用户要求检查 ACK 是否可用、配置是否完整：执行“检查”。
+- 用户要求用 ACK 做需求、修复问题或继续任务：执行“工作”。
+- 用户用自然语言要求增加、修改或关闭项目交付流程：执行“交付配置维护”。
+- 用户直接要求创建发布 PR/MR、发布源码版本、DEB 或 Docker 镜像：执行
+  “一次性交付路由”。
+
+始终先解析真实项目根目录。优先使用 `git rev-parse --show-toplevel`；不是 Git
+项目时使用用户指定目录或当前目录。不要修改项目的 `AGENTS.md`、`CLAUDE.md`
+或其它 Agent 指令文件。
+
+## 初始化
+
+1. 确认 `skiff` 可执行，并检查 `<project>/docs/ack` 是否存在。
+2. 不存在时执行：
+
+   ```bash
+   skiff init ack --project <project-root>
+   ```
+
+   该命令从本 Skill 的 `templates/` 生成项目状态，不会在项目中创建 Skill
+   软链接或资源副本。
+3. 如果 `docs/ack` 已存在，不重复初始化、不覆盖文件；转入“检查”。旧项目只有
+   `project.md` 与 `tasks.yaml` 时，先报告缺少 `knowledge.yaml`。用户授权后，
+   从 `templates/knowledge.template.yaml` 生成这个缺失文件并替换项目名和时间；若
+   `tasks.yaml` 尚无 `project.knowledgeFile`，同时只补
+   `docs/ack/knowledge.yaml` 这一项。不要重跑 `skiff init`，也不要改写其它已有
+   项目状态。
+4. 读取项目的公开配置和文档，例如 README、语言清单、包管理清单、测试配置与
+   CI，确定项目名、技术栈、源码/规格/测试路径及真实可执行命令。
+5. 完善 `docs/ack/project.md`：
+   - 用实际项目值替换全部占位符。
+   - 无服务地址时把 Base URL 写为 `n/a`，不要虚构端口。
+   - 无法从项目证据确定的命令写为 `n/a`，并在结果中列为待配置项。
+   - 只写项目差异，不复制 `references/` 中的通用规范。
+6. 完善 `docs/ack/tasks.yaml` 的项目信息。纯初始化且用户没有提供真实任务时，
+   删除模板示例任务并保留 `tasks: []`；不要虚构需求或缺陷。
+7. 检查 `docs/ack/knowledge.yaml`。新项目没有已验证的项目经验时保留
+   `verificationRegistry: {}` 与 `entries: []`，不从聊天、README 或单次失败中
+   猜测并激活知识。
+8. 检查 `docs/ack/delivery.yaml`。新项目保留 `enabled: false`、空能力表和空 profile；
+   不从 README 或 CI 猜测、启用交付。旧项目没有该文件时仍可继续使用原 ACK
+   闭环；只有用户明确要求配置交付时，才按“交付配置维护”补齐。
+9. 更新 `updatedAt`，并运行：
+
+   ```bash
+   python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
+   python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml \
+     --tasks docs/ack/tasks.yaml
+   python3 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml \
+     --tasks docs/ack/tasks.yaml --project-root <project-root>
+   ```
+
+10. 检查 `project.md`、`tasks.yaml`、`knowledge.yaml` 与 `delivery.yaml` 是否仍有
+   `<...>` 占位符。
+   结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”并列出
+   缺失值。
+11. 报告创建的路径、检测到的命令、校验结果和下一步。除非用户明确要求，不提交、
+   不推送。
+
+## 检查
+
+1. 检查以下路径：
+   - `docs/ack/project.md`
+   - `docs/ack/tasks.yaml`
+   - `docs/ack/knowledge.yaml`
+   - `docs/ack/delivery.yaml`（旧项目可无；存在或被任务板引用时必须校验）
+2. 读取 `<ack-skill-dir>/VERSION`，对比 `tasks.yaml` 的 `ackVersion`。旧项目只有
+   `kitVersion` 时仍可读取，但建议迁移为 `ackVersion`。`ackVersion` 必须是合法
+   SemVer；从 `0.10.0` 起 `project.orchestration` 与顶层 `workerReceipts` 必须同时
+   存在。
+3. 查找未替换占位符，并核对项目路径、覆盖层路径、Developer 白盒命令、Test
+   黑盒命令和 Base URL。
+4. 使用 `<ack-skill-dir>/scripts/validate_tasks.py` 校验任务板，使用
+   `<ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks
+   docs/ack/tasks.yaml` 校验项目知识和跨文件引用。如果存在交付配置或任务板声明了
+   `project.deliveryFile`，再使用 `<ack-skill-dir>/scripts/validate_delivery.py
+   docs/ack/delivery.yaml --tasks docs/ack/tasks.yaml --project-root <project-root>`
+   校验交付能力、顺序、安全边界和跨文件引用。只报告证据明确的问题，不因旧项目
+   缺少可选交付配置而宣称失败。
+5. 检查知识引用能解析到固定 revision，candidate 仍留在任务证据中，且
+   `stale`、`superseded` 和 `archived` 不会被当作可派发的 `active` 知识。
+6. 若存在 `project.orchestration`，检查 profile、model allowlist、默认 profile、
+   允许 worktree、顶层 `workerReceipts` 与 `dispatch.developer/test/operator` 的引用；receipt
+   必须绑定当前 ACK task、同一 role/profile/attempt，`receiptId` 与 `attemptId`
+   必须同时为空或同时填写。
+   缺少结构化路由的旧任务板只能使用手动模式，不能自动创建 worker。
+   `defaults.operator` 对旧项目可选；存在时必须是 standard profile，且 CLI、模型与
+   reasoning effort 必须和 `defaults.test` 相同。缺少它只表示一次性交付路由不可用，
+   不影响原 Developer/Test 闭环。
+7. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。
+
+## 一次性交付路由
+
+1. 读取 `references/delivery-routing.md` 并按用户原始请求分类。源码版本、release/hotfix
+   分支、普通或发布 PR/MR、tag 或 Forge Release 使用 `manage-release`；普通 PR/MR
+   只授权它的 `PR-only` 流程，不推断版本升级、合并或 tag。DEB/APT 使用
+   `deb-publisher`；Docker/OCI registry 使用 `publish-docker-image`。
+2. 若 `docs/ack/tasks.yaml` 不存在，或结构化 orchestration 没有通过校验的
+   `defaults.operator`，停止并建议初始化或按当前模板升级。不要由 Coordinator 亲自
+   执行，也不要猜模型。用户请求有多个合理路由且无法从项目事实唯一确定时，只问一个
+   最小澄清问题。
+3. 在权威任务板新增 `type: delivery-operation` 的最小操作记录，`operation.skill` 保存
+   精确 Skill 名，`operation.request` 保留本次用户请求的授权语义；若原文含凭据值，
+   必须替换为 `[REDACTED]`，不能落盘。`dispatch.operator` 使用
+   `defaults.operator`。不为一次性交付写 PRD，也不进入 Developer → Test 闭环，
+   不读取或修改 `delivery.yaml`。
+4. 运行 `validate_tasks.py`，再只用 `launch_worker.py plan|launch --role operator`
+   创建 fresh worker。审阅并绑定 fingerprint/receipt 后，把
+   `references/delivery-routing.md` 的 Operator prompt 和原始请求投递给 worker；
+   Orca 模式同时读取 `references/orca-adapter.md`，登记单一操作任务与 dispatch。
+   Operator 使用与 Test 相同的低成本模型/effort，但它是独立角色和独立终端，不复用
+   Test worker。
+5. 被选中的低层 Skill 决定实际步骤、确认点、硬停止与恢复。ACK 路由和项目配置都不能
+   扩大用户授权；Docker 路由只因用户显式调用 `$ack` 且明确要求发布镜像才视为对
+   `publish-docker-image` 的显式委派。
+6. Coordinator 只读 worker 证据并对照低层 Skill 完成标准终检。满足原始请求才把操作
+   标为 `verified`；可恢复的安全停止标为 `blocked`。远端写入部分成功或状态不确定时
+   不自动重试，先按低层 Skill 发现真实状态。
+
+## 工作
+
+1. 若 `docs/ack` 不存在，停止并建议先用 `/ack` 初始化；不要静默初始化。
+2. 依次读取：
+   - `docs/ack/project.md`
+   - `docs/ack/tasks.yaml`
+   - 通过 `<ack-skill-dir>/scripts/select_knowledge.py` 从
+     `docs/ack/knowledge.yaml` 选择的当前任务相关 `active` 条目
+   - `<ack-skill-dir>/references/kickoff.md`
+   - kickoff 指定且与当前任务相关的 references 文件
+   - 若 `tasks.yaml.project.deliveryFile` 存在，再读取该 `delivery.yaml` 和
+     `<ack-skill-dir>/references/delivery.md`
+3. 当前会话担任 Coordinator，遵守项目覆盖层中的命令、路径权限、模型路由和
+   worker 启动规则。项目覆盖层优先于通用示例命令。按 scope 推荐相关 `active`
+   知识，经确认后把固定 revision 的显式 `knowledgeRefs` 写入当前任务上下文；
+   不全量注入知识库。
+4. 新需求先写产品文档、任务拆分与可观测验收信号，更新 `tasks.yaml` 并校验，
+   然后交给用户确认；若启用了交付，还要把本次 profile、目标、停止点和需要审批的
+   步骤放入同一份计划。确认前不派发实现，也不执行交付。
+5. 创建或更换 Developer、Test 或 Operator worker 时，只使用
+   `<ack-skill-dir>/scripts/launch_worker.py plan|launch` 读取
+   `tasks.yaml.project.orchestration` 的 profile。不得直接执行
+   `orca terminal create --command`，不得接受或拼接自由 command、额外 argv、
+   executable、env 或 cwd。必须先审阅 `plan.launchFingerprint`，再把它作为
+   `launch --expected-launch-fingerprint` 传入。v0.10 不根据持久化 receipt 自动
+   复用旧终端；每次自动派发都创建 fresh worker，receipt 只作审计与 dispatch
+   关联。
+6. 用户已确认的任务按 ACK 闭环执行：Developer 实现与白盒验证，Test 独立黑盒
+   复测，Coordinator 读取证据终检并唯一写入 `tasks.yaml`。Developer 回报
+   `knowledgeApplied` 和 `knowledgeCandidates`，Test 回报 `knowledgeChecks`；
+   `candidate` 只有在独立验证和 gate 后才能由 Coordinator 写入或激活。
+7. 执行知识项的 `verification.ref` 时，只调用
+   `<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
+   <verification-ref> --project-root <project-root>`。不要直接执行选择器返回的 path/args，
+   也不要给 runner 注入额外命令或参数。
+8. 不把 `worker_done` 或 Test 自报成功直接当作完成。每项最多三轮，仍失败则记录
+   `leftover` 并继续其它任务。
+9. 关键的安全、正确性和兼容性约束应下沉为测试、lint、CI 或正式规范；
+   `knowledge.yaml` 只保存触发条件、原因与证据引用，不能替代可执行控制。
+10. 选定任务全部进入 `verified` 后，若 `delivery.enabled: true` 且用户确认的本次计划
+    包含交付，按 `references/delivery.md` 顺序执行 profile，并由 Coordinator 把证据
+    写入 `tasks.yaml.deliveryRuns`。任务状态保持 `verified`；交付失败只改变 delivery
+    run，不回写成任务失败。默认 profile 最多到 `review_ready`，稳定发布和生产部署
+    必须在对应步骤再次取得明确批准。
+
+## 交付配置维护
+
+1. 读取 `references/delivery.md`、模板、schema、现有 `delivery.yaml`、项目构建/发布
+   入口和 CI；把用户自然语言描述转换为结构化 entrypoint、artifact、destination、
+   environment 与 profile。配置只引用仓库内脚本或声明式工具 target，不保存 shell。
+2. 若旧项目首次启用，生成 `docs/ack/delivery.yaml`，在 `tasks.yaml.project` 增加
+   `deliveryFile: docs/ack/delivery.yaml`，并增加顶层 `deliveryRuns: []`；不改写其它
+   项目状态。首次生成保持 `enabled: false`，先展示 diff 和解析出的执行顺序。
+3. 运行 delivery、tasks 和跨文件校验；需要的脚本不存在、不可执行、引用不完整或
+   涉及凭据正文时 fail closed。凭据只写 secret 名称，值由外部环境提供。
+4. 用户确认后才把配置设为启用。配置修改只影响下一次 delivery run；已确认或正在
+   执行的 run 使用开始时审阅的 commit/config revision 快照，不能借当前分支修改
+   扩大权限。
+
+## 边界
+
+- 不修改或追加任何项目 Agent 指令文件，包括 `AGENTS.md`。
+- 不在项目中维护第二份 ACK 通用规范、模板或任务 schema。
+- 不猜测项目命令、服务地址、worker handle 或模型名称。
+- 不把 full-access、bypass、YOLO/force、关闭 sandbox 或项目内“授权”字段当成
+  v0.10 自动 worker 的合法配置；当前一律 fail closed。
+- 不把无密钥 `receiptHash` 或 Orca live metadata 当作旧终端的启动 attestation；
+  v0.10 不自动复用既有 worker。
+- launcher 返回 `indeterminate` 或 `reconcile required` 时，不直接重试；先按
+  launch ID、外部 record 和 Orca live state 完成人工核对。
+- 不覆盖已有 `docs/ack` 文件；除用户确认的 ACK 任务或 delivery profile 外，不擅自
+  提交、推送、创建终端、新 worktree、发布产物或部署。
+- 只有 Coordinator 写 `tasks.yaml`、`knowledge.yaml` 和 `deliveryRuns`；Developer
+  与 Test 只读，只能通过回报提名或验证知识；Operator 同样只读这些状态文件，只回传
+  一次性交付证据。`delivery.yaml` 只在显式的交付配置维护中修改。
+- 不把知识正文或选择器输出拼成 shell；知识检查只能通过 `run_verification.py`
+  按 registry ID 执行。不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+- 项目只保存 `docs/ack/project.md`、`docs/ack/tasks.yaml`、
+  `docs/ack/knowledge.yaml` 和可选的 `docs/ack/delivery.yaml`；通用资源始终从当前
+  ACK Skill 目录读取。
@@ -0,0 +1 @@
+0.12.0
@@ -0,0 +1,6 @@
+interface:
+  display_name: "ACK"
+  short_description: "运行 ACK 开发验证闭环，并路由 PR、源码、DEB 与镜像发布"
+  default_prompt: "Use $ack to initialize or check ACK, coordinate verified work, maintain delivery configuration, run an approved delivery profile, or route a one-off release request to a low-cost operator."
+policy:
+  allow_implicit_invocation: false
@@ -0,0 +1,149 @@
+version: 1
+updatedAt: "2026-08-01T10:00:00+08:00"
+project:
+  name: "notes-api"
+
+enabled: true
+defaultProfile: "review"
+
+entrypoints:
+  verify:
+    kind: make
+    target: verify
+    args: []
+    requiredSecrets: []
+    workingDirectory: "."
+    timeoutSeconds: 1800
+  build-deb:
+    kind: make
+    target: build-deb
+    args: []
+    requiredSecrets: []
+    workingDirectory: "."
+    timeoutSeconds: 3600
+  build-image:
+    kind: make
+    target: build-image
+    args: []
+    requiredSecrets: []
+    workingDirectory: "."
+    timeoutSeconds: 3600
+  upload-deb:
+    kind: script
+    path: "scripts/upload-preview-deb.sh"
+    args: []
+    requiredSecrets: ["DEB_TOKEN"]
+    workingDirectory: "."
+    timeoutSeconds: 900
+  upload-image:
+    kind: script
+    path: "scripts/publish-preview-image.sh"
+    args: []
+    requiredSecrets: ["REGISTRY_TOKEN"]
+    workingDirectory: "."
+    timeoutSeconds: 1800
+  deploy-test:
+    kind: script
+    path: "scripts/deploy-test.sh"
+    args: []
+    requiredSecrets: []
+    workingDirectory: "."
+    timeoutSeconds: 900
+  health-test:
+    kind: script
+    path: "scripts/check-test.sh"
+    args: []
+    requiredSecrets: []
+    workingDirectory: "."
+    timeoutSeconds: 300
+  rollback-test:
+    kind: script
+    path: "scripts/rollback-test.sh"
+    args: []
+    requiredSecrets: []
+    workingDirectory: "."
+    timeoutSeconds: 900
+
+artifacts:
+  service-deb:
+    type: deb
+    build: build-deb
+    outputs: ["dist/*.deb"]
+  service-image:
+    type: oci-image
+    build: build-image
+    image: "registry.example.com/notes/service"
+    platforms: ["linux/amd64", "linux/arm64"]
+
+destinations:
+  preview-apt:
+    type: apt-repository
+    channel: preview
+    endpoint: "https://packages.example.com"
+    repository: "testing"
+    upload: upload-deb
+  preview-registry:
+    type: oci-registry
+    channel: preview
+    registry: "registry.example.com"
+    repository: "notes/service"
+    upload: upload-image
+
+environments:
+  test-server:
+    type: ssh-host
+    classification: development
+    target: "notes-test"
+    deploy: deploy-test
+    healthCheck: health-test
+    rollback: rollback-test
+    mutex: "notes-test-deploy"
+
+profiles:
+  review:
+    stopAt: review_ready
+    steps:
+      - id: verify
+        action: verify
+        entrypoint: verify
+      - id: open-pr
+        action: pull-request
+        draft: true
+        remote: origin
+        baseBranch: main
+      - id: build-deb
+        action: build
+        artifact: service-deb
+      - id: publish-deb
+        action: publish
+        artifact: service-deb
+        destination: preview-apt
+      - id: deploy-test
+        action: deploy
+        artifact: service-deb
+        environment: test-server
+      - id: smoke-test
+        action: health-check
+        environment: test-server
+      - id: ready
+        action: mark-ready
+  review-image:
+    stopAt: review_ready
+    steps:
+      - id: verify
+        action: verify
+        entrypoint: verify
+      - id: open-pr
+        action: pull-request
+        draft: true
+        remote: origin
+        baseBranch: main
+      - id: build-image
+        action: build
+        artifact: service-image
+      - id: publish-image
+        action: publish
+        artifact: service-image
+        destination: preview-registry
+      - id: ready
+        action: mark-ready
@@ -0,0 +1,47 @@
+version: 1
+updatedAt: "2026-07-31T12:00:00+08:00"
+project:
+  name: "notes-web"
+verificationRegistry:
+  service-worktree-alignment:
+    path: "tests/ack/check_service_worktree.py"
+    args: ["--require-current-commit"]
+entries:
+  - id: "K-001"
+    revision: 1
+    kind: "verification"
+    status: "active"
+    title: "复测前确认服务与 worktree/commit 对齐"
+    subject: "service-worktree-alignment"
+    scope:
+      all: false
+      components: ["web"]
+      paths: ["web/**"]
+      dependencies: []
+      versions: []
+      tags: ["long-running-service"]
+      symbols: []
+      errorSignatures: []
+    appliesWhen: "修改常驻 Web 服务或前端构建产物"
+    directive: "复测前重启服务，并核对服务实例对应的 worktree 与 commit"
+    rationale: "历史任务曾因 Test 连接旧进程而产生假通过"
+    verification:
+      ref: "service-worktree-alignment"
+      expected: "服务实例、worktree 和 commit 一致"
+    provenance:
+      taskId: "BUG-002"
+      attemptId: "BUG-002-A2"
+      codeRef: "abc1234"
+      evidenceRef: "tasks.yaml#BUG-002"
+    owner: "web-team"
+    author: "developer"
+    reviewer: "test"
+    approval: null
+    createdAt: "2026-07-30T10:00:00+08:00"
+    lastValidatedAt: "2026-07-31T11:00:00+08:00"
+    reviewAfter: "2099-10-31T11:00:00+08:00"
+    temporary: false
+    removalCondition: null
+    statusReason: null
+    supersedes: []
+    conflictsWith: []
@@ -0,0 +1,103 @@
+# notes-web Agent 协作协议（示例，项目覆盖层）
+
+> 本项目基于 ack v0.11.0。
+> 通用规范由 `/ack` 从 Skill 自身的 `references/` 读取，本文件只填项目差异。
+> 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
+> ACK 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+> `docs/ack/` 只保存 `project.md`、`tasks.yaml`、`knowledge.yaml` 与 `delivery.yaml`。
+
+## 项目概览
+
+- 项目：`notes-web`
+- 技术栈：`TypeScript + React (Vite) + Go`
+- 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
+- Base URL：`http://localhost:5173`
+- 任务板：`docs/ack/tasks.yaml`
+- 项目知识：`docs/ack/knowledge.yaml`
+- 交付契约：`docs/ack/delivery.yaml`
+- 覆盖层文件：`docs/ack/project.md`
+
+## 稳定规范（引用，不重复）
+
+- 开始一个需求（启动手册）：`references/kickoff.md`
+- 角色 / 权限 / 状态机 / 完成定义：`references/roles-and-permissions.md`
+- 模型档位与升级规则：`references/model-routing.md`
+- 闭环流程（含手动模式、worktree 对齐）：`references/closed-loop.md`
+- 优化方法（验收信号、三轮策略）：`references/optimization-method.md`
+- 派发 prompt 模板：`references/prompt-templates.md`
+- Orca 编排命令：`references/orca-adapter.md`
+- 验证后交付：`references/delivery.md`
+
+## Worker 路由
+
+结构化配置位于 `docs/ack/tasks.yaml` 的 `project.orchestration`，启动记录位于顶层
+`workerReceipts`。本项目默认使用：
+
+| 角色 | profile ID | 档位 |
+|------|------------|------|
+| Developer | `codex-dev-standard` | standard |
+| Test | `codex-test-standard` | standard |
+| Developer 升级 | `codex-dev-strong` | strong |
+
+本文件不保存或拼接 worker shell 命令。
+
+## 路径权限
+
+| 路径 | Coordinator | Test | Developer | 说明 |
+|------|:-----------:|:----:|:---------:|------|
+| `docs/spec/**` | R/W | Read-only | Read-only | 产品规格（PM 拥有） |
+| `tests/browser/**` | Read-only | R/W | Read-only | 浏览器回归用例（Test 拥有） |
+| `.qa-records/**` | Read-only | R/W | Read-only | 复测记录（gitignore） |
+| `web/**`、`server/**` | Read-only | Read-only | R/W | 应用源码 |
+| `**/*_test.go`、`web/**/*.test.tsx` | Read-only | Read-only | R/W | 单元测试 |
+| `config/*.example.*` | Read-only | Read-only | R/W | 可提交配置模板 |
+| `.env`、`config/local.*` | Read-only | Read-only | Read-only | 本地私有配置 |
+| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
+| `knowledge.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写；Developer/Test 通过回报提名或验证 |
+| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 项目交付能力，不是执行授权 |
+
+## 命令
+
+Developer 白盒验证：
+
+```bash
+npm run build
+go test ./...
+npm run dev   # 本地起前端
+```
+
+Test 黑盒复测：
+
+```bash
+curl -s http://localhost:5173/api/health
+curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json
+# 浏览器回归：tests/browser/cases/*.md
+```
+
+项目已审查的知识检查入口保存在 `knowledge.yaml.verificationRegistry`，格式为检查
+ID 对应仓库内相对 path 和结构化 args。知识正文不保存或自动执行自由 shell 命令。
+执行时只把检查 ID 交给 Skill 的 `scripts/run_verification.py`，不直接拼接
+path/args。
+项目状态校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py`、
+`scripts/validate_knowledge.py` 和 `scripts/validate_delivery.py` 执行。
+交付机器入口以 `delivery.yaml` 为准，本覆盖层不维护第二套发布或部署命令。
+
+## 硬规则（其余见 references/）
+
+- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
+- 模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 references/model-routing.md）。
+- 自动 worker 只通过 ACK 的 `scripts/launch_worker.py` 启动；不直接执行自由
+  `orca --command`。v0.10 的自动 profile 只允许 `read-only` 或
+  `workspace-write`，不允许 full-access、bypass、YOLO/force 或关闭 sandbox。
+- 每次自动派发都先审阅 plan，再用 `--expected-launch-fingerprint` 启动 fresh
+  worker；持久化 receipt 只作审计，不授权自动复用旧终端。
+- `worker_done` 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
+- 只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`；Test 与 Developer 只读。
+- Coordinator 只派发按 scope 命中并显式写入 `knowledgeRefs` 的 `active` 知识；
+  `candidate` 不派发，知识库不全量注入。
+- Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
+  `knowledgeChecks`；关键约束应继续下沉到测试、lint、CI 或正式规范。
+- 交付只在任务 `verified` 后运行；默认 profile 停在 `review_ready`。stable 发布与
+  production 部署保留显式 approval，配置变更只影响下一次 run。
+- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续。
+- 不提交、推送、发布或部署，除非用户确认的 ACK 任务或 delivery profile 明确包含。
@@ -0,0 +1,233 @@
+# 填好的手动闭环示例（虚构的 notes-web 项目）。历史轮次没有自动 launcher receipt；
+# 因此使用 manual 模式。可用 scripts/validate_tasks.py 校验通过。
+version: 1
+updatedAt: "2026-07-06T09:40:00+08:00"
+source: "Coordinator (PM) Agent"
+ackVersion: "0.11.0"
+project:
+  name: "notes-web"
+  repoPath: "/home/dev/notes-web"
+  baseUrl: "http://localhost:5173"
+  devWorktree: "/home/dev/notes-web-wt/fix-preview"
+  overlayFile: "docs/ack/project.md"
+  knowledgeFile: "docs/ack/knowledge.yaml"
+  deliveryFile: "docs/ack/delivery.yaml"
+  orchestration:
+    profileVersion: 1
+    mode: "manual"
+    allowedWorktrees:
+      - "/home/dev/notes-web-wt/fix-preview"
+    modelAllowlist:
+      codex:
+        developer:
+          standard: ["gpt-5.6-terra"]
+          strong: ["gpt-5.6-sol"]
+        test:
+          standard: ["gpt-5.6-luna"]
+      cursor-agent:
+        developer:
+          standard: ["auto"]
+        test:
+          standard: ["auto"]
+    profiles:
+      codex-dev-standard:
+        role: "developer"
+        cli: "codex"
+        tier: "standard"
+        model: "gpt-5.6-terra"
+        reasoningEffort: "medium"
+        permissionMode: "workspace-write"
+      codex-test-standard:
+        role: "test"
+        cli: "codex"
+        tier: "standard"
+        model: "gpt-5.6-luna"
+        reasoningEffort: "low"
+        permissionMode: "workspace-write"
+      codex-dev-strong:
+        role: "developer"
+        cli: "codex"
+        tier: "strong"
+        model: "gpt-5.6-sol"
+        reasoningEffort: "high"
+        permissionMode: "workspace-write"
+      cursor-dev-standard:
+        role: "developer"
+        cli: "cursor-agent"
+        tier: "standard"
+        model: "auto"
+        reasoningEffort: null
+        permissionMode: "workspace-write"
+      cursor-test-standard:
+        role: "test"
+        cli: "cursor-agent"
+        tier: "standard"
+        model: "auto"
+        reasoningEffort: null
+        permissionMode: "workspace-write"
+    defaults:
+      developer: "codex-dev-standard"
+      test: "codex-test-standard"
+      developerUpgraded: "codex-dev-strong"
+
+workerReceipts: []
+deliveryRuns: []
+
+summary:
+  verified: ["BUG-002"]
+  open: []
+  failedRetest: []
+  leftovers: ["BUG-003"]
+
+tasks:
+  - id: "BUG-002"
+    type: "bug"
+    title: "预览变更点击后不显示 diff 行"
+    priority: "P0"
+    status: "verified"
+    assignee: "developer"
+    component: "web/app/fix/page.tsx"
+    specRefs:
+      - "docs/spec/fix-preview.md#preview"
+    testRefs:
+      - "tests/browser/cases/01-preview.md"
+    knowledgeRefs:
+      - "K-001@1"
+    knowledgeApplied:
+      - ref: "K-001@1"
+        result: "applied"
+        evidence: "重启服务并核对 commit 后再交给 Test"
+    knowledgeCandidates: []
+    knowledgeChecks:
+      - ref: "K-001@1"
+        result: "passed"
+        evidence: "服务实例、worktree 与 commit 9f8e7d6 一致"
+        checkedBy: "test-worker-1"
+        checkedAt: "2026-07-06T09:36:00+08:00"
+    description: >
+      用户在 /fix 页点击“预览变更”后，确认区不渲染 API 返回的 diff。
+    stepsToReproduce:
+      - "打开 /fix?fileId=1"
+      - "搜索并选择候选项"
+      - "点击“预览变更”"
+    expected: >
+      确认区出现 title、修改前值、修改后值、coverChanged 提示四行。
+    actual: >
+      API 返回 code=0，但页面确认区为空。
+    evidence:
+      browser: "确认区 DOM 为空，无 diff 行"
+      api: "POST /api/fix/preview -> code=0, 含 diff 字段"
+      logs: "无报错"
+    verification:
+      commands:
+        - "npm run build"
+        - "curl -s -X POST localhost:5173/api/fix/preview -d @fixtures/preview.json"
+      browser:
+        page: "/fix?fileId=1"
+        checks:
+          - "预览后出现 4 行 diff：title/before/after/coverChanged"
+    dispatch:
+      developer:
+        profileId: "codex-dev-standard"
+        receiptId: null
+        attemptId: null
+        taskId: null
+        dispatchId: null
+      test:
+        profileId: "codex-test-standard"
+        receiptId: null
+        attemptId: null
+        taskId: null
+        dispatchId: null
+      rounds:
+        - round: 1
+          attemptId: "BUG-002-A1"
+          result: failed
+          evidence: "只渲染了 title，缺少 before/after/coverChanged"
+        - round: 2
+          attemptId: "BUG-002-A2"
+          result: passed
+          evidence: "复测 4 行 diff 全部出现，取消不触发写入"
+    resolution:
+      fixedBy: "dev-worker-1"
+      verifiedBy: "test-worker-1"
+      verifiedAt: "2026-07-06T09:38:00+08:00"
+      leftoverReason: null
+
+  - id: "BUG-003"
+    type: "bug"
+    title: "并发保存偶发覆盖他人修改"
+    priority: "P1"
+    status: "leftover"
+    assignee: "developer"
+    component: "server/store/notes.go"
+    specRefs:
+      - "docs/spec/concurrency.md"
+    testRefs: []
+    knowledgeRefs: []
+    knowledgeApplied: []
+    knowledgeCandidates:
+      - kind: "pitfall"
+        title: "乐观锁检查必须覆盖批量导入路径"
+        claim: "只在 API 写入路径检查版本号会漏掉批量导入"
+        scope:
+          components: ["server-store"]
+          paths: ["server/store/**"]
+          tags: ["concurrency"]
+        appliesWhen: "修改 note 的并发写入或批量导入逻辑"
+        directive: "同时验证 API 与批量导入的版本冲突处理"
+        rationale: "第二轮修复只覆盖 API，批量导入仍可静默覆盖"
+        evidenceRefs:
+          - "tasks.yaml#BUG-003-round-2"
+        proposedBy: "test-worker-1"
+        proposedAt: "2026-07-06T09:32:00+08:00"
+    knowledgeChecks: []
+    description: >
+      两个会话同时保存同一条 note 时，后写覆盖先写，无冲突提示。
+    stepsToReproduce:
+      - "会话 A、B 同时打开 note 42"
+      - "A 保存，B 保存"
+    expected: >
+      B 保存时应检测到版本变化并提示冲突，而非静默覆盖。
+    actual: >
+      B 直接覆盖 A 的修改，无提示。
+    evidence:
+      api: "两次 PUT /api/notes/42 均返回 200，无版本校验"
+    verification:
+      commands:
+        - "go test ./server/store/..."
+      browser:
+        page: "/notes/42"
+        checks:
+          - "并发保存时后写方收到冲突提示"
+    dispatch:
+      developer:
+        profileId: "codex-dev-standard"
+        receiptId: null
+        attemptId: null
+        taskId: null
+        dispatchId: null
+      test:
+        profileId: "codex-test-standard"
+        receiptId: null
+        attemptId: null
+        taskId: null
+        dispatchId: null
+      rounds:
+        - round: 1
+          attemptId: "BUG-003-A1"
+          result: failed
+          evidence: "加了版本号但未在写入路径校验"
+        - round: 2
+          attemptId: "BUG-003-A2"
+          result: failed
+          evidence: "校验只覆盖 API，未覆盖批量导入路径"
+        - round: 3
+          attemptId: "BUG-003-A3"
+          result: failed
+          evidence: "乐观锁与前端重试逻辑冲突，需重新设计"
+    resolution:
+      fixedBy: null
+      verifiedBy: null
+      verifiedAt: null
+      leftoverReason: "failed after 3 supervised developer rounds; 需重新设计并发模型"
@@ -0,0 +1,122 @@
+# ACK 接入清单
+
+## 安装与初始化
+
+- [ ] ACK Skill 已全局安装或安装到当前项目。
+- [ ] 已运行 `skiff init ack --project <project-root>`。
+- [ ] `docs/ack/` 只包含项目自己的 `project.md`、`tasks.yaml`、`knowledge.yaml` 与
+      默认关闭的 `delivery.yaml`。
+- [ ] 旧项目缺少 `knowledge.yaml` 时，只补空文件及缺失的
+      `project.knowledgeFile` 指针，没有重跑初始化或覆盖其它项目状态。
+- [ ] 项目中没有 ACK Skill 的复制目录或 `kit`、`framework` 软链接。
+- [ ] `tasks.yaml` 使用 `ackVersion` 记录 ACK Skill 版本。
+
+## 项目覆盖层
+
+- [ ] `project.md` 只保存项目差异，不复制 Skill 的通用规范。
+- [ ] `tasks.yaml` 的 `project.overlayFile` 指向实际覆盖层。
+- [ ] `tasks.yaml` 的 `project.knowledgeFile` 固定为
+      `docs/ack/knowledge.yaml`。
+- [ ] 新项目的 `project.deliveryFile` 固定为 `docs/ack/delivery.yaml`，顶层有
+      `deliveryRuns: []`；旧项目未采用交付能力时可无这两项。
+- [ ] 技术栈、运行、构建、单测和集成测试命令均来自项目证据。
+- [ ] Coordinator、Developer、Test 的模型档位和升级规则已明确。
+- [ ] `project.orchestration` 使用受支持的 profileVersion，模型都命中项目
+      allowlist，默认 profile 与角色/档位一致。
+- [ ] 需要一次性交付路由时存在 `defaults.operator`；其 CLI、standard 模型和
+      reasoning effort 与 `defaults.test` 完全相同。
+- [ ] `allowedWorktrees` 只列出同一 Git common-dir 下已经核对的绝对 worktree。
+
+## 路径权限
+
+- [ ] Coordinator 可写规格和任务板。
+- [ ] Test 可写集成测试与复测记录，但不能改源码。
+- [ ] Developer 可写源码与单元测试，但不能改规格或黑盒验收。
+- [ ] 私有配置只读且不提交。
+- [ ] `tasks.yaml` 只有 Coordinator 写。
+- [ ] `knowledge.yaml` 只有 Coordinator 写；Developer 与 Test 只通过回报提名或验证。
+- [ ] `delivery.yaml` 只在用户显式维护配置时修改；Developer 与 Test 只读。
+- [ ] Operator 只回传一次性交付证据，不写 ACK 项目状态文件。
+
+## 任务板
+
+- [ ] 已替换项目名、仓库路径、Base URL、worktree 和覆盖层路径。
+- [ ] 没有真实任务时使用 `tasks: []`。
+- [ ] 真实任务的验收是可观测信号。
+- [ ] 已运行 `<ack-skill-dir>/scripts/validate_tasks.py` 并通过。
+
+## 可选交付
+
+- [ ] `delivery.yaml` 首次生成保持 `enabled: false`，没有根据 README/CI 自动启用。
+- [ ] entrypoint 只使用声明式工具 target 或仓库内无 symlink 的可执行脚本；没有
+      shell、自由 command、凭据值或环境变量值。
+- [ ] artifact、destination、environment 和 profile 引用均通过
+      `validate_delivery.py --tasks ... --project-root ...` 校验。
+- [ ] 默认 profile 只使用 preview/staging 与非 production 环境，停止在
+      `review_ready`。
+- [ ] stable 发布和 production 部署之前存在 approval 步骤；production 环境有
+      rollback 入口。
+- [ ] 本次 ACK 计划明确 profile、task IDs、目标、停止点和审批步骤；配置本身没有
+      被当作提交、推送、发布或部署授权。
+- [ ] 每次运行固定 commit/config revision，证据写入 `tasks.yaml.deliveryRuns`；
+      失败不会把已验证任务回退为失败。
+
+## 可选一次性交付路由
+
+- [ ] PR/MR 与源码发布、DEB、Docker 镜像分别路由到 `manage-release`、
+      `deb-publisher`、`publish-docker-image`；普通 PR/MR 只使用 `PR-only`，没有扩大
+      到版本升级、合并、tag 或 Forge Release。
+- [ ] `delivery-operation.operation.request` 保留用户原始请求，没有扩大授权。
+- [ ] Operator 使用 `launch_worker.py --role operator` 创建的 fresh worker，没有复用
+      Test terminal，也没有让 Coordinator 代跑。
+- [ ] 部分成功或外部状态不确定时按低层 Skill 恢复，没有盲目自动重试。
+
+## 项目知识
+
+- [ ] 新项目没有已验证知识时使用 `verificationRegistry: {}` 与 `entries: []`，
+      不虚构 active 条目。
+- [ ] 已运行 `<ack-skill-dir>/scripts/validate_knowledge.py` 并通过；同时校验任务引用。
+- [ ] Coordinator 只从 `active` 条目按 scope 推荐知识，并显式确认固定 revision 的
+      `knowledgeRefs`。
+- [ ] `candidate` 留在任务证据中，不派发；`stale`、`superseded`、`archived`
+      不默认选择。
+- [ ] 每轮只内联命中的少量知识，不全量注入 `knowledge.yaml`。
+- [ ] Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
+      `knowledgeChecks`。
+- [ ] `verification.ref` 只引用 `verificationRegistry` 中已审查的仓库内相对 path
+      和结构化 args；执行时只把 registry ID 交给 `run_verification.py`，不从
+      知识正文或选择器输出拼接 shell。
+- [ ] 关键约束已规划下沉到测试、lint、CI 或正式规范。
+- [ ] ACK 不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+
+## 编排
+
+- [ ] 已选择 Orca 或手动模式。
+- [ ] 自动创建只调用 `launch_worker.py plan|launch`，没有直接拼接
+      `orca terminal create --command` 或自由 worker 命令。
+- [ ] `launch` 使用刚审阅的 `plan.launchFingerprint` 作为
+      `--expected-launch-fingerprint`；漂移时重新 plan。
+- [ ] Developer/Test/Operator 只使用 `read-only` 或 `workspace-write` profile；
+      v0.10 没有 full-access、bypass、YOLO/force 或关闭 sandbox。
+- [ ] v0.10 每次自动派发都启动 fresh worker；没有把历史 receipt checksum 或
+      Orca live metadata 当作自动复用授权。
+- [ ] launcher receipt 已追加到顶层 `workerReceipts`，任务分别引用
+      `dispatch.developer` 与 `dispatch.test`；每个引用的 task/role/profile/attempt
+      都与当前任务、本轮 receipt 完全一致，没有用单一 handle 混淆两个角色。
+- [ ] 一次性交付 receipt 引用 `dispatch.operator`，与当前操作、profile 和 attempt
+      完全一致。
+- [ ] 多 worktree 场景只有一个权威 `tasks.yaml` 和 `knowledge.yaml`。
+- [ ] Test 使用的服务来自正确 worktree。
+
+## 闭环
+
+- [ ] `worker_done` 不直接视为完成。
+- [ ] Test 独立复测后由 Coordinator 读取证据终检。
+- [ ] 每轮写入 `dispatch.rounds`。
+- [ ] 三轮失败后标记 `leftover` 并填写原因。
+- [ ] `leftover` 不阻塞其它任务。
+
+首次接入建议选择一个低风险问题跑完整闭环。项目差异写回
+`docs/ack/project.md`；通用问题回流到 ACK Skill 的 `references/`、`templates/`
+或 `scripts/`，并更新 `VERSION`。项目特有、跨任务复用且已经验证的经验才写入
+`docs/ack/knowledge.yaml`。
@@ -0,0 +1,299 @@
+# 闭环流程（稳定核心，编排无关）
+
+本文件定义**与具体编排工具无关**的三角色协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。
+
+原则：调度消息只是运行时载体，任务结论必须回写到 `tasks.yaml`；已经验证且可跨
+任务使用的项目经验必须由 Coordinator 回写到 `knowledge.yaml`。不要把消息当最终记录。
+角色定义见 `roles-and-permissions.md`：Coordinator 只编排、Test 只验证、
+Developer 只实现。
+
+---
+
+## 编排抽象
+
+无论用什么工具，闭环都由这几个能力组成。注意 `dispatch` 有两个目标（Developer 与 Test）：
+
+| 抽象动作 | 含义 | Orca 实现 | 手动实现 |
+|----------|------|-----------|----------|
+| `prepare(task)` | Coordinator 把任务和验收信号写进 `tasks.yaml`，按 scope 推荐知识并确认显式 `knowledgeRefs` | 同左 | 同左 |
+| `dispatch(task, developer)` | 把修复任务连同上下文交给 Developer | `orca orchestration dispatch` | 复制 prompt 到 Developer 终端/会话 |
+| `dispatch(task, test)` | 把复测任务连同验收信号交给 Test | `orca orchestration dispatch` | 复制 prompt 到 Test 终端/会话 |
+| `wait()` | 等待 `worker_done` / `retest_result` / `escalation` / `decision_gate` | `orca orchestration check --wait` | 人工等待回报 |
+| `gate(task)` | Coordinator 读 Test 证据、`knowledgeChecks` 并对齐原始意图（不重测） | 同左 | 同左 |
+| `writeback(task, result)` | Coordinator 把任务结果写回 `tasks.yaml`，把验证通过的跨任务经验按权限写入 `knowledge.yaml` | 同左 | 同左 |
+
+派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。**独立复测由 Test 执行，不是 Coordinator**；Coordinator 只做读证据的终检。
+
+---
+
+## 标准闭环
+
+```text
+Coordinator 发现或读取 open 任务
+  -> prepare：写/补全 tasks.yaml 验收信号
+  -> 从 knowledge.yaml 按 scope 推荐 active 知识，Coordinator 确认固定 revision 的 knowledgeRefs
+  -> 为新轮次生成稳定 attemptId（<task-id>-A<round>），Developer 与 Test 共用
+  -> 决定 worktree：当前 worktree 起子 agent，还是新建隔离 worktree（见下节「子任务放哪」）
+  -> 解析安全 profile：机器配置只读 tasks.yaml.project.orchestration
+  -> 运行 launcher plan 并审阅 launchFingerprint
+  -> 带 expected fingerprint 启动 fresh worker，把 receipt 写回 tasks.yaml（见 orca-adapter.md）
+  -> dispatch 给 Developer（--to <worker handle>）
+  -> wait：Developer 的 worker_done / escalation（含 knowledgeApplied / knowledgeCandidates）
+  -> writeback fixed_by_dev
+  -> 为 Test 独立解析安全 profile，重新 plan/launch fresh worker 并写回 receipt
+  -> dispatch 给 Test（retesting）
+  -> wait：Test 的 retest_result（含 knowledgeChecks 和 candidate 独立证据）
+  -> Test 通过：gate（Coordinator 读证据对齐意图）
+        -> 通过 gate：writeback verified
+        -> gate 不满足意图：writeback failed_retest，带意图差异再派发 Developer
+  -> Test 失败：writeback failed_retest，追加证据，再派发 Developer（最多累计三轮）
+  -> 累计三轮失败：writeback leftover，继续下一个任务
+```
+
+一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。
+「决定 worktree」「解析 profile/receipt」几步的决策见下节与 `model-routing.md` /
+`orca-adapter.md`。v0.10 不自动复用历史 receipt 或既有终端；标题、preview、分支名、
+worker 自报和无密钥 receipt checksum 都不能代替可信启动 attestation。
+Coordinator 默认给新逻辑轮次生成 `<task-id>-A<round>`，并在记录轮次结果时写入
+`tasks[].dispatch.rounds[].attemptId`。它独立于编排工具产生的 `taskId` 和
+`dispatchId`：前者用于知识来源追溯，后两者只用于查询运行时。0.9.0 之前的历史
+轮次允许暂时缺省；但要把该轮证据晋升为知识前，必须按确定性格式补齐。晋升时，
+`provenance.taskId` 和 `provenance.attemptId` 必须能精确回到该任务及轮次。
+
+### 知识选择与晋升
+
+`prepare(task)` 时可以使用 Skill 自带的 `scripts/select_knowledge.py` 按
+component、path、dependency、version 和 tag 确定性推荐条目。选择器只返回
+`active`，并受条目数限制；`stale`、`superseded` 和 `archived` 不默认派发。自动
+匹配只是推荐。条目中每个非空 scope 维度都必须被任务上下文命中，因此调用时应
+提供当前任务已知的全部 component、path、dependency、version、tag、symbol 和错误
+特征。Coordinator 确认并写入当前任务的显式 `knowledgeRefs` 后才成为本轮权威
+上下文。
+
+`scope.paths` 使用 POSIX 路径 glob：`*` 不跨目录分隔符，`**` 才能跨目录。多个
+pattern 是同一维度内的 OR，候选越多表示范围越宽；超过选择预算时，选择器优先保留
+命中维度更多、OR 候选更少、字面约束更多且通配符更少的条目。
+
+派发时只内联本轮引用的少量知识，不要求 worker 全量读取 `knowledge.yaml`。这也
+避免隔离 worktree 读不到 Coordinator 工作树中尚未提交的项目状态。
+
+进行中的任务只能引用 `active` 条目。已经进入 `verified` 或 `leftover` 的终态任务
+可以继续保留固定 revision 的历史引用，即使对应知识后来变成 `stale`、
+`superseded` 或 `archived`；这些旧条目不会再次被选择器派发。
+
+Developer 或 Test 发现经验时只能通过 `knowledgeCandidates` 提名，并带上当前任务
+的独立观测、scope、触发条件和证据。candidate 留在任务证据中，不进入知识选择器，
+也不能被下一轮当作 active 指令。只有 Test 独立验证、Coordinator gate 通过后，
+Coordinator 才能写入或更新 `knowledge.yaml`；全项目强制或权限类规则还需
+User / Decision Owner 确认。
+
+Test 对显式引用回报 `not_applicable` 时，说明 Coordinator 的选择需要纠正。该引用
+仍在 `knowledgeRefs` 中就不能把任务标为 `verified`；Coordinator 应记录原因、移除
+误选引用并重新校验，或继续补充验证。
+
+知识中的 `verification.ref` 只能引用
+`knowledge.yaml.verificationRegistry` 里已审查的仓库内相对 path 和结构化 args，
+不能从知识正文拼接或执行自由 shell。Developer/Test 只把 `verification.ref` 交给
+`<ack-skill-dir>/scripts/run_verification.py`；该入口从项目根目录逐段安全打开检查
+文件，拒绝 symlink 路径，并从匿名稳定快照执行。关键约束应下沉为测试、lint、CI
+或正式规范。检查进程从固定的项目根 fd cwd 运行；检查脚本应使用 cwd 或
+`ACK_PROJECT_ROOT` 定位资源。后者是 fd 路径，原始展示路径只在
+`ACK_PROJECT_ROOT_DISPLAY` 中用于日志；不能依赖 `$0` / `__file__` 的目录。
+
+---
+
+## 子任务放哪：新 worktree 还是当前 worktree
+
+Coordinator 派发前先决定 Developer/Test 在哪工作。两种方式：
+
+**方式 1：当前 worktree 起 fresh 子 agent（终端）**
+
+```bash
+# v0.10 不自动复用既有终端；先审阅 plan：
+python3 <ack-skill-dir>/scripts/launch_worker.py plan \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test> \
+  --profile-id <profile-id> --worktree <absolute-current-worktree> --slot <1..99>
+python3 <ack-skill-dir>/scripts/launch_worker.py launch \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test> \
+  --profile-id <profile-id> --worktree <absolute-current-worktree> --slot <1..99> \
+  --expected-launch-fingerprint <plan 中的 sha256:...>
+```
+
+- 适合：串行闭环、一次一个 Developer 任务、小改动、Test 要复测的正是 Developer 改的那棵树。
+- 优点：单一服务实例、无跨 worktree 对齐困扰、开销小。
+- 风险：多个 agent 同时改同一棵树会互相踩（半构建状态、git 冲突）。
+- 记录：`launch` 成功后把 receipt 追加到权威 `tasks.yaml.workerReceipts`，并把
+  `receipt.id` 写入 `dispatch.<role>.receiptId`、把 `profileId` 写入
+  `dispatch.<role>.profileId`、把本轮稳定 ID 写入 `dispatch.<role>.attemptId`；
+  receipt 的 task/role/profile/attempt 必须与当前 dispatch 完全一致，不能只记录
+  一个裸 handle，也不能引用旧任务或旧轮次 receipt。
+
+**方式 2：新建隔离 worktree，再在其中起子 agent**
+
+创建成功后，先把 Orca 返回的绝对路径加入权威任务板的
+`project.orchestration.allowedWorktrees` 并重新运行 `validate_tasks.py`；未进入
+allowlist 的路径不能交给 launcher。
+
+```bash
+orca worktree create --name <feature> --base-branch <base> --json
+# 对返回的绝对路径调用 ACK launcher
+python3 <ack-skill-dir>/scripts/launch_worker.py plan \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test> \
+  --profile-id <profile-id> --worktree <absolute-new-worktree> --slot <1..99>
+python3 <ack-skill-dir>/scripts/launch_worker.py launch \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test> \
+  --profile-id <profile-id> --worktree <absolute-new-worktree> --slot <1..99> \
+  --expected-launch-fingerprint <plan 中的 sha256:...>
+```
+
+- 适合：并行多个互不依赖的子任务、大/高风险/实验性改动、要保持基线分支干净（如 prod 不动、feature 走独立分支）、要独立 build 或跑独立服务实例、best-of-N 尝试。
+- 优点：隔离 + 并行 + 易回滚（删 worktree 即可）。
+- 成本：各自 build/依赖、服务要用不同端口、必须处理下节的 worktree/服务对齐。
+
+**决策速查：**
+
+| 情况 | 选择 |
+|------|------|
+| 一次一个任务、串行修复 | 当前 worktree 子 agent |
+| 多个任务并行、互不依赖 | 每个任务一个新 worktree |
+| 高风险 / 实验 / 可能整体丢弃 | 新 worktree |
+| 要保持基线分支干净 | 新 worktree（feature 分支）|
+| 小改动、追求快 | 当前 worktree |
+
+**项目状态（SSOT）只落一处**：无论开几个 worktree，`tasks.yaml`、
+`knowledge.yaml` 和可选 `delivery.yaml` 都只认一个权威副本（通常在基线/协调所在
+worktree）。Coordinator 单写任务、知识与 `deliveryRuns`；交付能力只在显式配置维护
+时修改。`project.orchestration`、顶层 `workerReceipts` 和任务 dispatch 也只写入这个
+副本；不要每个 worktree 各留一份会分叉的项目状态。profile 解析、launcher 与
+receipt 规则见 `model-routing.md` 和 `orca-adapter.md`。
+
+两种 worktree 方式都只允许 profile 中的 `read-only` / `workspace-write` 安全权限。
+v0.10 的 full-access 授权与撤销机制仍是 Deferred；launcher 遇到 full-access 或等价
+的 sandbox 绕过请求必须 fail closed。
+
+---
+
+## 手动模式（无 Orca）
+
+没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：
+
+1. Coordinator 在 `tasks.yaml` 写好任务和验收信号。
+2. 从 `knowledge.yaml` 推荐相关 active 知识，Coordinator 确认固定 revision 的
+   `knowledgeRefs`；用 `prompt-templates.md` §1 的初始派发模板生成 prompt，
+   手动发给 Developer（另一个会话/终端/人）。
+3. Developer 完成后按 worker_done 模板回报。
+4. Coordinator 写回 `fixed_by_dev`，用 `prompt-templates.md` §3 的复测派发模板把任务发给 Test。
+5. Test 独立复测后按复测报告模板回报证据和 `knowledgeChecks`。
+6. Coordinator 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。
+7. 失败则用「复测失败再派发模板」重新发给 Developer，最多累计三轮。
+
+手动模式下同样遵守：worker_done / 复测报告都不等于最终结论、只有 Coordinator
+写 `tasks.yaml` 和 `knowledge.yaml`、三轮失败留档。若本次确认计划还包含交付，所有
+选中任务 `verified` 后由 Coordinator 继续按 `delivery.md` 执行并写 `deliveryRuns`。
+
+手动交给用户已打开的会话不等于产生 ACK receipt。该会话可以完成本次显式 handoff，
+但不能因此进入 Orca 自动派发信任路径；后续自动派发仍需重新通过 ACK launcher
+创建 fresh worker。
+
+---
+
+## Test 复测（编排无关）
+
+即使 Developer 的 worker_done 写了"全部通过"，Test 仍必须独立复测：
+
+```bash
+git status --short
+<test_commands>
+curl -s <base_url>/health-or-summary
+```
+
+浏览器复测建议记录：
+
+```text
+BASE_URL:
+page:
+steps:
+expected:
+actual:
+snapshot evidence:
+```
+
+Test 只回传证据，不写 `tasks.yaml` 或 `knowledge.yaml`；由 Coordinator 落盘。
+每条适用的显式 `knowledgeRef` 还应报告 `passed`、`failed` 或
+`not_applicable` 及证据。
+
+---
+
+## Coordinator 终检（gate）
+
+Test 报通过后，Coordinator 不重测，而是做一次读证据的终检：
+
+- Test 证据是否覆盖了任务的**每一条**验收信号（见 `optimization-method.md` §1）。
+- 当前任务显式 `knowledgeRefs` 的必需 `knowledgeChecks` 是否全部覆盖，检查引用
+  是否能解析到项目已审查的入口。
+- 结果是否符合任务的**原始意图**，而不只是通过了字面文案。
+- 运行环境是否对齐（见下方「服务与 worktree 对齐」）。
+
+终检不通过（例如意图漂移、验收信号写漏）时，回写 `failed_retest` 并把意图差异带给下一轮 Developer，必要时先补全验收信号。
+
+---
+
+## 服务与 worktree 对齐（防假通过/假失败）
+
+Test 复测前记录运行环境：
+
+```bash
+pwd
+git rev-parse --abbrev-ref HEAD
+git rev-parse --short HEAD
+```
+
+```text
+serverPid:
+serverCommand:
+BASE_URL:
+frontendDir:
+worktreePath:
+```
+
+如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须**停止并重启正确服务**后再测。长跑服务或静态前端尤其要确认加载的是最新构建产物。
+
+---
+
+## 结果回写
+
+Coordinator 回写 `tasks.yaml` 时按状态填写（字段结构见 `templates/tasks.schema.json`）：
+
+```yaml
+# 通过（Test 复测 + Coordinator 终检）
+status: verified
+resolution:
+  verifiedAt: "<timestamp>"
+  verifiedBy: "test"
+  evidence:
+    verification: "<commands passed>"
+    browser: "<snapshot or API evidence>"
+```
+
+```yaml
+# 失败但未满三轮
+status: failed_retest
+dispatch:
+  rounds:
+    - round: 1
+      result: failed
+      evidence: "<latest evidence from Test or gate>"
+```
+
+```yaml
+# 累计三轮失败
+status: leftover
+resolution:
+  leftoverReason: "failed after 3 supervised developer rounds"
+  evidence:
+    final: "<latest failing evidence>"
+```
@@ -0,0 +1,108 @@
+# ACK 一次性交付路由
+
+本文件定义用户显式调用 `$ack` 后，直接要求创建发布相关 PR/MR、发布源码版本、
+上传 DEB 或发布 Docker 镜像时的路由。它不要求先跑 Developer → Test 闭环，也不读取
+或修改 `delivery.yaml`；项目已有的“verified 后按 profile 交付”仍按 `delivery.md`
+执行。
+
+## 1. 只按用户目标选择能力
+
+| 用户目标 | 路由 | 不得顺带执行 |
+| --- | --- | --- |
+| 创建普通或发布 PR/MR，以及版本号、release/hotfix 分支、合并、正式 tag、Forge Release、恢复中断的源码发布 | `manage-release` | 未请求的版本升级、合并、tag、Forge Release、清理、普通产物上传 |
+| 构建、检查、上传 `.deb`，发布到 APT/DEB 仓库 | `deb-publisher` | tag、Forge Release、Docker 镜像 |
+| 构建并推送 Docker/OCI 镜像到 registry | `publish-docker-image` | 源码版本、DEB、额外 tag；用户说的 `docker-publisher` 视为这个已安装 Skill 的别名 |
+
+“创建 PR/MR”路由到 `manage-release`，但必须区分权限上限：发布版本、release/hotfix
+分支或版本升级对应的 PR/MR 走发布流程；普通 PR/MR 只走它的 ACK `PR-only` 入口，
+不得推断版本升级、release 分支、合并、tag 或 Forge Release。ACK 功能任务在 verified
+后按 profile 自动开 PR 时，仍使用 `delivery.md` 的 `pull-request` 动作，不重复建立
+一次性操作。
+
+只说“发布一下”时先从用户文字和项目发布入口判断目标。DEB、镜像和源码发布仍有两个
+以上合理候选时，先问一个最小澄清问题；不要根据最近文件或历史命令猜。用户明确要求
+多个产物时，为每个能力建立独立操作，按用户给出的顺序执行，不能由一个 Skill 暗中
+扩大到另一个 Skill。
+
+## 2. 用低成本 Operator 派发
+
+一次性交付由 `operator` worker 执行，Coordinator 不亲自运行低层 Skill。机器事实仍
+只读 `docs/ack/tasks.yaml.project.orchestration`：
+
+- `defaults.operator` 必须指向 `role: operator`、`tier: standard` 的 profile。
+- Operator 默认 profile 的 `cli`、`tier`、`model` 和 `reasoningEffort` 必须与
+  `defaults.test` 完全相同；校验器会拒绝漂移。`permissionMode` 仍按项目需要显式写
+  `read-only` 或 `workspace-write`，发布通常需要后者。
+- 旧项目没有 `defaults.operator` 时，普通 ACK 闭环仍可运行，但一次性交付路由必须
+  fail closed。先按当前模板补 operator allowlist/profile/default 并校验，不能临时猜
+  模型或让 Coordinator 代跑。
+- launcher 只给 Operator 固定的发布凭据 allowlist：`DEB_SERVER_URL`、`DEB_TOKEN`、
+  `DEB_REPOSITORY`、`DEB_UPLOAD_PATH` 和 `SSH_AUTH_SOCK`；Docker/Forge 使用 HOME
+  中自己的凭据存储。值不写入任务板或 receipt。缺少凭据时由低层 Skill 标记 blocked，
+  不通过 prompt、自由 env 或命令行注入秘密。
+
+路由后在权威任务板新增一条最小记录：
+
+```yaml
+- id: "DELIVERY-001"
+  type: "delivery-operation"
+  title: "publish one DEB"
+  status: "open"
+  operation:
+    skill: "deb-publisher"
+    request: "<保留用户本次请求的授权语义；凭据值必须替换为 [REDACTED]>"
+  dispatch:
+    operator:
+      profileId: "<defaults.operator>"
+      receiptId: null
+      attemptId: null
+      taskId: null
+      dispatchId: null
+    rounds: []
+```
+
+运行 `validate_tasks.py` 后，用 `launch_worker.py plan|launch` 创建 fresh worker，参数
+使用 `--role operator`、本操作 ID 和 `<operation-id>-A1`。审阅 fingerprint，成功后
+把 receipt 写入 `workerReceipts` 并与 `dispatch.operator` 精确绑定，再投递下节的
+prompt。Orca 模式按 `orca-adapter.md` 登记单一操作任务，并把 runtime task/dispatch
+ID 写入 `dispatch.operator`；不创建 Developer/Test 子任务链。不得复用 Test terminal；
+“同模型档位”不等于“同角色或同 worker”。
+
+## 3. Operator 派发 Prompt
+
+```text
+你是 ACK 一次性交付 Operator。请在 <worktree> 执行以下原始请求：
+<operation.request>
+
+ACK 已选择且只授权你加载：$<operation.skill>
+先完整读取该 Skill 及它要求的 references，再读取可信 base 上的项目发布规则。
+
+边界：
+- 原始请求是授权上限；除已脱敏的凭据值外保持原意，不得因 ACK 路由、项目配置或
+  历史操作扩大远端写权限。
+- 严格遵守低层 Skill 的确认点、硬停止条件、恢复流程和完成标准。
+- 不修改 docs/ack/tasks.yaml、knowledge.yaml 或 delivery.yaml。
+- 不把 token、密码、私钥路径或认证配置写入消息、文件、提交或日志。
+- 发生部分成功或外部状态不确定时停止自动重试，先按低层 Skill 核对真实状态。
+
+完成或阻塞后只回传：所选 Skill、实际执行到的阶段、准确目标、非敏感证据、
+未完成项和安全恢复动作。不要把命令已运行等同于发布已验证。
+```
+
+## 4. 状态与完成
+
+Coordinator 在派发后把操作标为 `dispatched`，只读 Operator 的结构化证据做终检：
+
+- `manage-release` 必须按其完成标准证明 PR/MR、merged commit、远端 tag 或 Forge
+  Release 中用户实际要求的最远阶段。
+- `deb-publisher` 必须分别证明包元数据/摘要、上传接受和仓库可见性。
+- `publish-docker-image` 必须证明完整镜像引用、platform、源 commit 和远端 digest；
+  registry 无法查询时明确限制。
+
+证据满足原始请求才把操作标为 `verified`；安全停止但可恢复时标为 `blocked` 并记录
+恢复动作。`worker_done` 不等于完成。涉及远端写入的失败不自动进入第二轮；先由对应
+低层 Skill 执行真实状态发现和恢复，再由用户决定是否继续。
+
+Operator receipt 和操作证据写在该任务中，不写入 `deliveryRuns`。一次性交付不会因
+项目其它任务未 `verified` 而被拦截，也不会触发 `delivery.yaml` 的 profile；两种流程
+必须保持独立，避免同一请求被重复发布。
@@ -0,0 +1,127 @@
+# ACK 交付阶段
+
+本文件定义可选的 `verified -> review_ready/released` 交付阶段。开发、独立复测和
+Coordinator 终检仍由 ACK 原有闭环负责；只有选中的任务全部 `verified` 后才能进入
+交付。项目配置位于 `docs/ack/delivery.yaml`，运行证据写入
+`docs/ack/tasks.yaml.deliveryRuns`。
+
+## 1. 配置与授权不是一回事
+
+`delivery.yaml` 描述项目能怎样构建、上传和部署，不能单独授予远端写权限。ACK 在
+kickoff 的既有用户确认点同时展示本次 profile、remote、产物目标、环境和停止点；用户
+确认该任务计划后，才允许执行计划中准确列出的 `review_ready` 步骤。目标、remote、
+channel、environment 或 source revision 漂移时重新确认。
+
+`approval` 步骤始终是运行时硬门。`stable` 发布和 `production` 部署不能由 kickoff
+的一般确认代替，必须在该步骤取得本次明确授权。配置、历史 approval 或项目文档不能
+替用户授权合并 PR、创建正式 tag、覆盖版本、删除分支或生产发布。
+
+## 2. 配置快照与变更生效
+
+普通任务在 kickoff 时从可信 base commit 读取交付契约并记录 `configRevision`。本次
+分支对 `delivery.yaml`、引用的部署入口、CI 或 Agent 指令文件的修改不能扩大当前运行
+权限；这些改动经审核合并后从下一次任务生效。
+
+用户明确要求维护交付配置时：
+
+1. 读取现有配置、项目构建入口、CI、打包和部署事实。
+2. 用自然语言总结将新增、删除或改变的 artifact、destination、environment、profile
+   和权限边界。
+3. 只做最小配置修改，不把项目脚本复制进 ACK。
+4. 运行 `validate_delivery.py`；可安全执行的本地入口使用 dry-run 或无凭据环境检查。
+5. 把配置或入口变更作为待审核变更交付。本轮不使用新配置执行 publish/deploy。
+
+普通功能任务中若发现配置漂移，记录 `contract_drift` 并停止受影响的交付步骤，不为了
+通过流程而静默修改配置或跳过步骤。
+
+## 3. 交付契约结构
+
+- `entrypoints`：项目已有的 Make、Just、Task、Dagger 或仓库内可执行脚本入口。
+- `artifacts`：`deb`、`oci-image` 或 `file`，引用一个 build entrypoint。
+- `destinations`：APT、OCI registry 或 CI artifact；`channel` 区分 preview、staging、
+  stable。
+- `environments`：SSH host、Docker Compose、Kubernetes 或 custom；必须声明环境等级、
+  deploy 和 health check，production 还必须声明 rollback。
+- `profiles`：按顺序执行的步骤和停止点。默认 profile 必须停在 `review_ready`，不能
+  发布 stable 或部署 production。
+
+配置不允许 `shell`、自由 `command`、`env`、外部 executable、token、密码、私钥路径
+或凭据 URL。entrypoint 的 `requiredSecrets` 只能列大写 secret 名称，值必须由外部
+凭据系统或执行环境注入。复杂逻辑放在受版本控制的项目入口中。entrypoint 使用 argv
+语义执行，不能拼成 `sh -c` 字符串。
+
+## 4. 运行前检查
+
+1. 从 `tasks.yaml.project.deliveryFile` 解析文件；未引用或 `enabled=false` 时保持旧 ACK
+   行为，收尾停在 `verified`。
+2. 运行：
+
+   ```bash
+   python3 <ack-skill-dir>/scripts/validate_delivery.py \
+     docs/ack/delivery.yaml --tasks docs/ack/tasks.yaml \
+     --project-root <project-root>
+   ```
+
+3. 确认选中 profile 是 kickoff 已确认的 profile，所有 task 已是 `verified`，工作区与
+   服务对应正确 source revision。
+4. 检查 referenced entrypoint、delivery config、CI 和凭据边界是否在本次变更中被
+   修改；被修改时禁止用它们执行带远端写权限或 secret 的步骤。
+5. 检查本次步骤引用的 `requiredSecrets` 是否由外部环境提供，只报告名称和是否存在，
+   不读取、打印或持久化值。缺失时在第一次相关写操作前标记 blocked。
+6. 将已确认工作树固化为本地 source revision，再创建 `deliveryRuns` 的 `planned`
+   记录，绑定 task IDs、profile、source revision 和 config revision；推送仍等到对应
+   `pull-request` 步骤。
+
+## 5. 步骤语义
+
+按 profile 中的顺序执行，不自行插入或省略步骤：
+
+- `verify`：运行指定 entrypoint，失败即停止。
+- `pull-request`：在精确 source revision 上提交、推送任务分支并创建或复用 Draft
+  PR/MR。普通任务使用项目已确认的 Forge 流程；只有本次是版本发布生命周期且用户
+  明确要求时才调用独立的 `manage-release`。没有对应能力或认证时标记 blocked，不用
+  带 token 的临时 curl 兜底。remote 与 base branch 必须来自该步骤，不能临时猜测。
+- `build`：调用 artifact 的 build entrypoint。DEB 必须记录包名、版本、架构和
+  SHA-256；OCI image 必须记录完整引用、platform 和 digest。产物必须绑定当前 source
+  revision，不能在目标机器重新拉源码构建。
+- `publish`：验证 artifact/destination 类型兼容，上传精确产物。DEB 可使用已安装的
+  `deb-publisher`；Docker 只有在用户明确指定 `$publish-docker-image` 时才加载该
+  explicit-only skill，否则必须走契约中已审查的 upload entrypoint。项目入口只接受
+  刚校验的精确 artifact。preview/staging 使用不可覆盖的 commit/PR 标识，不隐式使用
+  `latest`。既没有可用 skill 也没有 upload 入口时标记 blocked。
+- `deploy`：把同一不可变 artifact 交给 environment 的 deploy entrypoint；获取目标
+  mutex 后执行，不能并发部署同一目标。
+- `health-check`：在对应 deploy 成功后运行环境 health check，记录可观测证据。失败时
+  按项目入口执行 rollback；rollback 未证明成功时不得声称恢复。
+- `approval`：停止并展示准确 artifact、destination/environment、source revision 和
+  回滚计划，等待用户本次确认。
+- `mark-ready`：所有前序步骤成功后将 Draft PR/MR 标为 ready，并写入最终证据。
+
+## 6. 状态与恢复
+
+`task.status=verified` 表示代码正确性通过；交付状态单独记录为 `planned`、`running`、
+`blocked`、`failed`、`review_ready`、`released` 或 `skipped`。部署或 Forge 暂时失败不把
+任务改回 `failed_retest`。
+
+重复运行先核对已有 branch、PR/MR、artifact 和部署目标，复用身份匹配的资源。相同
+ID 指向不同 commit、digest 或目标时停止，不覆盖或另建伪装成同一运行的资源。
+
+若恢复过程中修改了任何 tracked file，原 source revision 和交付证据失效：回到 ACK
+验证闭环，Test 重新复测后才能创建新的 delivery run。只有外部瞬时失败且 Git 内容未变
+时，才可从失败步骤继续。
+
+`review_ready` 至少记录：source/config revision、PR/MR URL、所有产物引用与 digest、
+部署环境和健康检查证据。最终回复分别报告代码验证、PR、产物、部署和未完成项，不能用
+“完成”掩盖其中某一阶段失败或待审批。
+
+## 7. 与低层 Skill 的边界
+
+ACK 只负责读取项目交付契约、编排顺序、守住审批点并汇总证据，不复制低层 skill 的
+上传、镜像或 Git 发布实现。`deb-publisher`、`publish-docker-image` 和
+`manage-release` 仍是可独立使用、独立安装的能力；缺失时 ACK 使用契约中已审查的
+项目 entrypoint，二者都不可用时把对应步骤标为 `blocked`。低层 skill 自身要求显式
+调用时，ACK 不能绕过它的触发与授权边界。
+
+用户显式调用 `$ack` 直接要求创建发布 PR/MR、发布源码版本、DEB 或镜像时，走
+`delivery-routing.md` 的一次性交付流程，不要求其它 ACK 任务先 `verified`，也不创建
+本文件定义的 `deliveryRuns`。两种流程不能在同一请求中隐式重复执行。
@@ -0,0 +1,164 @@
+# 在新项目初始化 ACK
+
+本文件说明如何把 ACK 的项目状态初始化到目标项目。ACK Skill 自身已经通过 Agent
+的 Skill 机制安装；项目不复制、不链接 Skill 内容。
+
+## 前提与边界
+
+开始前确认：
+
+1. 目标项目根目录。
+2. ACK Skill 已全局安装或安装到当前项目。
+3. `skiff` 命令可用。
+
+不要覆盖已有的 `docs/ack/project.md`、`docs/ack/tasks.yaml`、
+`docs/ack/knowledge.yaml`、`docs/ack/delivery.yaml`、`AGENTS.md` 或其它 Agent
+指令文件。ACK 不会自动
+修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。不要把 token、`.env`
+内容或其它私有配置写入 ACK 项目状态。
+
+## 初始化
+
+在目标项目执行：
+
+```bash
+skiff init ack
+```
+
+或显式指定项目：
+
+```bash
+skiff init ack --project <project-root>
+```
+
+命令从 ACK Skill 自带的 `templates/` 生成：
+
+```text
+docs/ack/
+├── project.md
+├── tasks.yaml
+├── knowledge.yaml
+└── delivery.yaml       # 默认 enabled: false
+```
+
+如果任一目标文件已经存在，命令会拒绝覆盖。初始化过程不会创建 `kit`、
+`framework` 或其它指向 Skill 的软链接。
+
+### 旧项目补充知识库
+
+旧项目已经有 `project.md` 和 `tasks.yaml`、但没有 `knowledge.yaml` 时，不要重跑
+`skiff init ack`。先检查现有文件并向用户报告缺失项；用户授权后，只从
+`templates/knowledge.template.yaml` 生成 `docs/ack/knowledge.yaml`，替换项目名和
+当前时间，保留 `entries: []`。如果现有任务板缺少
+`project.knowledgeFile`，同一次授权只补
+`knowledgeFile: docs/ack/knowledge.yaml`，不改写其它项目状态。生成后运行任务板、
+知识库和跨文件引用校验。
+
+### 旧项目补充交付配置
+
+`delivery.yaml` 对旧项目是可选能力；缺少它不会影响三角色开发与验证闭环。只有用户
+明确要求配置项目交付时，才从 `templates/delivery.template.yaml` 生成文件，同时在
+任务板补 `project.deliveryFile: docs/ack/delivery.yaml` 与顶层
+`deliveryRuns: []`。首次生成保持 `enabled: false`，按 `delivery.md` 展示并确认
+解析结果后才启用。不要重跑 `skiff init ack`，也不要改写已有任务或知识。
+
+## 完善项目覆盖层
+
+编辑 `docs/ack/project.md`，填入：
+
+- 项目名、技术栈、运行命令和 Base URL。
+- Coordinator、Developer、Test 的实际模型档位。
+- 规格、集成测试、源码、单元测试和私有配置的路径权限。
+- Developer 白盒验证命令。
+- Test 黑盒复测命令。
+
+无法从项目证据确定的值写为 `n/a`，不要猜测。
+
+## 完善任务板
+
+编辑 `docs/ack/tasks.yaml`：
+
+- `ackVersion` 使用 ACK Skill 的合法 SemVer `VERSION`；从 `0.10.0` 起
+  `project.orchestration` 与顶层 `workerReceipts` 必须同时存在。
+- 从 `0.11.0` 起的新项目初始化包含默认关闭的交付契约；旧项目不要求为了版本号升级
+  自动补交付配置。
+- 从 `0.12.0` 起的新项目 orchestration 模板包含可选一次性交付所需的 Operator；其
+  默认 CLI、standard 模型和 reasoning effort 与 Test default 相同。旧项目不补也能
+  运行原闭环，但不能使用一次性交付路由。
+- `updatedAt` 使用当前带时区时间。
+- `project.name`、`repoPath`、`devWorktree`、`overlayFile` 和 `knowledgeFile` 使用
+  真实值。
+- 新项目的 `project.deliveryFile` 固定为 `docs/ack/delivery.yaml`，并保留顶层
+  `deliveryRuns: []`。旧项目只有在采用交付能力时才补这两个字段。
+- `project.orchestration.allowedWorktrees` 使用已核对的绝对 worktree；模型
+  allowlist、profiles 和 defaults 使用项目实际允许值。不要把完整启动命令、
+  `extraArgs`、`env` 或任意 executable 写进任务板。
+- 非服务项目的 `baseUrl` 写为 `n/a`。
+- 没有真实任务时使用 `tasks: []`，不要保留或虚构示例任务。
+
+每个真实任务的验收必须是可观测信号，例如可见文本、API 状态和字段，或明确的交互
+结果；不要只写“功能正常”。
+
+## 初始化项目知识
+
+新项目的 `docs/ack/knowledge.yaml` 保持 `verificationRegistry: {}` 与
+`entries: []`。不要从聊天、README、issue 或单次失败中猜测并激活知识。
+
+项目运行 ACK 后，Developer 和 Test 可以通过回报提名 `knowledgeCandidates`；
+candidate 留在任务证据中，不会被派发。只有 Test 独立验证且 Coordinator gate
+通过后，Coordinator 才能把它写成 `active` 条目。全项目范围的强制或权限类规则
+还需要 User / Decision Owner 确认。
+
+知识条目只引用项目已审查的 `verification.ref`。对应入口保存在
+`knowledge.yaml.verificationRegistry`，只允许仓库内相对 path 和结构化 args，
+不保存或自动执行自由 shell 命令。需要执行时只把 registry ID 交给
+`<ack-skill-dir>/scripts/run_verification.py`，不直接运行 path/args。关键约束应
+最终下沉为测试、lint、CI 或正式规范。
+
+## 初始化项目交付
+
+新项目的 `docs/ack/delivery.yaml` 保持 `enabled: false`、空能力表和空 profile。
+不要根据 README 或 CI 自动推断并启用发布/部署。用户用自然语言描述交付要求后，
+Coordinator 按 `delivery.md` 维护声明式配置：工具 target 与仓库脚本分开引用，产物、
+目的地、环境和有序 profile 使用稳定 ID。配置中不保存 shell、环境变量值或凭据
+正文；稳定发布和生产部署必须有显式 approval 步骤。
+
+## 校验
+
+Agent 从当前 `SKILL.md` 解析 ACK Skill 目录后运行：
+
+```bash
+python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
+python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml
+python3 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml \
+  --tasks docs/ack/tasks.yaml --project-root <project-root>
+```
+
+同时确认：
+
+- `project.md`、`tasks.yaml`、`knowledge.yaml` 和 `delivery.yaml` 没有未替换的
+  `<...>` 占位符。
+- `project.overlayFile` 指向真实文件。
+- `project.knowledgeFile` 指向 `docs/ack/knowledge.yaml`。
+- 新项目的 `project.deliveryFile` 指向 `docs/ack/delivery.yaml`；交付默认关闭。
+- Developer 与 Test 的验证命令可执行。
+- `project.orchestration` 的 profile/allowlist/defaults 通过校验，自动模式只允许
+  `read-only` 或 `workspace-write`；旧任务板未迁移时保持手动模式。
+- 若配置 Operator，其 default 与 Test 使用相同 CLI、standard 模型和 effort。
+- 顶层 `workerReceipts` 和 `dispatch.developer/test/operator` 的 task/role/profile/attempt
+  引用一致；`receiptId` 与 `attemptId` 同时为空或同时填写。持久 receipt 只作审计，
+  v0.10 不自动复用旧终端。
+- 网站或 API 项目写清服务启动、重启和 Base URL。
+- 任务中的固定 revision `knowledgeRefs` 都能解析，非 `active` 条目没有被派发。
+
+## 初始化报告
+
+完成后报告：
+
+- 创建或确认的四个项目文件。
+- 检测到的技术栈和验证命令。
+- 任务板、项目知识和交付契约校验结果。
+- 仍需用户补充的值。
+
+只有结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”，并列出
+具体阻塞项。除非用户明确要求，不提交、不推送。
@@ -0,0 +1,175 @@
+# 如何开始一个需求（Kickoff）
+
+从零开一个需求的启动手册。角色/权限见 `roles-and-permissions.md`，闭环见 `closed-loop.md`，模型见 `model-routing.md`。
+
+---
+
+## 前提：谁是 Coordinator
+
+**你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。** 你负责写文档、拆任务、
+编排、终检，**不亲自写代码、不亲自跑测试**。开发和测试是另起的 worker agent；
+具体 CLI、模型、reasoning effort 和执行模式的机器事实源是
+`docs/ack/tasks.yaml` 的 `project.orchestration`。`docs/ack/project.md` 只解释项目
+差异，不能提供另一套启动命令。
+
+---
+
+## 第 0 步：给 Coordinator 的开场指令（复制改需求）
+
+```text
+我要做一个新需求：<一句话需求>。
+你作为 ack 的 Coordinator(PM)，按 ACK Skill 的 references 规范执行：
+
+1. 先读 docs/ack/project.md、docs/ack/tasks.yaml（包括 project.orchestration），校验 docs/ack/knowledge.yaml 并
+   用 `scripts/select_knowledge.py` 只读取当前任务相关的 active 条目，再读
+   references/roles-and-permissions.md、closed-loop.md、optimization-method.md。
+   如果 tasks.yaml 声明 project.deliveryFile，再读取 delivery.yaml 与
+   references/delivery.md，但不要把配置本身当作执行授权。
+2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
+3. 按任务 scope 从 knowledge.yaml 推荐 active 知识，确认后把固定 revision 的
+   knowledgeRefs 写入任务；不要派发 candidate 或全量知识库。
+4. 把任务写进 docs/ack/tasks.yaml（只有你写），校验 tasks.yaml 和 knowledge.yaml。
+5. 先把「产品文档 + 任务拆分 + 验收信号 + 适用知识引用」给我确认；若启用了交付，
+   同时列明本次 profile、目标、停止点与审批步骤。不要急着派发或交付。
+6. 我确认后，按 ack 闭环循环：先用 `scripts/launch_worker.py` 校验结构化
+   Developer/Test profile，审阅 plan 后用 expected fingerprint 创建 fresh worker，
+   dispatch 开发 → worker_done → dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml；
+   每个任务最多三轮，三轮不过记 leftover 并升级我复盘。
+7. 所选任务都 verified 后，只有本次计划包含交付时才按 profile 顺序执行并写
+   deliveryRuns；默认停在 review_ready，stable/production 步骤再次向我确认。
+```
+
+---
+
+## 第 1 步：Coordinator 产出（确认前）
+
+1. 产品文档 → `docs/PRD-<feature>.md` 等（Coordinator R/W）。
+2. 任务板 → `docs/ack/tasks.yaml`，每条任务带 `expected` + `verification`，验收写成可观测信号（见 `optimization-method.md` §1）。
+3. 项目知识 → 从 `docs/ack/knowledge.yaml` 按 component、path、dependency、version
+   和 tag 推荐 `active` 条目，Coordinator 确认后写入固定 revision 的显式
+   `knowledgeRefs`。candidate 不参与选择。
+4. 校验结构与引用：
+
+```bash
+python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
+python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml
+```
+
+   `project.orchestration` 是 worker profile 的机器 SSOT；未知字段、非 allowlist 模型、
+   不匹配的角色/档位和非安全权限必须在派发前 fail closed。
+
+5. **停下来给人确认**：这是强模型该花时间的地方，不要跳过。
+
+如果 `delivery.enabled: true`，确认内容还必须列出：profile、关联 task IDs、构建产物、
+发布 channel、部署环境、PR 是否创建/标 ready、停止点，以及哪些步骤会再次审批。
+
+---
+
+## 第 2 步：决定 worktree
+
+见 `closed-loop.md` §「子任务放哪」：
+
+- 需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。
+- 小改动 / 串行修复 → 当前 worktree 起子 agent。
+
+---
+
+## 第 3 步：审阅并启动 worker
+
+先读 `tasks.yaml.project.orchestration` 的结构化 profiles。v0.10 不把历史 receipt
+或既有 Orca terminal 当作自动复用授权；每次自动派发都创建 fresh worker。原因和
+边界见 `model-routing.md` §「Receipt、审计与复用边界」。
+
+先查看目标 profile hash，确认本次结构化配置。这个 hash 只用于审计和漂移比较，
+不能用于匹配或复用旧 receipt / 既有终端：
+
+```bash
+python3 <ack-skill-dir>/scripts/launch_worker.py profile-hash \
+  --project-root <project-root> --profile-id <profile-id>
+```
+
+生成只读计划：
+
+```bash
+python3 <ack-skill-dir>/scripts/launch_worker.py plan \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test> \
+  --profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99>
+```
+
+审阅计划后执行唯一创建入口：
+
+```bash
+python3 <ack-skill-dir>/scripts/launch_worker.py launch \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test> \
+  --profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99> \
+  --expected-launch-fingerprint <plan 中的 sha256:...>
+```
+
+`launch` 的 fingerprint 必须来自刚才审阅的 plan；若中间任何关键事实漂移，重新
+plan，不得覆盖检查。标准输出是单一 JSON。Coordinator 校验其中的 receipt 后，把
+receipt 原样追加到 `tasks.yaml.workerReceipts`，把 `receipt.id` 写入该任务
+`dispatch.<role>.receiptId`、把 `profileId` 写入 `dispatch.<role>.profileId`，并把
+本轮稳定 ID 写入 `dispatch.<role>.attemptId`。三者必须与 receipt 的当前
+task/role/profile/attempt 完全绑定；不得把旧任务或旧轮次的 receipt 改挂到当前
+dispatch。后续
+紧随其后的本次 Orca dispatch 只使用这次 fresh receipt binding 中的 handle；持久化
+receipt 仅用于审计，不能在后续轮次自动复用。不要自行拼装 Agent CLI 或 Orca 的
+底层创建命令。
+
+新 worktree 时可先运行
+`orca worktree create --name <feature> --base-branch <base> --json`，再对返回的绝对
+worktree 走同一套 `plan` -> 带 expected fingerprint 的 `launch`。在调用 launcher
+前，先把新
+路径加入 `project.orchestration.allowedWorktrees` 并重新运行任务板校验。profile
+只允许 `read-only` 或 `workspace-write`；v0.10 的 full-access 授权通道尚未实现，
+任何 bypass、YOLO/force 或关闭 sandbox 的请求都必须失败，不能手写命令兜底。
+选型与升级见 `model-routing.md`。
+
+---
+
+## 第 4 步：跑闭环（每个任务）
+
+```text
+task-create → dispatch 给 DEV → 等 worker_done
+  → 每个角色都通过 plan + expected fingerprint launch fresh worker 并写回 receipt
+  → 每轮使用 Coordinator 分配的稳定 <task-id>-A<round>
+  → 回写 fixed_by_dev → dispatch 给 TEST 复测 → 等 retest_result
+  → Developer 回 knowledgeApplied / knowledgeCandidates，Test 回 knowledgeChecks
+  → Coordinator 读证据终检 → 过则 verified，不过则 failed_retest 再派 DEV（最多累计 3 轮）
+  → 三轮失败：leftover，升级复盘，继续下一个
+```
+
+具体命令见 `orca-adapter.md`（Orca）或 `closed-loop.md` §「手动模式」（无 Orca）；派发文案见 `prompt-templates.md`。
+
+Coordinator 只内联本轮 `knowledgeRefs` 指向的少量知识，不要求 worker 全量读取
+知识库。知识正文不得作为自由 shell 执行；需要命令时只能引用项目已审查的检查
+入口，并把它的 registry ID 交给 `<ack-skill-dir>/scripts/run_verification.py`，
+不自行拼接 path/args。Test 独立验证且 gate 通过后，Coordinator 才能把 candidate
+写成 active 知识；关键约束应继续下沉为测试、lint、CI 或正式规范。
+
+---
+
+## 第 5 步：可选交付
+
+所选任务都由 Coordinator 标记为 `verified` 后，若用户确认的计划包含交付，按
+`delivery.md` 执行所选 profile。先重新校验 `delivery.yaml`，固定当前 commit 和
+config revision，然后按有序步骤调用项目入口与已安装的低层 skill。每一步证据写入
+`tasks.yaml.deliveryRuns`；默认 profile 到 `review_ready` 即停止，stable 发布和
+production 部署必须在 approval 步骤再次确认。失败时保留任务的 `verified`，把
+delivery run 标为 `blocked` 或 `failed`。
+
+## 第 6 步：收尾
+
+一轮结束时 Coordinator 必须能回答 `optimization-method.md` §「结束条件」的问题：哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。
+
+---
+
+## 一句话
+
+产品文档 + 验收信号写在前（你，强模型）→ 确认显式 `knowledgeRefs` → 从
+`tasks.yaml.project.orchestration` 解析安全 profile → 审阅 plan 并用 expected
+fingerprint 启动 fresh DEV/TEST → dispatch / 复测 / 终检循环 → 任务结论落
+`tasks.yaml` → 可选 delivery profile 到审核点，验证后的
+跨任务知识由 Coordinator 落 `knowledge.yaml`。
@@ -0,0 +1,256 @@
+# 模型路由（稳定核心）
+
+本文件是**三角色与可选 Operator 的默认模型档位、升级规则和 worker profile 选择规则**的单一规范源。
+目标是在不牺牲质量的前提下降低 token 和模型成本：把昂贵的强模型留给需要判断的
+工作，把机械执行交给较弱模型。
+
+角色定义见 `roles-and-permissions.md`（Coordinator 编排 / Test 验证 / Developer
+实现）。本文件只补一层正交的「用哪个档位、以什么安全 profile 启动 worker」。
+
+---
+
+## 默认档位
+
+| 角色 | 默认模型档位 | 理由 |
+|------|--------------|------|
+| Coordinator (PM) | 强模型 | 需求拆解、验收信号设计、优先级、终检对齐意图、三轮失败复盘都需要高质量推理 |
+| Test | 中低模型 | 按既定验收信号执行浏览器/API/脚本，主要做观察、记录、逐条 pass/fail |
+| Developer | 中低模型（按任务升级） | 多数实现可照规格执行；跨系统、数据迁移、重复失败时再升级 |
+| Operator（一次性交付） | 与 Test 相同的中低模型 | 按低层发布 Skill 执行机械步骤并回传证据，不承担范围决策 |
+
+Coordinator 用强模型但**不亲自跑测试**（测试由 Test 承担），所以强模型的 token
+花在思考和终检上，而不是反复点击页面、跑 smoke、复制日志。这一分工天然省 token，
+同时保持「验证者 != 实现者」。
+
+---
+
+## 什么时候用强模型
+
+- 新需求理解、产品取舍、范围决策。
+- 架构与数据模型决策。
+- 把验收写成可观测信号（见 `optimization-method.md` §1）。
+- 需求含糊、规格与实现/测试冲突时的裁决。
+- Coordinator 终检：读证据、对齐原始意图。
+- 重复失败后的根因复盘与重新拆分。
+
+## 什么时候用中低模型
+
+- Test：跑浏览器用例、API smoke、逐条比对期望与实际、产出证据。
+- Developer：从清晰规格实现范围明确的任务、跑构建与单测、回报 worker_done。
+- Operator：执行 `delivery-routing.md` 已选定的发布 Skill，按其停止点记录证据。
+
+---
+
+## 升级规则
+
+**升级到 Coordinator（强模型）复盘**，当：
+
+- 同一验收路径 Developer 连续失败三轮（见 `optimization-method.md` §4）。
+- Test 两次仍无法给出清晰失败证据。
+- 任务需要改动产品范围或验收标准。
+- 修复涉及持久化数据、破坏性文件操作、安全或回滚。
+- 规格、测试、实现三者出现冲突。
+
+**升级 Developer 模型档位**，当：
+
+- 任务横跨多个子系统。
+- 改动涉及数据模型或迁移。
+- 需要设计新的抽象。
+- 低档位反复产出表面修复。
+
+升级由 Coordinator 判断并记录原因。升级不是修改一个正在运行的终端：必须选择
+对应强档 profile，重新计算 `profileHash`，再通过 launcher 创建新的 worker。
+v0.10 不自动复用持久化 receipt 指向的旧终端，Test 也不得使用 Developer 的强档
+worker。
+
+---
+
+## 结构化 worker profile
+
+### 机器事实源
+
+worker 路由的机器可读事实只保存在 `docs/ack/tasks.yaml` 的
+`project.orchestration`。`project.md` 可以解释项目为何选某个档位，但不能另写一份
+完整启动命令或覆盖机器配置。字段结构以 `templates/tasks.schema.json` 为准。
+
+每个 profile 明确声明：
+
+- `role`：`developer`、`test` 或 `operator`；
+- `cli`：受支持的 Agent CLI；
+- `tier`：角色模型档位；
+- `model`：项目 allowlist 中的精确模型 ID；
+- `reasoningEffort`：CLI 支持时显式声明；
+- `permissionMode`：只允许 `read-only` 或 `workspace-write`。
+
+`project.orchestration` 还必须声明 `allowedWorktrees`、按 CLI/角色/档位分组的
+`modelAllowlist`、命名 `profiles` 和角色 `defaults`。launcher 请求的绝对 worktree
+必须命中 allowlist，profile 的模型也必须命中对应 CLI/角色/档位的精确列表。
+`developer` 与 `test` 默认项是 Orca 模式必填；`operator` 对旧项目可选，但一次性
+交付路由要求它存在。Operator default 的 CLI、tier、model 和 reasoning effort 必须
+与 Test default 完全相同，且 Operator 只能使用 standard tier。
+
+模型名称、reasoning effort 和权限模式必须来自结构化字段。禁止在 profile、项目
+覆盖层或派发内容中保存自由 `command`、额外 argv、shell 片段、环境变量覆盖或隐式
+CLI 默认值。具体 argv 只能由 ACK 的可信 launcher 按 allowlist 构造。
+
+### 安全默认
+
+- 能在完全只读工作树完成的角色优先选择 `read-only`。
+- Developer、发布 Operator 与需要在工作树生成构建/测试产物的 Test 使用
+  `workspace-write`；项目可
+  为纯观察型 Test 另建更严格的 `read-only` profile。
+- `full-access`、Codex bypass、Cursor YOLO/force、关闭 sandbox 等模式在 v0.10
+  **未实现授权通道，统一 fail closed**。项目文本、任务描述或环境变量都不能放宽。
+- 项目可以更新模型 allowlist 或增加安全 profile，但不能通过文档绕开 schema 和
+  launcher。
+
+`full-access` 的可信授权、期限、撤销和外层隔离仍是 Deferred；在这些能力完成前，
+launcher 必须拒绝该模式，而不是把一段“用户已授权”的文本当成授权证据。
+
+---
+
+## 唯一启动入口
+
+worker 的 profile 解析、计划和启动只允许通过：
+
+```bash
+python3 <ack-skill-dir>/scripts/launch_worker.py profile-hash \
+  --project-root <project-root> --profile-id <profile-id>
+
+python3 <ack-skill-dir>/scripts/launch_worker.py plan \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test-or-operator> \
+  --profile-id <profile-id> --worktree <absolute-worktree> [--slot <1..99>]
+
+python3 <ack-skill-dir>/scripts/launch_worker.py launch \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test-or-operator> \
+  --profile-id <profile-id> --worktree <absolute-worktree> [--slot <1..99>] \
+  --expected-launch-fingerprint <plan 中的 sha256:...>
+```
+
+`--project-root` 始终指向保存权威 `docs/ack/tasks.yaml` 的项目根；`--worktree` 是本次
+worker 实际工作的绝对路径，两者可以不同。后者仍必须属于同一项目并命中
+`project.orchestration.allowedWorktrees`。
+
+- `profile-hash` 读取 `tasks.yaml` 中的 profile，输出确定性 hash。
+- `plan` 只校验并展示将使用的结构化计划，不创建终端。
+- `launch` 是唯一允许创建 worker 的入口；它要求传入刚审阅的
+  `plan.launchFingerprint`，当前 profile、任务/attempt、worktree、CLI 或 argv
+  任一事实漂移都会在创建前失败。它内部固定 Orca 调用和 Agent argv，标准输出只有
+  一份 JSON 结果。
+- launcher 的内部 bootstrap 属于私有协议，Coordinator 不直接调用、不复制到项目
+  文档，也不自行拼装 Orca 的底层终端创建文本。
+
+Coordinator 在执行 `launch` 前必须先审阅 `plan`。任何校验失败、字段未知、路径不
+匹配、CLI 不可用或权限模式不支持，都停止创建并回报，不回退到裸 Agent 命令。
+
+---
+
+## 可执行信任边界
+
+v0.10 的 launcher 还执行以下约束：
+
+- 不读取调用者传入的 `PATH` 来寻找 `git`、Orca 或 Agent CLI，只在固定的系统与
+  当前用户工具目录中解析受支持的可执行文件；候选目标必须由 root/当前用户拥有、
+  不是 group/other writable，并在 plan 与 bootstrap 间保持相同 device/inode。
+- Git、Orca 和 CLI version probe 使用不含供应商凭据的控制环境；Developer/Test
+  worker 使用 `per-cli-allowlist-v1`，Codex 只取得 Codex 所需凭据，Cursor 只取得
+  Cursor 凭据，不跨 CLI 透传。Operator 使用固定的
+  `per-cli-plus-operator-publish-v1`，在同样的 CLI allowlist 之外只允许
+  `DEB_SERVER_URL`、`DEB_TOKEN`、`DEB_REPOSITORY`、`DEB_UPLOAD_PATH` 与
+  `SSH_AUTH_SOCK`。这些值不进入 plan、receipt、任务板或日志；Docker/Forge CLI
+  默认只使用当前账户 HOME 中自己的凭据存储。`DBUS_*`、`DISPLAY`、
+  `WAYLAND_DISPLAY`、`XDG_RUNTIME_DIR`、`LD_*`、`PYTHON*`、`NODE_OPTIONS`、
+  `CODEX_HOME`、`GIT_*`、任意 Docker 密码变量和调用者 PATH 均不会透传给 worker。
+- worktree 除了命中项目 allowlist、属于同一 Git common-dir，还必须精确出现在
+  `git worktree list --porcelain -z` 中；`.git` symlink 冒充的目录会失败。
+- Orca 的 `--command` 只含固定 bootstrap 与随机 launch ID。终端创建后，父进程先
+  绑定 runtime/handle/incarnation/worktree，再通过该终端 stdin 发送一次性 nonce；
+  bootstrap 校验 nonce 后才允许启动 Agent CLI，并把 child PID 与 nonce/launch
+  fingerprint 绑定的 proof 原子写入 ready 状态；父进程看到并核对 proof 后才把
+  worker 视为可派发。
+- `orca terminal create` 一经发出，在取得确定 handle 前遇到超时、transport/解码
+  异常、进程中断、非零退出、畸形 JSON 或缺字段，一律标记为 `indeterminate`，
+  禁止自动重试。
+- 取得 handle 后若任一绑定或握手检查失败，launcher 会先用
+  `orca terminal close --tab --json` 请求持久关闭，并严格核对 runtime、handle、
+  tab 和 close mode。只有关闭回执完整匹配才记为普通 `failed`；关闭无法确认时保持
+  `indeterminate/reconcile-required`，调用方必须先人工核对，不能直接重试。
+- bootstrap 在真正启动 Agent 前，会在同一 launch-record 锁内再次确认状态仍为
+  `awaiting-authorization` 且没有 cleanup；父进程一旦先进入 cleanup/reconcile，
+  bootstrap 必须拒绝 `Popen`，不能让取消后的 workspace-write worker 继续启动。
+- 异常路径的 launch record 写入失败不能阻断上述关闭动作，也不能遮蔽原始
+  `indeterminate`。即使关闭已确认，只要最终状态无法可靠持久化，也保守返回
+  `indeterminate/reconcile-required`。
+
+这些约束防止任务板、任务文本和普通环境变量变成第二个启动命令入口。它们不抵御已经
+完全控制 Coordinator 用户账户、Orca 运行时、受信 Agent/Orca 可执行文件或
+Coordinator 用户级 Agent 配置/插件/MCP 的攻击者；该场景需要独立 OS 身份、受控
+Agent 配置或平台签发能力。`permissionMode` 约束的是 Agent CLI 的 shell/文件系统
+执行模式，不是模型供应商或外部工具能力的 attestation。
+
+---
+
+## Receipt、审计与复用边界
+
+成功启动返回的 JSON 含一个可校验 receipt。Coordinator 把 receipt 追加到
+`tasks.yaml` 顶层 `workerReceipts`，并把它的 `id` 写入当前任务
+`dispatch.<role>.receiptId`、把 `profileId` 写入 `dispatch.<role>.profileId`，同时把
+本次 `<task-id>-A<round>` 写入 `dispatch.<role>.attemptId`。
+
+这三个字段不是可任意组合的历史索引。任务板校验器要求被引用 receipt 的
+`createdFor.taskId` 等于当前 ACK `tasks[].id`，`createdFor.role` 等于 dispatch
+角色，`profileId` 完全相同，且 `createdFor.attemptId` 等于
+`dispatch.<role>.attemptId`。`receiptId: null` 时 `attemptId` 必须同为 `null`；
+`receiptId` 非空时 `attemptId` 必须存在并命中本轮。`dispatch.<role>.taskId` 是 Orca
+运行时 task ID，不能拿来替代 ACK task ID 或稳定 attempt ID。
+
+receipt 至少把以下事实绑定在一起：
+
+- `profileHash` 与请求的角色、模型、effort、权限和精确 argv；
+- `slot`，确保 fingerprint 也绑定审阅过的 worker 槽位和派生标题；
+- 任务、attempt、绝对 worktree 及 path/device/inode/git common-dir 等稳定身份；
+- Orca `runtimeId`、terminal `handle` 和 `incarnationId`；
+- 创建时间、launcher 指纹和 `receiptHash`。
+
+`receiptHash` 是无密钥的规范 JSON checksum，只能发现意外漂移或未同步修改，**不是
+launcher 身份证明，也不是复用授权**。项目内有写权限的一方可以修改 receipt 后重算
+hash；而当前 Orca metadata 又不能证明终端最初执行的命令、模型和权限。因此 v0.10
+明确禁止根据持久化 receipt 自动复用既有终端：每次需要自动派发 worker，都重新走
+`plan` → 带 expected fingerprint 的 `launch`，只使用该次 launcher 标准输出中的
+fresh handle 完成本次派发。
+
+`launchFingerprint` 是确定性的完整计划漂移校验，不是一次性授权或幂等键。同一份
+计划重复执行 `launch` 会创建新的 fresh terminal；成功后不得用同一 fingerprint
+再次启动。若结果不确定，必须先 reconcile，不能把重跑当作恢复方式。未来需要自动
+防重放时，应由 Orca/ACP 的原子 idempotency/claim 能力或项目外可信 launch intent
+提供，而不是把 checksum 冒充成一次性令牌。
+
+持久化 receipt 仍用于审计、dispatch 关联和检测配置漂移；标题、preview、分支名、
+worker 自报或单独的 Orca live metadata 都不能把旧终端提升为可信 worker。未来只有
+在 Orca/ACP 提供启动参数 attestation，或存在项目外可信签发与校验通道后，才开放
+自动复用。CLI / 模型变更仍需更新 allowlist 并重新生成 receipt。
+
+`ackVersion` 必须使用合法 SemVer。`0.10.0` 及以后版本的任务板必须同时存在
+`project.orchestration` 与顶层 `workerReceipts`；其中任一字段出现，另一个也必须
+出现，避免 schema-only 校验把半迁移任务板误判为可自动派发。
+
+---
+
+## 成本原则
+
+强模型产出高密度、可复用的产物：需求、架构决策、验收信号、任务拆分、失败复盘。
+中低模型消费这些产物，产出可核对的执行证据：测试结果、快照、API 响应、构建日志、
+改动文件清单和发布目标摘要。
+
+这样把昂贵推理挡在重复执行之外。
+
+---
+
+## 一句话
+
+Coordinator 是脑，Test 是眼，Developer 是手；一次性交付 Operator 是按已选 Skill
+操作发布系统的手。Coordinator 用强模型做判断，其余角色默认用安全、较低成本的结构化
+profile；只有常规闭环卡住时才升级，并且所有 worker 都必须经 launcher 产生可核对的
+receipt。
@@ -0,0 +1,186 @@
+# 优化方法（稳定核心）
+
+减少"开发声称完成但复测不过"的循环成本。本文件是**验收信号写法**和**三轮失败策略**的 SSOT，其它文件引用这里。
+
+三角色分工（Coordinator 编排 / Test 验证 / Developer 实现）见 `roles-and-permissions.md`；复测步骤、Coordinator 终检与环境对齐见 `closed-loop.md`。
+
+---
+
+## 1. 先把验收写成可观测信号（SSOT）
+
+不要只写"页面可用""体验更好"。每个任务至少写三类信号：
+
+| 类型 | 示例 |
+|------|------|
+| 可见文本 | 页面出现 `确认应用标签`、`取消`、`将修改` |
+| API 结果 | `POST /api/...` 返回 `code=0` 且字段存在 |
+| 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
+
+好的验收：
+
+```text
+点击"预览变更"后，页面必须出现 API 返回的 diff 行：
+- title
+- 修改前值
+- 修改后值
+- coverChanged 提示
+```
+
+不好的验收：
+
+```text
+预览功能正常。
+```
+
+---
+
+## 2. 回报必须带证据，不带结论
+
+Developer 的 `worker_done` 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。Test 的复测报告同理：跑了哪些命令、命中/缺失了哪些验收信号、实际观察到什么、证据（snapshot / API 结果）。两者的"结论"都不作数；任务结论只有 Coordinator 落盘到 `tasks.yaml` 才算数，跨任务知识只有 Coordinator 落盘到 `knowledge.yaml` 才会生效。
+
+不要写：
+
+```text
+已完成，应该可以了。
+```
+
+要写：
+
+```text
+修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
+手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
+风险：未执行真实写文件 apply。
+```
+
+---
+
+## 3. 验证权在 Test，Coordinator 只信证据
+
+即使 Developer 的 worker_done 写了"全部通过"，也必须由独立的 Test 复测（验证者 ≠ 实现者）。完整复测步骤与 worktree/服务对齐见 `closed-loop.md`。独立复测可避免三类假通过：测错服务实例、测到旧构建产物、开发只验证静态文本没验证真实交互。
+
+Coordinator 不亲自复测，但要做终检：读 Test 的证据，确认它覆盖了每条验收信号且符合原始意图，避免"过了字面没过意图"。终检不通过就回写 `failed_retest`。
+
+---
+
+## 4. 三轮失败策略（SSOT）
+
+每个任务最多自动派发三轮：
+
+```text
+round 1: 常规修复
+round 2: 带复测失败证据的定向修复
+round 3: 明确指出重复失败点，要求 worker 自己复现完整路径
+failed after round 3: 标记 leftover，继续下一个任务
+```
+
+三轮失败后不要继续消耗同一个 worker。常见原因：验收标准需要重新设计、Worker 对问题模型理解错了、UI 自动化与实际浏览器状态有差异、需要人工观察或调试工具介入。
+
+留档字段（结构见 `templates/tasks.schema.json`）：
+
+```yaml
+status: leftover
+resolution:
+  leftoverReason: "failed after 3 supervised developer rounds"
+dispatch:
+  rounds:
+    - round: 1
+      result: failed
+      evidence: "<why failed>"
+    - round: 2
+      result: failed
+      evidence: "<why failed>"
+    - round: 3
+      result: failed
+      evidence: "<why failed>"
+```
+
+---
+
+## 5. 任务排序
+
+1. P0 阻塞主流程。
+2. P1 高频用户路径。
+3. P1/P2 体验改进。
+4. 重构和内部质量。
+
+三轮失败的 P0 可以留档，但发布前需人工决策：降级范围、改验收标准、换新 Agent / 新 worktree 重做、人工修复。
+
+---
+
+## 6. 每轮派发只修一个明确问题
+
+不要一次让 Developer Worker 修太多失败项，除非它们共享同一根因：
+
+```text
+one dispatch = one bug = one acceptance path
+```
+
+优点：复测更快、失败原因更清楚、三轮失败留档更准确。
+
+---
+
+## 7. 把失败证据写给下一轮 worker
+
+第二轮以后，派发 prompt 应突出"上一轮为什么没过"，而非重复原始描述。模板见 `prompt-templates.md` §「复测失败再派发模板」。
+
+---
+
+## 8. 优先让测试可执行化
+
+如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。这类可执行测试由 Test 拥有并维护（见 `roles-and-permissions.md` 权限表的 `<integration_test_paths>`）。优先级：
+
+1. API smoke。
+2. 浏览器脚本或 case 文档。
+3. 单元测试。
+4. 人工检查清单。
+
+目标不是全部自动化，而是把最容易反复误判的路径自动化。
+
+---
+
+## 9. 让经验成为有证据、会过期的知识护栏
+
+项目特有、跨任务复用且会改变后续开发或验证行为的经验，可以提名到项目知识护栏。
+不要把全部对话、日志或单次猜测自动保存成“记忆”。
+
+```text
+Developer / Test 当前任务观测
+  -> knowledgeCandidates（只留在任务证据）
+  -> Test 独立验证 + Coordinator gate
+  -> Coordinator 写入 active knowledge
+  -> stale
+  -> superseded / archived
+```
+
+`prepare(task)` 时只按 component、path、dependency、version 和 tag 推荐相关
+`active` 条目；自动匹配只负责推荐，Coordinator 确认固定 revision 的显式
+`knowledgeRefs` 才是本轮权威上下文。每轮只派发命中的少量条目，不全量注入知识库。
+
+Developer 回报实际采用的 `knowledgeApplied` 和带当前观测证据的
+`knowledgeCandidates`。Test 对本轮显式引用回报 `knowledgeChecks`，并用独立观测
+确认或否定 candidate。同一 Agent 不能把自己读到的旧知识复述成新证据，避免错误
+知识自我强化。
+
+知识中的验证只能引用 `knowledge.yaml.verificationRegistry` 中已经审查的仓库内
+相对 path 和结构化 args，不能把正文或选择器输出拼接成自由 shell 执行。实际运行
+只把 registry ID 交给 `<ack-skill-dir>/scripts/run_verification.py`。安全、正确性
+和兼容性等关键约束一旦稳定，应下沉为测试、lint、CI 或正式规范；知识项继续解释
+触发条件、原因与证据，不替代可执行控制。
+
+依赖、配置、路径或版本变化后应重新审查相关知识。临时 workaround 必须有失效或
+移除条件；冲突规则不能靠“最后写入者获胜”处理。
+
+---
+
+## 10. 结束条件
+
+一轮闭环结束时，必须能回答：
+
+- 哪些任务 verified？哪些 leftover？
+- 每个 leftover 失败了几轮？最后一轮失败证据是什么？
+- 当前工作树有哪些未提交改动？
+- 是否还有 open / failed_retest 未处理？
+- 本轮显式 `knowledgeRefs` 是否都有必要的 `knowledgeChecks`？
+- 是否有待验证 candidate，或因依赖、路径、版本变化需要转为 stale 的知识？
+
+答不清楚，闭环就还没结束。
@@ -0,0 +1,283 @@
+# Orca 适配器（稳定核心，一种编排实现）
+
+Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 `closed-loop.md`）；本文件只提供 Orca 的具体命令。没有 Orca 时用 `closed-loop.md` §「手动模式」。
+
+所有结论仍以 `tasks.yaml` 为准，Orca 消息不是最终记录。
+
+---
+
+## 何时用 Orca 编排
+
+用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 `worker_done` 后再复测。
+
+不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。
+
+---
+
+## 运行前检查
+
+```bash
+orca status --json
+orca terminal list --json
+orca orchestration task-list --json
+orca orchestration inbox --limit 20 --json
+```
+
+确认：Orca runtime 可达并取得本次 `runtimeId`；Coordinator 终端存在；当前没有冲突
+的活跃编排任务。Developer/Test worker 与一次性交付 Operator 都必须通过本次 launcher
+新建，不要求预先存在。
+
+---
+
+## 既有 worker 的处理
+
+v0.10 **不自动复用任何既有终端**。`receiptHash` 是无密钥 checksum，Orca 当前的
+terminal metadata 也不包含原始 Agent argv、模型或权限 attestation；两者即使完全
+匹配，仍不足以证明旧终端由可信 launcher 以目标 profile 创建。标题、preview、分支
+名或 worker 自报更不能作为证明。
+
+| 情况 | 动作 |
+|------|------|
+| 历史 receipt 与 live metadata 看似完全匹配 | 只作审计，不自动复用；重新 launch |
+| 没有 receipt，或只有同名终端 | 不复用；重新 launch |
+| 需要并发 worker | 使用下一 `slot` 重新 launch |
+| Developer 升级模型档位 | 选择强档安全 profile，重新 plan/launch |
+
+只有刚刚成功返回的 `launch` 标准输出中的 fresh handle，才可用于紧随其后的本次
+dispatch。未来若 Orca/ACP 增加启动参数 attestation，或 ACK 接入项目外可信签发
+通道，再单独设计自动复用；不能用项目文档声明跳过这条限制。
+
+---
+
+## 通过 launcher 创建 worker
+
+**模型不由 Orca dispatch 设置。** `task-create` / `dispatch` 只投递任务；Agent CLI、
+模型、reasoning effort 和权限由 `tasks.yaml.project.orchestration` 的结构化 profile
+决定，并且只能由 ACK launcher 构造。
+
+先只读生成计划：
+
+```bash
+python3 <ack-skill-dir>/scripts/launch_worker.py plan \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test-or-operator> \
+  --profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99>
+```
+
+确认计划中的任务、attempt、角色、profile hash、绝对 worktree 和安全权限模式后，再
+执行唯一启动入口：
+
+```bash
+python3 <ack-skill-dir>/scripts/launch_worker.py launch \
+  --project-root <project-root> --task-id <task-id> \
+  --attempt-id <task-id>-A<round> --role <developer-or-test-or-operator> \
+  --profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99> \
+  --expected-launch-fingerprint <plan 中的 sha256:...>
+```
+
+`launch` 必须携带刚才审阅的 `plan.launchFingerprint`；若 profile、任务/attempt、
+worktree、CLI identity/version 或精确 argv 漂移，创建前就失败。它内部调用当前
+Orca 后端并完成终端绑定；Coordinator 不自行执行或拼装 Orca 的底层终端创建文本，
+也不直接调用 launcher 的私有 bootstrap。
+若 launcher 报告 `indeterminate` 或 `reconcile required`，说明终端可能已经创建且
+持久关闭尚未得到可信确认；此时先按返回的 launch ID/record 和 Orca live state
+人工核对，禁止直接重复执行 `launch`。
+标准输出是单一 JSON。成功后：
+
+1. 校验返回 receipt 的 `receiptHash`；
+2. 把 receipt 原样追加到 `tasks.yaml.workerReceipts`；
+3. 把 `receipt.id` 写入当前任务 `dispatch.<role>.receiptId`，把 `profileId` 写入
+   `dispatch.<role>.profileId`，把本轮 `<task-id>-A<round>` 写入
+   `dispatch.<role>.attemptId`；校验器会要求 receipt 的 task/role/profile/attempt
+   与当前 ACK 任务完全一致；
+4. 再用 receipt binding 中的 handle 创建/派发 Orca 子任务。
+
+profile 只允许 `read-only` 或 `workspace-write`。v0.10 不提供可信的 full-access 授权
+通道；bypass、YOLO/force、关闭 sandbox 及其它 full-access 请求必须由 schema 和
+launcher fail closed，不能改用手写命令兜底。模型档位与升级规则见
+`model-routing.md`。
+
+需要隔离/并行时，可以先用 Orca 创建 worktree。Coordinator 必须先把返回的绝对
+路径加入 `project.orchestration.allowedWorktrees` 并重新校验 `tasks.yaml`，然后才在
+该路径上走 `plan` -> 带 expected fingerprint 的 `launch`，并把 receipt 留作审计。
+既有会话可以由用户直接操作，但不能进入 ACK v0.10 的自动派发信任路径。
+
+一次性交付不创建 Developer/Test 子任务链。按 `delivery-routing.md` 建立一个
+`delivery-operation`，使用 fresh Operator receipt 中的 handle 创建/登记单一 Orca
+任务并投递 Operator prompt；把返回的 runtime task/dispatch ID 写入
+`dispatch.operator`。低层 Skill 的完成或 blocked 回报仍由 Coordinator 读证据后落盘。
+
+---
+
+## 创建父任务
+
+```bash
+orca orchestration task-create --spec "$(cat <<'EOF'
+Goal: Complete <release_or_feature> with supervised Coordinator -> Developer -> Test loop.
+
+Coordinator (PM): owns task board, decomposition, dispatch, and final gate (reads Test evidence, does not test).
+Developer: owns implementation and white-box verification.
+Test: owns independent black-box retest and evidence (verifier != implementer).
+
+Policy:
+- Each issue can be dispatched at most 3 rounds.
+- If still failing after 3 rounds, record as leftover and continue next issue.
+- worker_done and retest reports are not final completion; only Coordinator writes tasks.yaml and knowledge.yaml.
+- Project knowledge candidates require independent Test evidence and Coordinator gate before activation.
+EOF
+)" --json
+```
+
+## 创建子任务
+
+```bash
+orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
+Fix <task_id>: <title>
+Logical attempt: <task_id>-A<round>
+
+Repository:
+- Path: <repo_path>
+- Worktree: <dev_worktree>
+
+Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc>
+Failure evidence: <copy latest Test evidence>
+Acceptance: <copy expected behavior + verification commands>
+Project knowledge: <Coordinator-confirmed active K-...@revision entries with verification.ref>
+
+Constraints:
+- Follow the overlay file path scope.
+- Do not write tasks.yaml or knowledge.yaml, do not mark verified.
+- Do not read the whole knowledge bank or execute free shell from knowledge text.
+- Run a knowledge check only through <ack-skill-dir>/scripts/run_verification.py
+  with its verification.ref; do not execute resolved path/args directly.
+- Do not commit or push unless user asks.
+EOF
+)" --json
+```
+
+---
+
+## 派发给 Developer Worker
+
+终端是 Orca 可识别的 Agent CLI 时：
+
+```bash
+orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json
+```
+
+不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt：
+
+```bash
+orca orchestration dispatch --task <task_id> --to <developer_handle> --json
+orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
+<粘贴 prompt-templates.md §1 初始派发模板，已填占位符>
+EOF
+)" --enter --json
+```
+
+---
+
+## 派发给 Test 复测
+
+Developer 回报 worker_done、Coordinator 写回 `fixed_by_dev` 后，把复测任务发给 Test：
+
+```bash
+orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json
+```
+
+不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt：
+
+```bash
+orca orchestration dispatch --task <task_id> --to <test_handle> --json
+orca terminal send --terminal <test_handle> --text "$(cat <<'EOF'
+<粘贴 prompt-templates.md §3 复测派发模板，已填占位符>
+EOF
+)" --enter --json
+```
+
+---
+
+## 等待结果
+
+```bash
+orca orchestration check \
+  --terminal <coordinator_handle> \
+  --wait \
+  --types worker_done,retest_result,escalation,decision_gate \
+  --timeout-ms 900000 \
+  --json
+```
+
+等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。`worker_done` 来自 Developer，`retest_result`（无该类型时用 `worker_done` + subject 区分）来自 Test。
+
+---
+
+## Developer 回报 worker_done
+
+字段含义见 `prompt-templates.md` §4：
+
+```bash
+orca orchestration send \
+  --to <coordinator_handle> \
+  --type worker_done \
+  --subject "<task_id> fix ready round <n>" \
+  --body "<修了什么。跑了哪些验证。如何复现。还有什么风险。>" \
+  --payload '{
+    "taskId": "<orca_task_id>",
+    "dispatchId": "<orca_dispatch_id>",
+    "attemptId": "<task_id>-A<n>",
+    "filesModified": ["<file_a>", "<file_b>"],
+    "verification": ["<command_a>: passed", "<command_b>: passed"],
+    "knowledgeApplied": [
+      {"ref": "<K-001@1>", "result": "applied", "evidence": "<what was done>"}
+    ],
+    "knowledgeCandidates": [
+      {
+        "kind": "pitfall",
+        "title": "<title>",
+        "claim": "<evidence-backed claim>",
+        "scope": {"components": ["<component>"], "paths": ["<path glob>"]},
+        "appliesWhen": "<trigger>",
+        "directive": "<action, not a shell command>",
+        "rationale": "<why it matters>",
+        "evidenceRefs": ["<current task evidence>"]
+      }
+    ],
+    "risk": "<remaining risk or none>"
+  }' \
+  --json
+```
+
+收到 worker_done 后，Coordinator 写回 `fixed_by_dev`，再按上文派发给 Test 复测。
+
+---
+
+## Test 回报复测结果
+
+字段含义见 `prompt-templates.md` §5：
+
+```bash
+orca orchestration send \
+  --to <coordinator_handle> \
+  --type retest_result \
+  --subject "<task_id> retest round <n>" \
+  --body "<逐条验收信号结论 + 实际观察 + 证据>" \
+  --payload '{
+    "taskId": "<orca_task_id>",
+    "dispatchId": "<orca_dispatch_id>",
+    "attemptId": "<task_id>-A<n>",
+    "env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"},
+    "signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"],
+    "knowledgeChecks": [
+      {"ref": "<K-001@1>", "result": "passed", "evidence": "<independent evidence>"}
+    ],
+    "knowledgeCandidates": [],
+    "conclusion": "all-signals-pass | signals-failed"
+  }' \
+  --json
+```
+
+无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>`
+区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`；
+通过独立验证和 gate 的跨任务经验再由 Coordinator 写入 `knowledge.yaml`。任务通过
+写 `verified`，不过写 `failed_retest`。
@@ -0,0 +1,269 @@
+# 派发 Prompt 模板（稳定核心）
+
+Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发复测。复制时替换尖括号占位符。模板与编排工具无关：Orca 模式用 `orca-adapter.md` 的命令投递，手动模式直接把文本发给对应 Agent。
+
+角色分工见 `roles-and-permissions.md`；闭环顺序见 `closed-loop.md`。
+
+派发时除了具体任务，Coordinator 应把对应角色的**能力要求**一并带上（`roles-and-permissions.md` §「三角色能力清单」的 Must Do / Must Not）。下面模板已内置关键条目，复制即可。
+
+---
+
+## 0. 可选 skills 路由（装了才用，不阻塞）
+
+如果 worker 所在环境已安装以下 skill，可在对应环节调用以获得更强 playbook；未安装则按 `roles-and-permissions.md` 的能力清单执行：
+
+- Coordinator 规划复杂需求：`/think` 或 `superpowers:brainstorming` / `writing-plans`。
+- Developer 排查缺陷：`/hunt` 或 `superpowers:systematic-debugging`；行为变更：`superpowers:test-driven-development`。
+- Test 复测 / 合并前检查：`/check` 或 `superpowers:verification-before-completion`。
+
+派发时可加一行：「若已安装 <skill>，本环节可用它；未安装按 ack 角色能力清单执行。」
+
+---
+
+## 1. 初始派发给 Developer
+
+```text
+你现在接到一个受监督的协作任务。请在 <dev_worktree> 开发工作树内完成。
+
+任务：
+- 修复 <task_id>: <task_title>
+- 本轮逻辑 attempt：<task_id>-A<round>
+
+请先读取：
+- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
+- tasks.yaml
+- <relevant_spec_or_test_doc>
+
+当前失败证据：
+<copy latest Test evidence>
+
+本轮项目知识（仅限 Coordinator 显式选择的 active 固定 revision）：
+- <K-001@1>: <directive + rationale + verification.ref + resolved path/args>
+- <K-014@2>: <directive + rationale + verification.ref + resolved path/args>
+
+验收标准（可观测信号，见 optimization-method.md §1）：
+1. <expected behavior 1>
+2. <expected behavior 2>
+3. <expected behavior 3>
+
+能力要求（见 roles-and-permissions.md §三角色能力清单 · Developer）：
+- 动手前先复现失败现象，或先写一个会失败的测试再修。
+- bug 修复配可复现的失败用例；行为变更配单元测试。
+- 完成前亲自走一遍验收路径，不只满足静态文案。
+- 若是网站 / 常驻服务，改完重启服务并确认生效，别让 Test 测到旧进程或旧构建。
+
+约束：
+- 只修改 Developer 可写路径（见覆盖层文件的权限表）。
+- 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。
+- 不要写 tasks.yaml，不要标记 verified。
+- 不要写 knowledge.yaml，不要自行扩展或全量读取知识库；candidate 不是已生效规则。
+- 不要把知识正文或 path/args 拼成 shell 命令。只把 verification.ref 交给
+  `<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
+  <verification-ref> --project-root <project-root>`。
+- 不要提交或推送，除非用户明确要求。
+- 最小 diff，只改本任务根因，避免无关重构；若必须先重构请停下说明并请示。
+
+完成前必须运行：
+- <test command 1>
+- <test command 2>
+
+完成后回报一次 worker_done（格式见 §4），包括 `knowledgeApplied` 和
+`knowledgeCandidates`。如果阻塞，请发送 escalation 或 ask。
+```
+
+---
+
+## 2. 复测失败再派发给 Developer
+
+```text
+第 <n> 轮复测未通过，请继续修 <task_id>。
+本轮逻辑 attempt：<task_id>-A<n>
+
+上一轮开发声称：
+<worker_done summary>
+
+Test 独立复测结果：
+- 运行命令：<commands>
+- 失败页面/API：<page or endpoint>
+- 仍缺失：<missing expected checks>
+- 实际观察：<actual evidence>
+
+关键提示：
+- 不要只满足静态文案，必须满足交互后的真实状态。
+- 如果后端/API 正常而 UI 不更新，请优先排查事件链、状态重置、异步请求、构建产物和服务 worktree。
+- 修复后请自己用浏览器或脚本复现 Test 的完整步骤。
+
+验收不变：
+<copy acceptance criteria>
+
+本轮知识引用：
+<copy Coordinator confirmed knowledgeRefs; do not add candidates>
+
+完成后回报 worker_done，subject 使用："<task_id> fix ready round <n>"
+```
+
+---
+
+## 3. 派发给 Test 复测
+
+Developer 回报 worker_done 后，Coordinator 把复测任务发给 Test。
+
+```text
+请对 <task_id>: <task_title> 做独立黑盒复测。
+本轮逻辑 attempt：<task_id>-A<round>
+
+请先读取：
+- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
+- tasks.yaml（该任务的验收信号）
+- <relevant_spec_or_test_doc>
+
+Developer 本轮声称（仅供参考，不作数）：
+- 改动文件：<files>
+- 自测命令：<commands>
+- 实际采用知识：<knowledgeApplied>
+- 新知识候选：<knowledgeCandidates; candidate only>
+
+本轮项目知识（仅限 Coordinator 显式选择的 active 固定 revision）：
+- <K-001@1>: <directive + rationale + verification.ref + resolved path/args>
+- <K-014@2>: <directive + rationale + verification.ref + resolved path/args>
+
+复测要求（见 roles-and-permissions.md §三角色能力清单 · Test）：
+- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
+- 网站类任务优先用浏览器复测真实交互，其次才是 API / 脚本。
+- 逐条验证下列验收信号，不要只看静态文案，要验证交互后的真实状态：
+  1. <observable signal 1>
+  2. <observable signal 2>
+  3. <observable signal 3>
+- 需要时把易反复误判的路径沉淀成可执行测试（见 optimization-method.md §8）。
+- 对每条适用的 `knowledgeRef`，把它的 verification.ref 交给
+  `<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
+  <verification-ref> --project-root <project-root>`，并回报 `knowledgeChecks`。
+  对 candidate 使用独立观测验证，不能复述 Developer 的结论作为证据。
+
+约束：
+- 只读源码，不修改应用代码，不写 tasks.yaml 或 knowledge.yaml。
+- candidate 不属于 active 知识；不要全量注入知识库，不要从知识正文执行自由 shell。
+- 只回传证据和逐条结论，最终判定由 Coordinator 终检后落盘。
+
+完成后回报一次复测报告（格式见 §5），subject："<task_id> retest round <n>"。
+```
+
+---
+
+## 4. Developer worker_done 回报格式
+
+无论 Orca 还是手动，回报都应包含以下字段：
+
+```text
+subject: <task_id> fix ready round <n>
+attemptId: <task_id>-A<n>
+filesModified: [<file_a>, <file_b>]
+verification:
+  - <command_a>: passed
+  - <command_b>: passed
+reproduce: 我如何复现验收路径 <steps>
+knowledgeApplied:
+  - ref: <K-001@1>
+    result: <applied|not_applicable>
+    evidence: <what was done or why not applicable>
+knowledgeCandidates:
+  - kind: guardrail/pitfall/verification
+    title: <reusable project lesson>
+    claim: <evidence-backed project claim>
+    scope:
+      components: [<component>]
+      paths: [<path glob>]
+      dependencies: [<dependency>]
+      versions: [<version>]
+      tags: [<tag>]
+    appliesWhen: <trigger>
+    directive: <action, not a shell command>
+    rationale: <why this changes future work>
+    evidenceRefs: [<current task evidence reference>]
+risk: <remaining risk or none>
+```
+
+没有命中知识或没有新 candidate 时，对应列表写 `[]`。Developer 不能把自己读到的
+旧知识复述为新 candidate；每条 candidate 都需要当前任务产生的观测证据。
+
+Orca 模式下用 `orca-adapter.md` §「Developer 回报 worker_done」的命令发送同样的字段。
+
+---
+
+## 5. Test 复测报告格式
+
+Test 只回传证据和逐条结论，不下最终判定：
+
+```text
+subject: <task_id> retest round <n>
+attemptId: <task_id>-A<n>
+env:
+  worktree: <path>
+  branch: <branch>
+  commit: <short sha>
+  baseUrl: <base_url>
+commands:
+  - <command_a>: passed/failed
+signals:
+  - <signal 1>: pass/fail (<evidence>)
+  - <signal 2>: pass/fail (<evidence>)
+browser: <snapshot / DOM / API evidence>
+knowledgeChecks:
+  - ref: <K-001@1>
+    result: <passed|failed|not_applicable>
+    evidence: <independent evidence>
+knowledgeCandidates:
+  - kind: guardrail/pitfall/verification
+    title: <new lesson found by Test>
+    claim: <evidence-backed project claim>
+    scope:
+      components: [<component>]
+      paths: [<path glob>]
+      dependencies: [<dependency>]
+      versions: [<version>]
+      tags: [<tag>]
+    appliesWhen: <trigger>
+    directive: <action, not a shell command>
+    rationale: <why this changes future work>
+    evidenceRefs: [<independent evidence reference>]
+conclusion: all-signals-pass / signals-failed
+notes: <observations, suspected cause, and independent candidate validation evidence>
+```
+
+没有适用项时列表写 `[]`。Test 的知识结论仍只是证据；只有 Coordinator 能写入或
+激活 `knowledge.yaml`。
+
+Orca 模式下用 `orca-adapter.md` §「Test 回报复测结果」的命令发送同样的字段。
+
+---
+
+## 6. Coordinator 最终报告模板
+
+```text
+本轮闭环完成。
+
+已验证（Test 复测通过 + 终检）：
+- <task_id>: <what passed>
+
+遗留：
+- <task_id>: 三轮仍未通过，已记录为 leftover。最后失败证据：<evidence>
+
+验证命令：
+- <command>: passed
+
+项目知识：
+- 本轮采用：<knowledgeRefs and checks>
+- 新增或更新：<active/stale/superseded entries written by Coordinator, or none>
+- 待验证 candidate：<remaining candidates or none>
+
+交付（未启用时写 n/a）：
+- run/profile/status：<delivery run id / profile / review_ready|released|blocked|failed>
+- PR/MR：<URL and head/base>
+- 产物：<reference, digest, destination>
+- 部署：<environment, health/rollback evidence>
+- 待审批或未完成：<approval/blocked step or none>
+
+工作树状态：
+- <repo_path>: <git status summary>
+- <dev_worktree>: <git status summary>
+```
@@ -0,0 +1,210 @@
+# 角色与权限（稳定核心）
+
+本文件是**角色模型、路径权限、任务状态机、完成定义**的单一事实源（SSOT）。其它文件只引用本文件，不重复定义。
+
+目标：让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
+
+---
+
+## 角色模型（三角色）
+
+ACK 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Developer 只实现**。关键属性是**验证者 ≠ 实现者**：Developer 不能给自己盖章，验证权在独立的 Test。
+
+| 角色 | 主要职责 | 验证方式 | 不应做的事 |
+|------|----------|----------|------------|
+| Coordinator (PM) | 需求拆解、定验收信号、排优先级、单写 `tasks.yaml` / `knowledge.yaml`、选择知识、向 Developer/Test 派发、跑三轮闭环、做最终 gate；经确认后编排可选交付 | 读 Test 证据并对齐原始意图（不亲自跑测试）；核对交付证据 | 修改源码、亲自复测、凭 worker_done 直接标 `verified`、自动激活未验证知识、把配置当作发布授权 |
+| Test | 黑盒复测、回归验证、执行知识检查、独立验证知识候选、沉淀可执行测试、产出证据 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、修改产品规格、写 `tasks.yaml` 或 `knowledge.yaml` |
+| Developer | 实现修复、写单元测试、运行构建和白盒验证、提名项目知识 | 单元测试、类型检查、构建、本地运行 | 修改产品规格与集成测试、写项目状态、标记 `verified`、绕过测试声称完成 |
+| User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
+
+**独立验证权归 Test。** Coordinator 不亲自复测，它读 Test 的证据，并对照任务的原始意图做一次终检（见「完成定义」）。`worker_done` 不等于完成的原则同时适用于 Developer 和 Test：结论只有落到 `tasks.yaml` 才算数。
+
+**模型档位（正交层）。** 三角色默认按成本分层：Coordinator 用强模型，Test 与 Developer 用中低模型，必要时升级。完整档位表与升级规则见 `model-routing.md`。Coordinator 用强模型但不跑测试，这一分工天然省 token 又不破坏「验证者 ≠ 实现者」。
+
+**一次性交付 Operator 不进入三角色开发闭环。** 用户显式调用 `$ack` 直接要求发布时，
+Coordinator 按 `delivery-routing.md` 选择低层 Skill，并把原始请求交给独立 Operator。
+Operator 与 Test 使用相同低成本模型/effort，但不承担独立复测；它只执行被选 Skill、
+遵守其授权边界并回传发布证据，且不得写 ACK 状态文件。
+
+---
+
+## 三角色能力清单（SSOT）
+
+上面的表定义了**边界**（谁能碰什么），这一节定义**能力**（每个角色到底该怎么做好自己的事）。每个角色用同一骨架描述：`Outcome`（产出什么）/ `Must Do`（必须做）/ `Must Not`（不能做）/ `Evidence`（拿什么证明）/ `Output`（交付格式）。派发 prompt 会引用这里，见 `prompt-templates.md`。
+
+这些是**通用工程习惯**，不含项目命令与路径；项目差异写在覆盖层文件（默认 `docs/ack/project.md`）。装了外部 skill 的环境可按每个角色末尾的「可选 skills」加速，未装则照本清单执行，不阻塞。
+
+### Coordinator (PM)：拆解与终检
+
+- **Outcome**：把一句话需求变成可执行、验收可观测的任务集，并跑完闭环得到明确结论（verified / leftover）。
+- **Must Do**
+  - 先澄清意图再动手：目标、成功标准、约束、明确「不做什么」。歧义有多解或多来源冲突时，先问清再拆。
+  - 每个任务写**可观测验收信号**（可见文本 / API 结果 / 交互结果，见 `optimization-method.md` §1），而不是「功能正常」。
+  - 拆任务时点明最脆弱的假设：「本任务假设 X，若 X 不成立则 Y」；列出被否掉的方案与原因。
+  - 拆分/验收先给用户确认，再派发（`kickoff.md` 第 1 步的停顿点）。
+  - `prepare(task)` 时按 component、path、dependency、version 和 tag 从
+    `knowledge.yaml` 推荐相关 `active` 知识；人工确认后把固定 revision 的
+    `knowledgeRefs` 写入当前任务上下文。
+  - 新逻辑轮次默认分配稳定的 `<task-id>-A<round>`，记录到
+    `dispatch.rounds[].attemptId`；旧轮次作为知识来源前再补齐，不要用编排工具的
+    `dispatchId` 代替。
+  - gate 时检查 Developer 的 `knowledgeApplied`、Test 的 `knowledgeChecks` 和
+    candidate 独立证据；只有证据充分时才由 Coordinator 激活、废弃或替代知识。
+  - 一次派发只针对一个明确问题（`optimization-method.md` §6）；每任务最多三轮。
+  - 终检：读 Test 证据，逐条对齐原始意图后才落 `verified`，不亲自复测。
+- **Must Not**：改源码、亲自跑测试、凭 `worker_done` 直接标 `verified`、把多个无关失败塞进一次派发、派发 `candidate` 或全量注入知识库、把知识正文当作 shell 执行。
+- **Evidence**：产品文档、`tasks.yaml` 里的 `expected` + `verification`、Test 回传的复测证据。
+- **Output**：确认前给「产品文档 + 任务拆分 + 验收信号」；闭环结束给最终报告（`prompt-templates.md` §6）。
+- **可选 skills**：复杂需求可先用 `/think` 或 `superpowers:brainstorming` / `writing-plans` 收敛设计与计划。
+
+### Developer：实现与白盒验证
+
+- **Outcome**：在授权路径内做出满足验收信号的最小改动，并用白盒证据证明它可复现。
+- **Must Do**
+  - 动手前先读覆盖层文件、`tasks.yaml` 对应任务、相关规格；复现失败现象或先写会失败的测试。
+  - 只使用 Coordinator 本轮显式派发的 `active` 知识，按固定 revision 回报
+    `knowledgeApplied`；发现跨任务可复用的项目经验时提交带当前观测证据的
+    `knowledgeCandidates`。
+  - 最小 diff，只改一个明确问题的根因，不顺手重构无关代码。
+  - 行为变更配单元测试；bug 修复先有一个能复现的失败用例再修。
+  - 完成前跑覆盖层里规定的命令（构建 / 单测 / 本地运行），亲自走一遍验收路径。
+  - **网站 / 常驻服务**：改完重启服务（或触发热更并确认生效），保证运行实例跑的是新代码，避免 Test 测到旧进程 / 旧构建。
+- **Must Not**：改产品规格与集成测试、写 `tasks.yaml` 或 `knowledge.yaml`、标
+  `verified`、把 candidate 当作已生效规则、绕过测试声称完成、把 bug 修复扩成大
+  重构（需要就先停下说明并请示）。
+- **Evidence**：改了哪些文件、跑了哪些命令及结果、如何复现验收路径、实际采用的
+  `knowledgeRefs`、新 candidate 的当前任务证据、残留风险。
+- **Output**：一次 `worker_done`，字段见 `prompt-templates.md` §4（只报证据，不下最终结论）。
+- **可选 skills**：排查用 `/hunt` 或 `superpowers:systematic-debugging`（先根因后修）；实现行为变更用 `superpowers:test-driven-development`。
+
+### Test：独立黑盒复测
+
+- **Outcome**：以独立视角复现验收路径，逐条给出通过/失败的可观测证据，供 Coordinator 终检。
+- **Must Do**
+  - 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 `closed-loop.md`），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
+  - 逐条验证验收信号，验证交互后的真实状态，而不是只看静态文案。
+  - 对 Coordinator 派发的每条 `knowledgeRef` 执行适用的额外检查，回报
+    `knowledgeChecks`；对本轮 candidate 使用独立观测验证，不能复述 Developer
+    结论当作证据。
+  - **网站类任务优先用浏览器复测**真实交互（点击 / 跳转 / 渲染），其次才是 API / 脚本；纯后端 / CLI 则以 API smoke 或脚本为主。
+  - 把最容易反复误判的路径沉淀成可执行测试（`optimization-method.md` §8）。
+  - 只回传证据 + 逐条结论，最终判定留给 Coordinator。
+- **Must Not**：改应用源码、改产品规格、写 `tasks.yaml` 或 `knowledge.yaml`、凭
+  Developer 的 `worker_done` 直接下结论、把 candidate 作为 active 知识执行。
+- **Evidence**：运行环境快照、命令结果、每条信号 pass/fail + 证据
+  （snapshot / DOM / API 结果）、每条适用知识的
+  `passed` / `failed` / `not_applicable` + 证据。
+- **Output**：一次复测报告，字段见 `prompt-templates.md` §5。
+- **可选 skills**：合并 / 发版前检查可用 `/check` 或 `superpowers:verification-before-completion`（证据先于结论）。
+
+---
+
+## 路径权限模板
+
+目标项目在自己的**覆盖层文件**中填入实际路径（模板见 `templates/project.template.md`；覆盖层默认 `docs/ack/project.md`，路径记在 `tasks.yaml` 的 `project.overlayFile`）。
+
+| 路径 | Coordinator | Test | Developer | 说明 |
+|------|:-----------:|:----:|:---------:|------|
+| `<spec_paths>` | R/W | Read-only | Read-only | PRD、API spec、设计文档，Coordinator（PM）拥有 |
+| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器用例、API smoke、回归清单，Test 拥有 |
+| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录，通常可 gitignore |
+| `<source_paths>` | Read-only | Read-only | R/W | 应用源码 |
+| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
+| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
+| `<local_config>` | Read-only | Read-only | Read-only | 本地私有配置，不提交 |
+| `tasks.yaml` | R/W | Read-only | Read-only | 见下方「项目状态写入约定」 |
+| `knowledge.yaml` | R/W | Read-only | Read-only | Coordinator 单写；Developer/Test 通过回报提名或验证 |
+| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 声明项目交付能力，不保存凭据或执行授权 |
+
+---
+
+## 任务状态机（SSOT）
+
+```text
+open
+  -> dispatched      （派发给 Developer）
+  -> fixed_by_dev    （Developer 声称已修）
+  -> retesting       （派发给 Test 复测）
+  -> verified        （Test 通过 + Coordinator 终检）
+```
+
+失败分支：
+
+```text
+dispatched     -> blocked
+retesting      -> failed_retest -> dispatched
+failed_retest（累计 3 轮） -> leftover
+```
+
+状态定义（所有状态都只由 Coordinator 写入 `tasks.yaml`，来源不同）：
+
+| 状态 | 依据来源 | 含义 |
+|------|----------|------|
+| `open` | Coordinator 自己发现/记录 | 已发现，等待处理 |
+| `dispatched` | Coordinator 派发动作 | 已派发给 Developer |
+| `fixed_by_dev` | Developer 的 worker_done | 开发声称已修复并提供白盒验证 |
+| `retesting` | Coordinator 派发动作 | 已派发给 Test，正在黑盒复测 |
+| `failed_retest` | Test 的复测报告 | 复测失败，可继续派发 Developer |
+| `verified` | Test 通过 + Coordinator 终检 | 复测通过且符合原始意图 |
+| `blocked` | Coordinator 判断 | 需要用户决策或外部条件 |
+| `leftover` | Coordinator 判断 | 累计 3 轮仍未通过，留给人工或专项处理 |
+
+三轮失败的处理细则见 `optimization-method.md` §「三轮失败策略」。
+
+`type: delivery-operation` 使用独立的短状态流：`open -> dispatched -> verified | blocked`。
+这里的 `verified` 只表示 Coordinator 已按被路由 Skill 的完成标准核对一次性交付证据，
+不表示代码经过 Test 复测，也不能作为普通功能任务的验证证据。远端部分成功不会自动
+重派；恢复规则见 `delivery-routing.md`。
+
+## 交付状态（与任务状态正交）
+
+任务进入 `verified` 后不再改写为发布或部署状态。可选交付的每次执行单独记录在
+`tasks.yaml.deliveryRuns`：
+
+```text
+planned -> running -> review_ready | released
+                    -> blocked | failed
+planned -> skipped
+```
+
+`review_ready` 表示 PR、preview 产物和已授权的非生产部署证据已经齐备，等待用户
+审核；`released` 只用于用户明确批准后的 stable 发布或 production 部署。交付失败
+不会否定已经独立验证的任务，但必须保留失败步骤、revision 与日志引用。完整顺序、
+审批点和恢复规则见 `delivery.md`。
+
+---
+
+## 项目状态写入约定（并发安全）
+
+`tasks.yaml` 是任务与交付运行事实源，`knowledge.yaml` 是跨任务项目知识事实源，
+`delivery.yaml` 是项目交付能力事实源。为避免多 Agent 并发写冲突：
+
+- **只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`**。Test 与 Developer
+  对它们都是只读的。
+- Developer 的实现状态、Test 的复测证据都通过消息回传（`worker_done` / 复测报告），由 Coordinator 落盘。
+- Developer 和 Test 只能通过 `knowledgeCandidates` 提名知识；candidate 保存在
+  当前任务证据中，在 Test 独立验证和 Coordinator gate 前不写成可派发的 active
+  知识。
+- 每次写入前先读最新内容，写入后更新顶层 `updatedAt`。
+- 单次写入应是一个任务的一次状态跃迁，避免整表批量重写。
+- `delivery.yaml` 只在用户显式要求维护配置时修改；运行只写
+  `tasks.yaml.deliveryRuns`，不能反向改写能力定义。
+
+全项目范围的 `must`、`never` 或权限类规则还需要 User / Decision Owner 确认。
+关键约束应最终下沉为测试、lint、CI 或正式规范；知识条目保存触发条件、原因和
+证据引用，不替代可执行控制。
+
+---
+
+## 完成定义（Definition of Done）
+
+一个任务只有同时满足以下条件，才能标记 `verified`：
+
+- Developer 已提供修改文件和白盒验证证据（`worker_done`）。
+- Test 在正确 worktree 和正确服务实例上独立复测通过（对齐检查见 `closed-loop.md`），并产出可观测证据。
+- 相关单元测试、构建、集成或浏览器检查通过。
+- 当前任务显式 `knowledgeRefs` 对应的必需 `knowledgeChecks` 已由 Test 覆盖；
+  未覆盖或检查引用无法解析时不能标记 `verified`。
+- **Coordinator 终检**：读 Test 的证据，确认它满足任务的原始意图与验收信号（不是重测，是审证据 + 对齐意图；避免"过了字面没过意图"）。
+- `tasks.yaml` 中记录了复测证据与 `resolution.verifiedBy`。
+- 用户可见行为符合验收标准。
@@ -0,0 +1,430 @@
+#!/usr/bin/env python3
+"""安全执行 knowledge.yaml 中已审查的 verificationRegistry 条目。
+
+本入口只接受 registry ID，不接受额外命令或参数。执行前只打开一次项目根目录
+fd，知识库、检查目标和子进程 cwd 都固定到该 fd；检查文件逐段以 O_NOFOLLOW
+打开后复制到匿名、尽可能 sealed 的稳定快照，再使用结构化 argv 和 shell=False
+启动，避免检查与执行之间被替换。
+
+退出码: 0..125 沿用检查结果 / 1 知识或执行失败 / 2 环境、路径或用法错误。
+"""
+
+from __future__ import annotations
+
+import argparse
+import fcntl
+import os
+import stat
+import subprocess
+import sys
+import tempfile
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from validate_knowledge import (  # type: ignore
+    infer_project_root,
+    load_yaml_text,
+    validate_all,
+)
+
+MAX_KNOWLEDGE_BYTES = 16 * 1024 * 1024
+MAX_TARGET_BYTES = 16 * 1024 * 1024
+
+
+def _project_root(
+    value: str | None,
+    knowledge_path: Path,
+) -> tuple[Path | None, str | None]:
+    inferred = infer_project_root(knowledge_path)
+    if value is not None:
+        candidate = Path(value).expanduser()
+        if not candidate.is_dir():
+            return None, f"项目根目录不存在: {candidate}"
+        resolved = candidate.resolve(strict=True)
+        if inferred is not None and resolved != inferred:
+            return (
+                None,
+                f"--project-root {resolved} 与 knowledge.yaml 推断的项目根目录 "
+                f"{inferred} 不一致",
+            )
+        return resolved, None
+    if inferred is None:
+        return None, "无法从 knowledge.yaml 确定现有项目根目录"
+    return inferred, None
+
+
+def _validate_knowledge_location(
+    knowledge_path: Path,
+    project_root: Path,
+) -> str | None:
+    expected = project_root / "docs" / "ack" / "knowledge.yaml"
+    lexical = Path(os.path.abspath(knowledge_path.expanduser()))
+    if lexical != expected:
+        return (
+            "只允许执行项目权威知识库 "
+            f"{expected}，当前输入为 {lexical}"
+        )
+    return None
+
+
+def _open_regular_beneath(
+    project_root: Path | int,
+    relative_path: str,
+    *,
+    require_executable: bool,
+) -> tuple[int | None, str | None]:
+    """从根目录 fd 逐段打开目标，不允许任一段通过 symlink 跳转。"""
+    if not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "O_DIRECTORY"):
+        return None, "当前平台不支持安全的 O_NOFOLLOW/O_DIRECTORY 路径解析"
+    parts = PurePosixPath(relative_path).parts
+    if (
+        not parts
+        or PurePosixPath(relative_path).is_absolute()
+        or any(part in {"", ".", ".."} for part in parts)
+    ):
+        return None, "检查目标必须是规范的项目内相对路径"
+
+    directory_fds: list[int] = []
+    target_fd: int | None = None
+    try:
+        root_fd = (
+            os.dup(project_root)
+            if isinstance(project_root, int)
+            else os.open(
+                project_root,
+                os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+            )
+        )
+        directory_fds.append(root_fd)
+        current_fd = root_fd
+        for segment in parts[:-1]:
+            current_fd = os.open(
+                segment,
+                os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+                dir_fd=current_fd,
+            )
+            directory_fds.append(current_fd)
+        target_fd = os.open(
+            parts[-1],
+            os.O_RDONLY | os.O_NOFOLLOW,
+            dir_fd=current_fd,
+        )
+        metadata = os.fstat(target_fd)
+        if not stat.S_ISREG(metadata.st_mode):
+            os.close(target_fd)
+            return None, "检查目标不是普通文件"
+        if require_executable and metadata.st_mode & 0o111 == 0:
+            os.close(target_fd)
+            return None, "检查目标不可执行"
+        return target_fd, None
+    except OSError as exc:
+        if target_fd is not None:
+            os.close(target_fd)
+        return None, f"检查目标不存在、不可访问或路径包含软链接: {exc}"
+    finally:
+        for directory_fd in reversed(directory_fds):
+            os.close(directory_fd)
+
+
+def _stable_metadata(before: os.stat_result, after: os.stat_result) -> bool:
+    fields = (
+        "st_dev",
+        "st_ino",
+        "st_mode",
+        "st_size",
+        "st_mtime_ns",
+        "st_ctime_ns",
+    )
+    return all(getattr(before, field) == getattr(after, field) for field in fields)
+
+
+def _read_stable_bytes(
+    source_fd: int,
+    *,
+    maximum: int,
+) -> tuple[bytes | None, str | None]:
+    before = os.fstat(source_fd)
+    if before.st_size > maximum:
+        return None, f"知识库超过大小上限 {maximum} bytes"
+    chunks: list[bytes] = []
+    total = 0
+    try:
+        os.lseek(source_fd, 0, os.SEEK_SET)
+        while True:
+            chunk = os.read(source_fd, min(1024 * 1024, maximum - total + 1))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            total += len(chunk)
+            if total > maximum:
+                return None, f"知识库超过大小上限 {maximum} bytes"
+    except OSError as exc:
+        return None, f"无法读取权威知识库快照: {exc}"
+    after = os.fstat(source_fd)
+    if not _stable_metadata(before, after):
+        return None, "权威知识库在读取期间发生变化，拒绝执行"
+    return b"".join(chunks), None
+
+
+def load_authoritative_knowledge(
+    project_root: Path | int,
+) -> tuple[dict[str, Any] | None, str | None]:
+    source_fd, open_error = _open_regular_beneath(
+        project_root,
+        "docs/ack/knowledge.yaml",
+        require_executable=False,
+    )
+    if open_error is not None or source_fd is None:
+        return None, open_error or "无法安全打开权威知识库"
+    try:
+        content, read_error = _read_stable_bytes(
+            source_fd,
+            maximum=MAX_KNOWLEDGE_BYTES,
+        )
+    finally:
+        os.close(source_fd)
+    if read_error is not None or content is None:
+        return None, read_error or "无法读取权威知识库"
+    try:
+        text = content.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return None, f"权威知识库不是有效 UTF-8: {exc}"
+    return load_yaml_text(text, "知识库"), None
+
+
+def _write_all(file_descriptor: int, chunk: bytes) -> None:
+    remaining = memoryview(chunk)
+    while remaining:
+        written = os.write(file_descriptor, remaining)
+        if written <= 0:
+            raise OSError("无法写入检查快照")
+        remaining = remaining[written:]
+
+
+def _snapshot_executable(source_fd: int) -> tuple[int | None, str | None]:
+    """复制到匿名快照；Linux 上进一步 seal，冻结本次执行内容。"""
+    before = os.fstat(source_fd)
+    if before.st_size > MAX_TARGET_BYTES:
+        return None, f"检查目标超过大小上限 {MAX_TARGET_BYTES} bytes"
+    snapshot_fd: int | None = None
+    seal_snapshot = all(
+        hasattr(owner, name)
+        for owner, name in (
+            (os, "memfd_create"),
+            (os, "MFD_ALLOW_SEALING"),
+            (os, "MFD_CLOEXEC"),
+            (fcntl, "F_ADD_SEALS"),
+            (fcntl, "F_SEAL_SEAL"),
+            (fcntl, "F_SEAL_SHRINK"),
+            (fcntl, "F_SEAL_GROW"),
+            (fcntl, "F_SEAL_WRITE"),
+        )
+    )
+    try:
+        if seal_snapshot:
+            snapshot_fd = os.memfd_create(  # type: ignore[attr-defined]
+                "ack-verification",
+                os.MFD_CLOEXEC | os.MFD_ALLOW_SEALING,  # type: ignore[attr-defined]
+            )
+        else:
+            snapshot_fd, snapshot_path = tempfile.mkstemp(
+                prefix="ack-verification-"
+            )
+            os.unlink(snapshot_path)
+
+        os.lseek(source_fd, 0, os.SEEK_SET)
+        total = 0
+        while True:
+            chunk = os.read(
+                source_fd,
+                min(1024 * 1024, MAX_TARGET_BYTES - total + 1),
+            )
+            if not chunk:
+                break
+            _write_all(snapshot_fd, chunk)
+            total += len(chunk)
+            if total > MAX_TARGET_BYTES:
+                os.close(snapshot_fd)
+                return None, f"检查目标超过大小上限 {MAX_TARGET_BYTES} bytes"
+        after = os.fstat(source_fd)
+        if not _stable_metadata(before, after):
+            os.close(snapshot_fd)
+            return None, "检查目标在创建执行快照期间发生变化，拒绝执行"
+
+        os.fchmod(snapshot_fd, before.st_mode & 0o777)
+        os.lseek(snapshot_fd, 0, os.SEEK_SET)
+        if seal_snapshot:
+            seals = (
+                fcntl.F_SEAL_SEAL
+                | fcntl.F_SEAL_SHRINK
+                | fcntl.F_SEAL_GROW
+                | fcntl.F_SEAL_WRITE
+            )
+            fcntl.fcntl(snapshot_fd, fcntl.F_ADD_SEALS, seals)
+        return snapshot_fd, None
+    except OSError as exc:
+        if snapshot_fd is not None:
+            os.close(snapshot_fd)
+        return None, f"无法创建稳定的检查执行快照: {exc}"
+
+
+def open_target(
+    data: dict[str, Any],
+    verification_ref: str,
+    project_root: Path | int,
+) -> tuple[int | None, list[str] | None, str | None]:
+    registry = data.get("verificationRegistry")
+    if not isinstance(registry, dict) or verification_ref not in registry:
+        return None, None, f"verification.ref {verification_ref!r} 未在 registry 注册"
+    target = registry.get(verification_ref)
+    if not isinstance(target, dict):
+        return None, None, f"verificationRegistry.{verification_ref} 不是对象"
+    relative_path = target.get("path")
+    args = target.get("args")
+    if not isinstance(relative_path, str) or not isinstance(args, list):
+        return None, None, f"verificationRegistry.{verification_ref} 结构无效"
+    if any(not isinstance(arg, str) for arg in args):
+        return (
+            None,
+            None,
+            f"verificationRegistry.{verification_ref}.args 必须是字符串数组",
+        )
+    source_fd, error = _open_regular_beneath(
+        project_root,
+        relative_path,
+        require_executable=True,
+    )
+    if error is not None or source_fd is None:
+        return None, None, error or "无法安全打开检查目标"
+    try:
+        target_fd, snapshot_error = _snapshot_executable(source_fd)
+    finally:
+        os.close(source_fd)
+    if snapshot_error is not None or target_fd is None:
+        return None, None, snapshot_error or "无法创建检查执行快照"
+    return target_fd, args, None
+
+
+def _fd_executable_path(target_fd: int) -> str | None:
+    for prefix in ("/proc/self/fd", "/dev/fd"):
+        candidate = f"{prefix}/{target_fd}"
+        if Path(candidate).exists():
+            return candidate
+    return None
+
+
+def _fd_directory_path(directory_fd: int) -> str | None:
+    for prefix in ("/proc/self/fd", "/dev/fd"):
+        candidate = f"{prefix}/{directory_fd}"
+        if Path(candidate).is_dir():
+            return candidate
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="执行 ACK verificationRegistry 中已审查的检查"
+    )
+    parser.add_argument("knowledge", help="knowledge.yaml 路径")
+    parser.add_argument("verification_ref", help="verificationRegistry 中的检查 ID")
+    parser.add_argument(
+        "--project-root",
+        help="项目根目录；默认从 knowledge.yaml 的 docs/ack 布局或 Git 推断",
+    )
+    args = parser.parse_args(argv)
+
+    knowledge_path = Path(args.knowledge)
+    project_root, root_error = _project_root(args.project_root, knowledge_path)
+    if project_root is None:
+        sys.stderr.write(f"{root_error or '无法确定现有项目根目录'}\n")
+        return 2
+    location_error = _validate_knowledge_location(knowledge_path, project_root)
+    if location_error is not None:
+        sys.stderr.write(f"{location_error}\n")
+        return 2
+
+    try:
+        project_root_fd = os.open(
+            project_root,
+            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+        )
+    except OSError as exc:
+        sys.stderr.write(f"无法安全打开项目根目录: {exc}\n")
+        return 2
+
+    try:
+        stable_root_path = _fd_directory_path(project_root_fd)
+        if stable_root_path is None:
+            sys.stderr.write("当前平台无法固定项目根目录文件描述符\n")
+            return 2
+        data, knowledge_error = load_authoritative_knowledge(project_root_fd)
+        if knowledge_error is not None or data is None:
+            sys.stderr.write(f"{knowledge_error or '无法读取权威知识库'}\n")
+            return 2
+        schema_path = (
+            Path(__file__).resolve().parent.parent
+            / "templates"
+            / "knowledge.schema.json"
+        )
+        errors, mode = validate_all(
+            data,
+            schema_path,
+            project_root=Path(stable_root_path),
+        )
+        if errors:
+            sys.stderr.write(f"知识库校验失败（{mode}），拒绝执行：\n")
+            for error in errors:
+                sys.stderr.write(f"  - {error}\n")
+            return 1
+
+        target_fd, target_args, error = open_target(
+            data,
+            args.verification_ref,
+            project_root_fd,
+        )
+        if error is not None or target_fd is None or target_args is None:
+            sys.stderr.write(f"{error or '无法解析检查目标'}\n")
+            return 2
+
+        try:
+            executable_path = _fd_executable_path(target_fd)
+            if executable_path is None:
+                sys.stderr.write(
+                    "当前平台无法从已打开的文件描述符安全执行检查\n"
+                )
+                return 2
+            environment = os.environ.copy()
+            environment["ACK_PROJECT_ROOT"] = stable_root_path
+            environment["ACK_PROJECT_ROOT_DISPLAY"] = str(project_root)
+            environment["ACK_VERIFICATION_REF"] = args.verification_ref
+            registry = data.get("verificationRegistry")
+            target = (
+                registry.get(args.verification_ref)
+                if isinstance(registry, dict)
+                else None
+            )
+            if isinstance(target, dict) and isinstance(target.get("path"), str):
+                environment["ACK_VERIFICATION_PATH"] = target["path"]
+            try:
+                completed = subprocess.run(
+                    [executable_path, *target_args],
+                    cwd=stable_root_path,
+                    env=environment,
+                    shell=False,
+                    check=False,
+                    pass_fds=(project_root_fd, target_fd),
+                )
+            except OSError as exc:
+                sys.stderr.write(f"检查启动失败: {exc}\n")
+                return 1
+        finally:
+            os.close(target_fd)
+    finally:
+        os.close(project_root_fd)
+    if 0 <= completed.returncode <= 125:
+        return completed.returncode
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""按显式项目上下文确定性选择 active ACK 知识。
+
+匹配采用大小写敏感 glob；entry 中每个非空 scope 维度都必须被查询上下文命中。
+scope.all=true 的条目始终命中并优先占用 --limit，数量超过预算时显式失败。其余
+结果按作用域具体程度及稳定引用排序。本脚本只输出数据，绝不执行 knowledge.yaml
+中的任何文本。
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import sys
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from validate_knowledge import (  # type: ignore
+    SCOPE_FIELDS,
+    infer_project_root,
+    load_yaml,
+    stable_ref,
+    validate_builtin_structure,
+    validate_semantics,
+)
+
+DEFAULT_LIMIT = 10
+MAX_LIMIT = 100
+
+
+def _path_glob_matches(value: str, pattern: str) -> bool:
+    """路径 glob：* 只匹配单段，只有完整的 ** 段可以跨越 /。"""
+    value_parts = tuple(value.split("/"))
+    pattern_parts = tuple(pattern.split("/"))
+
+    @lru_cache(maxsize=None)
+    def match(pattern_index: int, value_index: int) -> bool:
+        if pattern_index == len(pattern_parts):
+            return value_index == len(value_parts)
+        pattern_part = pattern_parts[pattern_index]
+        if pattern_part == "**":
+            return match(pattern_index + 1, value_index) or (
+                value_index < len(value_parts)
+                and match(pattern_index, value_index + 1)
+            )
+        return (
+            value_index < len(value_parts)
+            and fnmatch.fnmatchcase(value_parts[value_index], pattern_part)
+            and match(pattern_index + 1, value_index + 1)
+        )
+
+    return match(0, 0)
+
+
+def scope_matches(
+    scope: dict[str, Any], context: dict[str, list[str]]
+) -> bool:
+    if scope.get("all") is True:
+        return True
+    constrained = False
+    for field in SCOPE_FIELDS:
+        patterns = scope.get(field)
+        if not isinstance(patterns, list) or not patterns:
+            continue
+        constrained = True
+        values = context.get(field, [])
+        matcher = _path_glob_matches if field == "paths" else fnmatch.fnmatchcase
+        if not values or not any(
+            matcher(value, pattern)
+            for pattern in patterns
+            if isinstance(pattern, str)
+            for value in values
+        ):
+            return False
+    return constrained
+
+
+def _pattern_specificity(pattern: str) -> tuple[int, int, int, int, int]:
+    wildcard_count = sum(pattern.count(char) for char in ("*", "?", "["))
+    double_star_count = sum(1 for part in pattern.split("/") if part == "**")
+    literal_count = sum(char not in "*?[]!" for char in pattern)
+    exact = int(wildcard_count == 0)
+    depth = len(pattern.split("/"))
+    return (exact, literal_count, -double_star_count, -wildcard_count, depth)
+
+
+def _specificity(entry: dict[str, Any]) -> tuple[int, int, int, int, int, int, int]:
+    scope = entry.get("scope")
+    if not isinstance(scope, dict) or scope.get("all") is True:
+        return (0, 0, 0, 0, 0, 0, 0)
+    populated = 0
+    exact = 0
+    literal = 0
+    double_star = 0
+    wildcard = 0
+    depth = 0
+    extra_or_patterns = 0
+    for field in SCOPE_FIELDS:
+        values = scope.get(field)
+        if isinstance(values, list) and values:
+            populated += 1
+            scores = [
+                _pattern_specificity(value)
+                for value in values
+                if isinstance(value, str)
+            ]
+            if scores:
+                dimension_score = min(scores)
+                exact += dimension_score[0]
+                literal += dimension_score[1]
+                double_star += dimension_score[2]
+                wildcard += dimension_score[3]
+                depth += dimension_score[4]
+                extra_or_patterns += len(scores) - 1
+    return (
+        populated,
+        exact,
+        literal,
+        double_star,
+        wildcard,
+        depth,
+        -extra_or_patterns,
+    )
+
+
+def select_entries(
+    data: dict[str, Any],
+    context: dict[str, list[str]],
+    *,
+    limit: int = DEFAULT_LIMIT,
+) -> list[dict[str, Any]]:
+    if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= MAX_LIMIT:
+        raise ValueError(f"limit 必须在 1..{MAX_LIMIT} 之间")
+    entries = data.get("entries")
+    if not isinstance(entries, list):
+        return []
+    matched = [
+        entry
+        for entry in entries
+        if isinstance(entry, dict)
+        and entry.get("status") == "active"
+        and isinstance(entry.get("scope"), dict)
+        and scope_matches(entry["scope"], context)
+        and stable_ref(entry) is not None
+    ]
+    global_entries = [
+        entry
+        for entry in matched
+        if isinstance(entry.get("scope"), dict)
+        and entry["scope"].get("all") is True
+    ]
+    scoped_entries = [entry for entry in matched if entry not in global_entries]
+    global_entries.sort(key=lambda entry: stable_ref(entry) or "")
+    if len(global_entries) > limit:
+        raise ValueError(
+            f"命中的全项目知识有 {len(global_entries)} 条，超过 --limit={limit}；"
+            "提高 limit 后重试，不能静默丢弃全项目护栏"
+        )
+    scoped_entries.sort(
+        key=lambda entry: (
+            *(-part for part in _specificity(entry)),
+            stable_ref(entry) or "",
+        )
+    )
+    return [
+        *global_entries,
+        *scoped_entries[: limit - len(global_entries)],
+    ]
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="选择当前任务适用的 active ACK 知识")
+    parser.add_argument(
+        "knowledge", nargs="?", default="knowledge.yaml", help="知识库路径"
+    )
+    parser.add_argument("--component", action="append", default=[])
+    parser.add_argument("--path", action="append", default=[])
+    parser.add_argument("--dependency", action="append", default=[])
+    parser.add_argument("--version", action="append", default=[])
+    parser.add_argument("--tag", action="append", default=[])
+    parser.add_argument("--symbol", action="append", default=[])
+    parser.add_argument("--error-signature", action="append", default=[])
+    parser.add_argument("--limit", type=int, default=DEFAULT_LIMIT)
+    parser.add_argument(
+        "--project-root",
+        help="可选项目根目录，用于 verificationRegistry symlink containment 校验",
+    )
+    parser.add_argument(
+        "--format", choices=("json", "refs"), default="json", dest="output_format"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    knowledge_path = Path(args.knowledge)
+    if not knowledge_path.is_file():
+        sys.stderr.write(f"找不到知识库文件: {knowledge_path}\n")
+        return 2
+    if not 1 <= args.limit <= MAX_LIMIT:
+        sys.stderr.write(f"--limit 必须在 1..{MAX_LIMIT} 之间\n")
+        return 2
+
+    if args.project_root:
+        project_root = Path(args.project_root).expanduser()
+        if not project_root.is_dir():
+            sys.stderr.write(f"项目根目录不存在: {project_root}\n")
+            return 2
+        project_root = project_root.resolve()
+    else:
+        project_root = infer_project_root(knowledge_path)
+
+    data = load_yaml(knowledge_path, "知识库")
+    errors = validate_builtin_structure(data)
+    errors.extend(validate_semantics(data, project_root=project_root))
+    registry = data.get("verificationRegistry")
+    if project_root is None and isinstance(registry, dict) and registry:
+        errors.append(
+            "verificationRegistry 非空但无法确定项目根目录；请传入 --project-root"
+        )
+    errors = list(dict.fromkeys(errors))
+    if errors:
+        sys.stderr.write(f"知识库无效，拒绝选择，共 {len(errors)} 项：\n")
+        for error in errors:
+            sys.stderr.write(f"  - {error}\n")
+        return 1
+
+    context = {
+        "components": args.component,
+        "paths": args.path,
+        "dependencies": args.dependency,
+        "versions": args.version,
+        "tags": args.tag,
+        "symbols": args.symbol,
+        "errorSignatures": args.error_signature,
+    }
+    try:
+        selected = select_entries(data, context, limit=args.limit)
+    except ValueError as exc:
+        sys.stderr.write(f"知识选择失败: {exc}\n")
+        return 1
+    refs = [stable_ref(entry) for entry in selected]
+    if args.output_format == "refs":
+        if refs:
+            sys.stdout.write("\n".join(ref for ref in refs if ref) + "\n")
+        return 0
+
+    payload = {
+        "count": len(selected),
+        "limit": args.limit,
+        "refs": refs,
+        "entries": [
+            {
+                "ref": stable_ref(entry),
+                **entry,
+                "verificationTarget": (
+                    data.get("verificationRegistry", {}).get(
+                        entry.get("verification", {}).get("ref")
+                    )
+                    if isinstance(data.get("verificationRegistry"), dict)
+                    and isinstance(entry.get("verification"), dict)
+                    else None
+                ),
+            }
+            for entry in selected
+        ],
+    }
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,809 @@
+#!/usr/bin/env python3
+"""校验 ACK 项目交付契约。
+
+权威结构位于 templates/delivery.schema.json。jsonschema 是可选依赖；内置规则始终
+检查引用、步骤顺序、默认 profile 安全边界、敏感信息和仓库内入口路径。
+
+用法:
+    python3 validate_delivery.py docs/ack/delivery.yaml
+    python3 validate_delivery.py docs/ack/delivery.yaml \
+      --tasks docs/ack/tasks.yaml --project-root <project-root>
+
+退出码: 0 通过 / 1 校验失败 / 2 环境或用法错误。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import stat
+import sys
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from yaml_subset import (
+    DuplicateKeyError,
+    YamlSubsetError,
+    load_json_unique,
+    load_yaml_subset,
+    make_unique_pyyaml_loader,
+)
+
+
+ID_RE = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
+RELATIVE_PATH_RE = re.compile(r"^[A-Za-z0-9._/*?+-]+$")
+PLATFORM_RE = re.compile(r"^[a-z0-9]+/[A-Za-z0-9._-]+$")
+SECRET_NAME_RE = re.compile(r"^[A-Z][A-Z0-9_]{0,127}$")
+REMOTE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+
+TOP_LEVEL_FIELDS = {
+    "version",
+    "updatedAt",
+    "project",
+    "enabled",
+    "defaultProfile",
+    "entrypoints",
+    "artifacts",
+    "destinations",
+    "environments",
+    "profiles",
+}
+ENTRYPOINT_FIELDS = {
+    "kind",
+    "target",
+    "function",
+    "path",
+    "args",
+    "requiredSecrets",
+    "workingDirectory",
+    "timeoutSeconds",
+}
+ARTIFACT_FIELDS = {"type", "build", "outputs", "image", "platforms"}
+DESTINATION_FIELDS = {
+    "type",
+    "channel",
+    "registry",
+    "repository",
+    "endpoint",
+    "artifactName",
+    "upload",
+}
+ENVIRONMENT_FIELDS = {
+    "type",
+    "classification",
+    "target",
+    "deploy",
+    "healthCheck",
+    "rollback",
+    "mutex",
+}
+PROFILE_FIELDS = {"stopAt", "steps"}
+STEP_FIELDS = {
+    "id",
+    "action",
+    "entrypoint",
+    "artifact",
+    "destination",
+    "environment",
+    "gate",
+    "draft",
+    "remote",
+    "baseBranch",
+}
+
+ENTRYPOINT_KINDS = {"make", "just", "task", "dagger", "script"}
+ARTIFACT_TYPES = {"deb", "oci-image", "file"}
+DESTINATION_TYPES = {"apt-repository", "oci-registry", "ci-artifact"}
+CHANNELS = {"preview", "staging", "stable"}
+ENVIRONMENT_TYPES = {"ssh-host", "docker-compose", "kubernetes", "custom"}
+CLASSIFICATIONS = {"development", "staging", "production"}
+STOP_POINTS = {"verified", "review_ready", "released"}
+ACTIONS = {
+    "verify",
+    "pull-request",
+    "build",
+    "publish",
+    "deploy",
+    "health-check",
+    "approval",
+    "mark-ready",
+}
+ACTION_FIELDS = {
+    "verify": {"entrypoint"},
+    "pull-request": {"draft", "remote", "baseBranch"},
+    "build": {"artifact"},
+    "publish": {"artifact", "destination"},
+    "deploy": {"artifact", "environment"},
+    "health-check": {"environment"},
+    "approval": {"gate"},
+    "mark-ready": set(),
+}
+
+SECRET_PATTERNS = (
+    ("private key", re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----")),
+    ("GitHub token", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b")),
+    ("OpenAI-style token", re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b")),
+    ("AWS access key", re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b")),
+    ("URL credentials", re.compile(r"https?://[^/\s:@]+:[^/\s@]+@")),
+    (
+        "inline secret assignment",
+        re.compile(
+            r"(?i)\b(?:api[_-]?key|access[_-]?token|password|secret|token)"
+            r"\s*[:=]\s*[\"']?[^\s,\"']{8,}"
+        ),
+    ),
+)
+
+
+def _nonempty(value: Any) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _mapping(value: Any) -> bool:
+    return isinstance(value, dict)
+
+
+def _reject_unknown(
+    value: dict[str, Any],
+    allowed: set[str],
+    where: str,
+    errors: list[str],
+) -> None:
+    for field in sorted(set(value) - allowed):
+        errors.append(f"{where}: 未知字段 {field!r}")
+
+
+def _load_document(path: Path, label: str) -> dict[str, Any]:
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        sys.stderr.write(f"{label}读取失败: {exc}\n")
+        raise SystemExit(1)
+
+    if path.suffix.lower() == ".json":
+        try:
+            data = load_json_unique(content)
+        except (json.JSONDecodeError, DuplicateKeyError) as exc:
+            sys.stderr.write(f"{label} JSON 解析失败: {exc}\n")
+            raise SystemExit(1)
+    else:
+        try:
+            import yaml  # type: ignore
+        except ImportError:
+            try:
+                data = load_yaml_subset(content)
+            except YamlSubsetError as exc:
+                sys.stderr.write(f"{label} YAML 子集解析失败: {exc}\n")
+                raise SystemExit(1)
+        else:
+            try:
+                data = yaml.load(content, Loader=make_unique_pyyaml_loader(yaml))
+            except yaml.YAMLError as exc:  # type: ignore
+                sys.stderr.write(f"{label} YAML 解析失败: {exc}\n")
+                raise SystemExit(1)
+
+    if not isinstance(data, dict):
+        sys.stderr.write(f"{label}顶层必须是对象（mapping）\n")
+        raise SystemExit(1)
+    return data
+
+
+def _safe_relative_path(value: Any, *, allow_glob: bool = False) -> bool:
+    if not _nonempty(value) or value.startswith("/") or "\\" in value:
+        return False
+    if not RELATIVE_PATH_RE.fullmatch(value):
+        return False
+    if not allow_glob and any(marker in value for marker in "*?"):
+        return False
+    parts = PurePosixPath(value).parts
+    return ".." not in parts and all(part not in {"", "/"} for part in parts)
+
+
+def _safe_branch_name(value: Any) -> bool:
+    if not _nonempty(value) or len(value) > 255:
+        return False
+    if value == "@" or value.startswith(("/", ".", "-")):
+        return False
+    if value.endswith(("/", ".", ".lock")):
+        return False
+    if "@{" in value or ".." in value or "//" in value:
+        return False
+    return re.search(r"[\x00-\x20\x7f~^:?*\[\\]", value) is None
+
+
+def _validate_path_binding(
+    project_root: Path,
+    relative_path: str,
+    where: str,
+    *,
+    expected: str,
+) -> list[str]:
+    errors: list[str] = []
+    current = project_root
+    parts = PurePosixPath(relative_path).parts
+    if relative_path == ".":
+        parts = ()
+    for index, part in enumerate(parts):
+        current = current / part
+        try:
+            metadata = current.lstat()
+        except FileNotFoundError:
+            return [f"{where}: 路径不存在: {relative_path!r}"]
+        except OSError as exc:
+            return [f"{where}: 路径不可访问: {relative_path!r}: {exc}"]
+        if stat.S_ISLNK(metadata.st_mode):
+            return [f"{where}: 路径不能包含 symlink: {relative_path!r}"]
+        if index < len(parts) - 1 and not stat.S_ISDIR(metadata.st_mode):
+            return [f"{where}: 中间路径不是目录: {relative_path!r}"]
+
+    try:
+        metadata
+    except UnboundLocalError:
+        metadata = project_root.lstat()
+    if expected == "directory" and not stat.S_ISDIR(metadata.st_mode):
+        errors.append(f"{where}: 必须指向目录: {relative_path!r}")
+    if expected == "executable":
+        if not stat.S_ISREG(metadata.st_mode):
+            errors.append(f"{where}: 必须指向普通文件: {relative_path!r}")
+        elif metadata.st_mode & 0o111 == 0:
+            errors.append(f"{where}: 脚本不可执行: {relative_path!r}")
+    return errors
+
+
+def _scan_secrets(value: Any, where: str, errors: list[str]) -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            _scan_secrets(item, f"{where}.{key}", errors)
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            _scan_secrets(item, f"{where}[{index}]", errors)
+        return
+    if not isinstance(value, str):
+        return
+    for label, pattern in SECRET_PATTERNS:
+        if pattern.search(value):
+            errors.append(f"{where}: 疑似包含敏感信息（{label}）")
+
+
+def _validate_ids(values: Any, where: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(values, dict):
+        errors.append(f"{where}: 必须是对象")
+        return {}
+    for key in values:
+        if not isinstance(key, str) or ID_RE.fullmatch(key) is None:
+            errors.append(f"{where}: ID {key!r} 必须使用小写连字符格式")
+    return values
+
+
+def _validate_entrypoints(
+    values: dict[str, Any],
+    errors: list[str],
+    project_root: Path | None,
+) -> None:
+    for entrypoint_id, value in values.items():
+        where = f"entrypoints.{entrypoint_id}"
+        if not _mapping(value):
+            errors.append(f"{where}: 必须是对象")
+            continue
+        _reject_unknown(value, ENTRYPOINT_FIELDS, where, errors)
+        kind = value.get("kind")
+        if kind not in ENTRYPOINT_KINDS:
+            errors.append(f"{where}.kind: 必须是 {sorted(ENTRYPOINT_KINDS)}")
+        required_selector = {
+            "make": "target",
+            "just": "target",
+            "task": "target",
+            "dagger": "function",
+            "script": "path",
+        }.get(kind)
+        for selector in ("target", "function", "path"):
+            if selector == required_selector:
+                if not _nonempty(value.get(selector)):
+                    errors.append(f"{where}.{selector}: {kind} 入口必须填写非空值")
+            elif selector in value:
+                errors.append(f"{where}.{selector}: kind={kind!r} 不允许此字段")
+
+        args = value.get("args")
+        if not isinstance(args, list) or any(not isinstance(item, str) for item in args):
+            errors.append(f"{where}.args: 必须是字符串列表")
+        required_secrets = value.get("requiredSecrets")
+        if (
+            not isinstance(required_secrets, list)
+            or any(
+                not isinstance(item, str) or SECRET_NAME_RE.fullmatch(item) is None
+                for item in required_secrets
+            )
+            or (
+                isinstance(required_secrets, list)
+                and len(required_secrets) != len(set(required_secrets))
+            )
+        ):
+            errors.append(
+                f"{where}.requiredSecrets: 必须是唯一的大写 secret 名称列表"
+            )
+        working_directory = value.get("workingDirectory")
+        if not _safe_relative_path(working_directory):
+            errors.append(f"{where}.workingDirectory: 必须是安全的仓库内相对路径")
+        timeout = value.get("timeoutSeconds")
+        if (
+            not isinstance(timeout, int)
+            or isinstance(timeout, bool)
+            or not 1 <= timeout <= 86400
+        ):
+            errors.append(f"{where}.timeoutSeconds: 必须是 1..86400 的整数")
+
+        if kind == "script" and not _safe_relative_path(value.get("path")):
+            errors.append(f"{where}.path: 必须是安全的仓库内相对路径")
+        if project_root is not None:
+            if _safe_relative_path(working_directory):
+                errors.extend(
+                    _validate_path_binding(
+                        project_root,
+                        working_directory,
+                        f"{where}.workingDirectory",
+                        expected="directory",
+                    )
+                )
+            if kind == "script" and _safe_relative_path(value.get("path")):
+                errors.extend(
+                    _validate_path_binding(
+                        project_root,
+                        value["path"],
+                        f"{where}.path",
+                        expected="executable",
+                    )
+                )
+
+
+def _validate_artifacts(
+    values: dict[str, Any],
+    entrypoints: dict[str, Any],
+    errors: list[str],
+) -> None:
+    for artifact_id, value in values.items():
+        where = f"artifacts.{artifact_id}"
+        if not _mapping(value):
+            errors.append(f"{where}: 必须是对象")
+            continue
+        _reject_unknown(value, ARTIFACT_FIELDS, where, errors)
+        artifact_type = value.get("type")
+        if artifact_type not in ARTIFACT_TYPES:
+            errors.append(f"{where}.type: 必须是 {sorted(ARTIFACT_TYPES)}")
+        build = value.get("build")
+        if build not in entrypoints:
+            errors.append(f"{where}.build: 未定义 entrypoint {build!r}")
+        outputs = value.get("outputs")
+        if artifact_type in {"deb", "file"}:
+            if (
+                not isinstance(outputs, list)
+                or not outputs
+                or any(not _safe_relative_path(item, allow_glob=True) for item in outputs)
+            ):
+                errors.append(f"{where}.outputs: deb/file 必须填写安全的产物路径列表")
+            if "image" in value or "platforms" in value:
+                errors.append(f"{where}: deb/file 不允许 image 或 platforms")
+        if artifact_type == "oci-image":
+            if not _nonempty(value.get("image")):
+                errors.append(f"{where}.image: oci-image 必须填写镜像名")
+            platforms = value.get("platforms")
+            if (
+                not isinstance(platforms, list)
+                or not platforms
+                or any(not isinstance(item, str) or PLATFORM_RE.fullmatch(item) is None for item in platforms)
+                or len(platforms) != len(set(platforms))
+            ):
+                errors.append(f"{where}.platforms: 必须是唯一的 os/arch 列表")
+            if "outputs" in value:
+                errors.append(f"{where}: oci-image 不允许 outputs")
+
+
+def _validate_destinations(
+    values: dict[str, Any],
+    entrypoints: dict[str, Any],
+    errors: list[str],
+) -> None:
+    for destination_id, value in values.items():
+        where = f"destinations.{destination_id}"
+        if not _mapping(value):
+            errors.append(f"{where}: 必须是对象")
+            continue
+        _reject_unknown(value, DESTINATION_FIELDS, where, errors)
+        destination_type = value.get("type")
+        if destination_type not in DESTINATION_TYPES:
+            errors.append(f"{where}.type: 必须是 {sorted(DESTINATION_TYPES)}")
+        type_fields = {
+            "apt-repository": {"endpoint", "repository"},
+            "oci-registry": {"registry", "repository"},
+            "ci-artifact": {"artifactName"},
+        }.get(destination_type, set())
+        allowed_fields = {"type", "channel", "upload"} | type_fields
+        for field in sorted(set(value) - allowed_fields):
+            errors.append(f"{where}.{field}: type={destination_type!r} 不允许此字段")
+        if value.get("channel") not in CHANNELS:
+            errors.append(f"{where}.channel: 必须是 {sorted(CHANNELS)}")
+        upload = value.get("upload")
+        if upload is not None and upload not in entrypoints:
+            errors.append(f"{where}.upload: 未定义 entrypoint {upload!r}")
+        if destination_type == "apt-repository":
+            if not _nonempty(value.get("endpoint")):
+                errors.append(f"{where}.endpoint: APT 目标必须填写服务地址")
+            if not _nonempty(value.get("repository")):
+                errors.append(f"{where}.repository: APT 目标必须填写仓库名")
+        if destination_type == "oci-registry":
+            for field in ("registry", "repository"):
+                if not _nonempty(value.get(field)):
+                    errors.append(f"{where}.{field}: OCI 目标必须填写非空值")
+        if destination_type == "ci-artifact" and not _nonempty(value.get("artifactName")):
+            errors.append(f"{where}.artifactName: CI artifact 必须填写名称")
+
+
+def _validate_environments(
+    values: dict[str, Any],
+    entrypoints: dict[str, Any],
+    errors: list[str],
+) -> None:
+    for environment_id, value in values.items():
+        where = f"environments.{environment_id}"
+        if not _mapping(value):
+            errors.append(f"{where}: 必须是对象")
+            continue
+        _reject_unknown(value, ENVIRONMENT_FIELDS, where, errors)
+        if value.get("type") not in ENVIRONMENT_TYPES:
+            errors.append(f"{where}.type: 必须是 {sorted(ENVIRONMENT_TYPES)}")
+        classification = value.get("classification")
+        if classification not in CLASSIFICATIONS:
+            errors.append(f"{where}.classification: 必须是 {sorted(CLASSIFICATIONS)}")
+        if not _nonempty(value.get("target")):
+            errors.append(f"{where}.target: 必须是非空目标别名")
+        for field in ("deploy", "healthCheck"):
+            reference = value.get(field)
+            if reference not in entrypoints:
+                errors.append(f"{where}.{field}: 未定义 entrypoint {reference!r}")
+        rollback = value.get("rollback")
+        if rollback is not None and rollback not in entrypoints:
+            errors.append(f"{where}.rollback: 未定义 entrypoint {rollback!r}")
+        if classification == "production" and rollback is None:
+            errors.append(f"{where}.rollback: production 环境必须提供回滚入口")
+        if not _nonempty(value.get("mutex")):
+            errors.append(f"{where}.mutex: 必须填写部署互斥锁 ID")
+
+
+def _artifact_destination_compatible(artifact_type: str, destination_type: str) -> bool:
+    return destination_type in {
+        "deb": {"apt-repository", "ci-artifact"},
+        "oci-image": {"oci-registry", "ci-artifact"},
+        "file": {"ci-artifact"},
+    }.get(artifact_type, set())
+
+
+def _validate_profiles(
+    values: dict[str, Any],
+    *,
+    default_profile: Any,
+    entrypoints: dict[str, Any],
+    artifacts: dict[str, Any],
+    destinations: dict[str, Any],
+    environments: dict[str, Any],
+    errors: list[str],
+) -> None:
+    for profile_id, value in values.items():
+        where = f"profiles.{profile_id}"
+        if not _mapping(value):
+            errors.append(f"{where}: 必须是对象")
+            continue
+        _reject_unknown(value, PROFILE_FIELDS, where, errors)
+        stop_at = value.get("stopAt")
+        if stop_at not in STOP_POINTS:
+            errors.append(f"{where}.stopAt: 必须是 {sorted(STOP_POINTS)}")
+        steps = value.get("steps")
+        if not isinstance(steps, list):
+            errors.append(f"{where}.steps: 必须是列表")
+            continue
+
+        seen_step_ids: set[str] = set()
+        built_artifacts: set[str] = set()
+        published_artifacts: set[str] = set()
+        deployed_environments: set[str] = set()
+        approvals: set[str] = set()
+        has_pull_request = False
+        has_mark_ready = False
+
+        for index, step in enumerate(steps):
+            step_where = f"{where}.steps[{index}]"
+            if not _mapping(step):
+                errors.append(f"{step_where}: 必须是对象")
+                continue
+            _reject_unknown(step, STEP_FIELDS, step_where, errors)
+            step_id = step.get("id")
+            if not isinstance(step_id, str) or ID_RE.fullmatch(step_id) is None:
+                errors.append(f"{step_where}.id: 必须使用小写连字符格式")
+            elif step_id in seen_step_ids:
+                errors.append(f"{step_where}.id: 不能重复 {step_id!r}")
+            else:
+                seen_step_ids.add(step_id)
+
+            action = step.get("action")
+            if action not in ACTIONS:
+                errors.append(f"{step_where}.action: 必须是 {sorted(ACTIONS)}")
+                continue
+            required_fields = ACTION_FIELDS[action]
+            for field in sorted(required_fields):
+                if field not in step:
+                    errors.append(f"{step_where}.{field}: action={action!r} 时必填")
+            allowed_fields = {"id", "action"} | required_fields
+            for field in sorted(set(step) - allowed_fields):
+                errors.append(f"{step_where}.{field}: action={action!r} 不允许此字段")
+
+            if action == "verify" and step.get("entrypoint") not in entrypoints:
+                errors.append(
+                    f"{step_where}.entrypoint: 未定义 entrypoint {step.get('entrypoint')!r}"
+                )
+            if action == "pull-request":
+                if not isinstance(step.get("draft"), bool):
+                    errors.append(f"{step_where}.draft: 必须是布尔值")
+                if (
+                    not isinstance(step.get("remote"), str)
+                    or REMOTE_RE.fullmatch(step["remote"]) is None
+                ):
+                    errors.append(f"{step_where}.remote: 必须是安全的 Git remote 名称")
+                if not _safe_branch_name(step.get("baseBranch")):
+                    errors.append(f"{step_where}.baseBranch: 必须是安全的 Git 分支名")
+                has_pull_request = True
+            if action == "build":
+                artifact_id = step.get("artifact")
+                if artifact_id not in artifacts:
+                    errors.append(f"{step_where}.artifact: 未定义 artifact {artifact_id!r}")
+                else:
+                    built_artifacts.add(artifact_id)
+            if action == "publish":
+                artifact_id = step.get("artifact")
+                destination_id = step.get("destination")
+                if artifact_id not in artifacts:
+                    errors.append(f"{step_where}.artifact: 未定义 artifact {artifact_id!r}")
+                elif artifact_id not in built_artifacts:
+                    errors.append(f"{step_where}: publish 前必须先 build {artifact_id!r}")
+                if destination_id not in destinations:
+                    errors.append(
+                        f"{step_where}.destination: 未定义 destination {destination_id!r}"
+                    )
+                elif artifact_id in artifacts:
+                    artifact_type = artifacts[artifact_id].get("type")
+                    destination_type = destinations[destination_id].get("type")
+                    if not _artifact_destination_compatible(artifact_type, destination_type):
+                        errors.append(
+                            f"{step_where}: artifact {artifact_type!r} 不能发布到 "
+                            f"{destination_type!r}"
+                        )
+                    if destinations[destination_id].get("channel") == "stable" and "release" not in approvals:
+                        errors.append(f"{step_where}: stable 发布前必须有 release approval")
+                    published_artifacts.add(artifact_id)
+            if action == "deploy":
+                artifact_id = step.get("artifact")
+                environment_id = step.get("environment")
+                if artifact_id not in artifacts:
+                    errors.append(f"{step_where}.artifact: 未定义 artifact {artifact_id!r}")
+                elif artifact_id not in built_artifacts:
+                    errors.append(f"{step_where}: deploy 前必须先 build {artifact_id!r}")
+                if environment_id not in environments:
+                    errors.append(
+                        f"{step_where}.environment: 未定义 environment {environment_id!r}"
+                    )
+                else:
+                    classification = environments[environment_id].get("classification")
+                    if classification == "production" and "production" not in approvals:
+                        errors.append(f"{step_where}: production 部署前必须有 production approval")
+                    if (
+                        classification == "production"
+                        and artifact_id not in published_artifacts
+                    ):
+                        errors.append(f"{step_where}: production 部署前必须先 publish 同一产物")
+                    deployed_environments.add(environment_id)
+            if action == "health-check":
+                environment_id = step.get("environment")
+                if environment_id not in environments:
+                    errors.append(
+                        f"{step_where}.environment: 未定义 environment {environment_id!r}"
+                    )
+                elif environment_id not in deployed_environments:
+                    errors.append(
+                        f"{step_where}: health-check 前必须先 deploy {environment_id!r}"
+                    )
+            if action == "approval":
+                gate = step.get("gate")
+                if gate not in {"release", "production"}:
+                    errors.append(f"{step_where}.gate: 必须是 release/production")
+                else:
+                    if gate == "release" and not built_artifacts:
+                        errors.append(f"{step_where}: release approval 前必须先 build 产物")
+                    if gate == "production" and not published_artifacts:
+                        errors.append(f"{step_where}: production approval 前必须先 publish 产物")
+                    approvals.add(gate)
+            if action == "mark-ready":
+                if not has_pull_request:
+                    errors.append(f"{step_where}: mark-ready 前必须先创建 pull-request")
+                has_mark_ready = True
+                if index != len(steps) - 1:
+                    errors.append(f"{step_where}: mark-ready 必须是 profile 最后一步")
+
+        if stop_at in {"review_ready", "released"} and (
+            not has_pull_request or not has_mark_ready
+        ):
+            errors.append(
+                f"{where}: {stop_at} 必须包含 pull-request 和末尾 mark-ready"
+            )
+        if stop_at == "released" and not ({"release", "production"} & approvals):
+            errors.append(f"{where}: released profile 必须包含 release 或 production approval")
+
+        if profile_id == default_profile:
+            if stop_at != "review_ready":
+                errors.append(f"{where}: defaultProfile 必须停在 review_ready")
+            used_destinations = {
+                step.get("destination")
+                for step in steps
+                if isinstance(step, dict) and step.get("action") == "publish"
+            }
+            used_environments = {
+                step.get("environment")
+                for step in steps
+                if isinstance(step, dict) and step.get("action") == "deploy"
+            }
+            if any(
+                destinations.get(item, {}).get("channel") == "stable"
+                for item in used_destinations
+            ):
+                errors.append(f"{where}: defaultProfile 不能发布 stable 目标")
+            if any(
+                environments.get(item, {}).get("classification") == "production"
+                for item in used_environments
+            ):
+                errors.append(f"{where}: defaultProfile 不能部署 production 环境")
+
+
+def validate_builtin(data: dict[str, Any], project_root: Path | None = None) -> list[str]:
+    errors: list[str] = []
+    _reject_unknown(data, TOP_LEVEL_FIELDS, "<root>", errors)
+
+    if data.get("version") != 1 or isinstance(data.get("version"), bool):
+        errors.append("version 必须是整数 1")
+    if "updatedAt" in data and not _nonempty(data.get("updatedAt")):
+        errors.append("updatedAt 必须是非空字符串")
+    project = data.get("project")
+    if not _mapping(project):
+        errors.append("project 必须是对象")
+        project = {}
+    else:
+        _reject_unknown(project, {"name"}, "project", errors)
+        if not _nonempty(project.get("name")):
+            errors.append("project.name 必须是非空字符串")
+
+    enabled = data.get("enabled")
+    if not isinstance(enabled, bool):
+        errors.append("enabled 必须是布尔值")
+    default_profile = data.get("defaultProfile")
+    if default_profile is not None and (
+        not isinstance(default_profile, str) or ID_RE.fullmatch(default_profile) is None
+    ):
+        errors.append("defaultProfile 必须是 null 或小写连字符 ID")
+
+    entrypoints = _validate_ids(data.get("entrypoints"), "entrypoints", errors)
+    artifacts = _validate_ids(data.get("artifacts"), "artifacts", errors)
+    destinations = _validate_ids(data.get("destinations"), "destinations", errors)
+    environments = _validate_ids(data.get("environments"), "environments", errors)
+    profiles = _validate_ids(data.get("profiles"), "profiles", errors)
+
+    _validate_entrypoints(entrypoints, errors, project_root)
+    _validate_artifacts(artifacts, entrypoints, errors)
+    _validate_destinations(destinations, entrypoints, errors)
+    _validate_environments(environments, entrypoints, errors)
+    _validate_profiles(
+        profiles,
+        default_profile=default_profile,
+        entrypoints=entrypoints,
+        artifacts=artifacts,
+        destinations=destinations,
+        environments=environments,
+        errors=errors,
+    )
+
+    if enabled:
+        if default_profile not in profiles:
+            errors.append("enabled=true 时 defaultProfile 必须引用已定义 profile")
+        elif not profiles[default_profile].get("steps"):
+            errors.append("enabled=true 时 defaultProfile.steps 不能为空")
+    elif default_profile is not None and default_profile not in profiles:
+        errors.append("defaultProfile 必须引用已定义 profile")
+
+    _scan_secrets(data, "<root>", errors)
+    return errors
+
+
+def validate_tasks_link(delivery: dict[str, Any], tasks: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    project = tasks.get("project")
+    if not isinstance(project, dict):
+        return ["tasks.project 必须是对象"]
+    if project.get("deliveryFile") != "docs/ack/delivery.yaml":
+        errors.append("tasks.project.deliveryFile 必须固定为 docs/ack/delivery.yaml")
+    delivery_project = delivery.get("project")
+    if (
+        isinstance(delivery_project, dict)
+        and _nonempty(delivery_project.get("name"))
+        and _nonempty(project.get("name"))
+        and delivery_project["name"] != project["name"]
+    ):
+        errors.append("delivery.project.name 必须与 tasks.project.name 一致")
+    if not isinstance(tasks.get("deliveryRuns"), list):
+        errors.append("引用 deliveryFile 的任务板必须包含 deliveryRuns 列表")
+    return errors
+
+
+def validate_with_schema(data: dict[str, Any], schema_path: Path) -> list[str]:
+    import jsonschema  # type: ignore
+
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    validator = jsonschema.Draft7Validator(schema)
+    errors = []
+    for error in sorted(validator.iter_errors(data), key=lambda item: list(item.path)):
+        location = "/".join(str(part) for part in error.path) or "<root>"
+        errors.append(f"[schema] {location}: {error.message}")
+    return errors
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="校验 ACK 项目交付契约")
+    parser.add_argument("delivery", nargs="?", default="docs/ack/delivery.yaml")
+    parser.add_argument("--tasks", help="关联的 docs/ack/tasks.yaml")
+    parser.add_argument("--project-root", help="项目根目录；提供后检查入口路径")
+    parser.add_argument("--schema", help="delivery.schema.json 路径（默认自动探测）")
+    args = parser.parse_args(argv)
+
+    delivery_path = Path(args.delivery)
+    if not delivery_path.is_file():
+        sys.stderr.write(f"找不到交付契约: {delivery_path}\n")
+        return 2
+    project_root = Path(args.project_root).resolve() if args.project_root else None
+    if project_root is not None and not project_root.is_dir():
+        sys.stderr.write(f"项目根目录不存在: {project_root}\n")
+        return 2
+
+    delivery = _load_document(delivery_path, "交付契约")
+    errors = validate_builtin(delivery, project_root)
+
+    if args.tasks:
+        tasks_path = Path(args.tasks)
+        if not tasks_path.is_file():
+            sys.stderr.write(f"找不到任务板: {tasks_path}\n")
+            return 2
+        tasks = _load_document(tasks_path, "任务板")
+        errors.extend(validate_tasks_link(delivery, tasks))
+
+    schema_path = (
+        Path(args.schema)
+        if args.schema
+        else Path(__file__).resolve().parent.parent / "templates" / "delivery.schema.json"
+    )
+    if args.schema and not schema_path.is_file():
+        sys.stderr.write(f"找不到 schema: {schema_path}\n")
+        return 2
+    if schema_path.is_file():
+        try:
+            errors.extend(validate_with_schema(delivery, schema_path))
+        except ImportError:
+            sys.stderr.write("提示: 未安装 jsonschema，仅执行内置语义规则\n")
+        except (OSError, json.JSONDecodeError) as exc:
+            sys.stderr.write(f"schema 读取失败: {exc}\n")
+            return 2
+
+    if errors:
+        for error in errors:
+            sys.stderr.write(f"- {error}\n")
+        return 1
+
+    sys.stdout.write("交付契约校验通过\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,987 @@
+#!/usr/bin/env python3
+"""校验 tasks.yaml 是否符合 ack 任务板结构。
+
+权威结构是同目录上层的 templates/tasks.schema.json（跨语言可用）。
+本脚本是参考实现：
+  - 始终执行内置语义校验；
+  - 安装了 jsonschema 时，再叠加 schema 结构校验；
+  - knowledge 字段会检查引用格式、候选结构和 Test 检查结果。
+YAML 优先使用 PyYAML；未安装时使用 fail-closed 的 ACK YAML 子集。
+JSON 任务板只使用标准库，两种格式都拒绝重复键。
+
+用法:
+    python3 validate_tasks.py [tasks.yaml]
+    python3 validate_tasks.py --schema path/to/tasks.schema.json tasks.yaml
+
+退出码: 0 通过 / 1 校验失败 / 2 环境或用法错误。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from yaml_subset import (
+    DuplicateKeyError,
+    YamlSubsetError,
+    load_json_unique,
+    load_yaml_subset,
+    make_unique_pyyaml_loader,
+)
+from worker_profiles import validate_routing_document
+
+STATUS_ENUM = {
+    "open",
+    "dispatched",
+    "fixed_by_dev",
+    "retesting",
+    "failed_retest",
+    "verified",
+    "blocked",
+    "leftover",
+}
+MAX_ROUNDS = 3
+KNOWLEDGE_KINDS = {"guardrail", "pitfall", "verification"}
+KNOWLEDGE_CHECK_RESULTS = {"passed", "failed", "not_applicable"}
+KNOWLEDGE_REF_RE = re.compile(r"^K-[A-Z0-9][A-Z0-9-]*@[1-9][0-9]*$")
+TASK_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+ATTEMPT_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*-A[1-9][0-9]*$")
+DELIVERY_RUN_ID_RE = re.compile(r"^DR-[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+DELIVERY_PROFILE_RE = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
+GIT_REVISION_RE = re.compile(r"^[0-9a-f]{7,64}$")
+SEMVER_RE = re.compile(
+    r"^(0|[1-9][0-9]*)\."
+    r"(0|[1-9][0-9]*)\."
+    r"(0|[1-9][0-9]*)"
+    r"(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)"
+    r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?"
+    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
+)
+KNOWLEDGE_SCOPE_FIELDS = {
+    "components",
+    "paths",
+    "dependencies",
+    "versions",
+    "tags",
+    "symbols",
+    "errorSignatures",
+}
+KNOWLEDGE_APPLICATION_FIELDS = {"ref", "result", "evidence"}
+KNOWLEDGE_CANDIDATE_FIELDS = {
+    "kind",
+    "title",
+    "claim",
+    "scope",
+    "appliesWhen",
+    "directive",
+    "rationale",
+    "evidenceRefs",
+    "proposedBy",
+    "proposedAt",
+}
+KNOWLEDGE_CHECK_FIELDS = {
+    "ref",
+    "result",
+    "evidence",
+    "checkedBy",
+    "checkedAt",
+}
+DELIVERY_RUN_FIELDS = {
+    "id",
+    "profile",
+    "taskIds",
+    "status",
+    "sourceRevision",
+    "configRevision",
+    "pullRequest",
+    "artifacts",
+    "deployments",
+    "evidence",
+    "updatedAt",
+}
+DELIVERY_STATUSES = {
+    "planned",
+    "running",
+    "blocked",
+    "failed",
+    "review_ready",
+    "released",
+    "skipped",
+}
+DELIVERY_ARTIFACT_FIELDS = {"id", "type", "reference", "digest"}
+DELIVERY_DEPLOYMENT_FIELDS = {"environment", "result", "evidence"}
+DISPATCH_FIELDS = {
+    "taskId",
+    "dispatchId",
+    "worker",
+    "developer",
+    "test",
+    "operator",
+    "rounds",
+}
+DELIVERY_OPERATION_FIELDS = {"skill", "request"}
+DELIVERY_OPERATION_SKILLS = {
+    "manage-release",
+    "deb-publisher",
+    "publish-docker-image",
+}
+KNOWLEDGE_CANDIDATE_REQUIRED_FIELDS = {
+    "kind",
+    "title",
+    "claim",
+    "scope",
+    "appliesWhen",
+    "directive",
+    "rationale",
+    "evidenceRefs",
+}
+KNOWLEDGE_CANDIDATE_TEXT_FIELDS = {
+    "title",
+    "claim",
+    "appliesWhen",
+    "directive",
+    "rationale",
+}
+
+
+def _nonempty_string(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def load_document(path: Path) -> dict:
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        sys.stderr.write(f"任务板读取失败: {exc}\n")
+        raise SystemExit(1)
+
+    if path.suffix.lower() == ".json":
+        try:
+            data = load_json_unique(content)
+        except (json.JSONDecodeError, DuplicateKeyError) as exc:
+            sys.stderr.write(f"JSON 解析失败: {exc}\n")
+            raise SystemExit(1)
+    else:
+        try:
+            import yaml  # type: ignore
+        except ImportError:
+            try:
+                data = load_yaml_subset(content)
+            except YamlSubsetError as exc:
+                sys.stderr.write(f"YAML 子集解析失败: {exc}\n")
+                raise SystemExit(1)
+        else:
+            try:
+                data = yaml.load(
+                    content,
+                    Loader=make_unique_pyyaml_loader(yaml),
+                )
+            except yaml.YAMLError as exc:  # type: ignore
+                sys.stderr.write(f"YAML 解析失败: {exc}\n")
+                raise SystemExit(1)
+    if not isinstance(data, dict):
+        sys.stderr.write("任务板顶层必须是对象（mapping）\n")
+        raise SystemExit(1)
+    return data
+
+
+def validate_knowledge_ref_list(
+    value: object,
+    where: str,
+    errors: list[str],
+) -> list[str]:
+    if not isinstance(value, list):
+        errors.append(f"{where}: 必须是列表")
+        return []
+
+    refs: list[str] = []
+    seen: set[str] = set()
+    for index, ref in enumerate(value):
+        item_where = f"{where}[{index}]"
+        if not isinstance(ref, str) or not KNOWLEDGE_REF_RE.fullmatch(ref):
+            errors.append(f"{item_where}: 必须使用 K-<id>@<revision> 格式")
+            continue
+        if ref in seen:
+            errors.append(f"{item_where}: 引用重复: {ref}")
+        seen.add(ref)
+        refs.append(ref)
+    return refs
+
+
+def reject_unknown_fields(
+    value: dict,
+    allowed: set[str],
+    where: str,
+    errors: list[str],
+) -> None:
+    """Mirror additionalProperties=false for builtin knowledge validation."""
+    for field in sorted(set(value) - allowed):
+        errors.append(f"{where}: 未知字段 {field!r}")
+
+
+def validate_optional_string_fields(
+    value: dict,
+    fields: set[str],
+    where: str,
+    errors: list[str],
+) -> None:
+    for field in sorted(fields):
+        if field in value and not isinstance(value[field], str):
+            errors.append(f"{where}.{field}: 必须是字符串")
+
+
+def validate_knowledge_fields(
+    task: dict,
+    where: str,
+    status: object,
+    errors: list[str],
+) -> None:
+    refs = (
+        validate_knowledge_ref_list(
+            task["knowledgeRefs"],
+            f"{where}.knowledgeRefs",
+            errors,
+        )
+        if "knowledgeRefs" in task
+        else []
+    )
+    if "knowledgeApplied" in task:
+        applications = task["knowledgeApplied"]
+        if not isinstance(applications, list):
+            errors.append(f"{where}.knowledgeApplied: 必须是列表")
+        else:
+            seen_applications: set[str] = set()
+            for index, application in enumerate(applications):
+                application_where = f"{where}.knowledgeApplied[{index}]"
+                if not isinstance(application, dict):
+                    errors.append(f"{application_where}: 必须是对象")
+                    continue
+                reject_unknown_fields(
+                    application,
+                    KNOWLEDGE_APPLICATION_FIELDS,
+                    application_where,
+                    errors,
+                )
+                ref = application.get("ref")
+                if not isinstance(ref, str) or not KNOWLEDGE_REF_RE.fullmatch(ref):
+                    errors.append(
+                        f"{application_where}.ref: 必须使用 K-<id>@<revision> 格式"
+                    )
+                else:
+                    if ref in seen_applications:
+                        errors.append(f"{application_where}.ref: 应用结果重复: {ref}")
+                    seen_applications.add(ref)
+                    if ref not in refs:
+                        errors.append(f"{application_where}.ref: {ref} 不在 knowledgeRefs 中")
+                if application.get("result") not in {"applied", "not_applicable"}:
+                    errors.append(
+                        f"{application_where}.result: 必须是 applied/not_applicable"
+                    )
+                evidence = application.get("evidence")
+                if not isinstance(evidence, str) or not evidence.strip():
+                    errors.append(f"{application_where}.evidence: 必须提供非空证据")
+
+    if "knowledgeCandidates" in task:
+        candidates = task["knowledgeCandidates"]
+        if not isinstance(candidates, list):
+            errors.append(f"{where}.knowledgeCandidates: 必须是列表")
+        else:
+            for index, candidate in enumerate(candidates):
+                candidate_where = f"{where}.knowledgeCandidates[{index}]"
+                if not isinstance(candidate, dict):
+                    errors.append(f"{candidate_where}: 必须是对象")
+                    continue
+                reject_unknown_fields(
+                    candidate,
+                    KNOWLEDGE_CANDIDATE_FIELDS,
+                    candidate_where,
+                    errors,
+                )
+                missing = sorted(
+                    key
+                    for key in KNOWLEDGE_CANDIDATE_REQUIRED_FIELDS
+                    if key not in candidate
+                )
+                if missing:
+                    errors.append(
+                        f"{candidate_where}: 缺少必填字段 {', '.join(missing)}"
+                    )
+                if candidate.get("kind") not in KNOWLEDGE_KINDS:
+                    errors.append(
+                        f"{candidate_where}.kind: 必须是 {sorted(KNOWLEDGE_KINDS)}"
+                    )
+                for field in sorted(KNOWLEDGE_CANDIDATE_TEXT_FIELDS):
+                    value = candidate.get(field)
+                    if not isinstance(value, str) or not value.strip():
+                        errors.append(
+                            f"{candidate_where}.{field}: 必须是非空字符串"
+                        )
+                validate_optional_string_fields(
+                    candidate,
+                    {"proposedBy", "proposedAt"},
+                    candidate_where,
+                    errors,
+                )
+                scope = candidate.get("scope")
+                if not isinstance(scope, dict):
+                    errors.append(f"{candidate_where}.scope: 至少包含一个非空作用域")
+                else:
+                    unknown_scope_fields = sorted(
+                        set(scope) - KNOWLEDGE_SCOPE_FIELDS - {"all"}
+                    )
+                    for field in unknown_scope_fields:
+                        errors.append(
+                            f"{candidate_where}.scope: 未知字段 {field!r}"
+                        )
+                    if "all" in scope and not isinstance(scope.get("all"), bool):
+                        errors.append(f"{candidate_where}.scope.all: 必须是布尔值")
+                    populated_scope_fields: list[str] = []
+                    for field in sorted(KNOWLEDGE_SCOPE_FIELDS & set(scope)):
+                        values = scope.get(field)
+                        if not isinstance(values, list) or any(
+                            not isinstance(item, str) or not item.strip()
+                            for item in values
+                        ):
+                            errors.append(
+                                f"{candidate_where}.scope.{field}: "
+                                "必须是非空字符串列表"
+                            )
+                        elif len(values) != len(set(values)):
+                            errors.append(
+                                f"{candidate_where}.scope.{field}: 不能包含重复值"
+                            )
+                        elif values:
+                            populated_scope_fields.append(field)
+                    if scope.get("all") is True and populated_scope_fields:
+                        errors.append(
+                            f"{candidate_where}.scope: all=true 时不能同时填写作用域维度"
+                        )
+                    if scope.get("all") is not True and not populated_scope_fields:
+                        errors.append(
+                            f"{candidate_where}.scope: 至少包含一个非空作用域"
+                        )
+                evidence_refs = candidate.get("evidenceRefs")
+                if (
+                    not isinstance(evidence_refs, list)
+                    or not evidence_refs
+                    or not all(
+                        isinstance(ref, str) and ref.strip()
+                        for ref in evidence_refs
+                    )
+                ):
+                    errors.append(
+                        f"{candidate_where}.evidenceRefs: 必须是非空字符串列表"
+                    )
+                elif len(evidence_refs) != len(set(evidence_refs)):
+                    errors.append(
+                        f"{candidate_where}.evidenceRefs: 不能包含重复值"
+                    )
+
+    if "knowledgeChecks" not in task:
+        return
+    checks = task["knowledgeChecks"]
+    if not isinstance(checks, list):
+        errors.append(f"{where}.knowledgeChecks: 必须是列表")
+        return
+
+    seen_checks: set[str] = set()
+    for index, check in enumerate(checks):
+        check_where = f"{where}.knowledgeChecks[{index}]"
+        if not isinstance(check, dict):
+            errors.append(f"{check_where}: 必须是对象")
+            continue
+        reject_unknown_fields(
+            check,
+            KNOWLEDGE_CHECK_FIELDS,
+            check_where,
+            errors,
+        )
+        validate_optional_string_fields(
+            check,
+            {"checkedBy", "checkedAt"},
+            check_where,
+            errors,
+        )
+        ref = check.get("ref")
+        result = check.get("result")
+        evidence = check.get("evidence")
+        if not isinstance(ref, str) or not KNOWLEDGE_REF_RE.fullmatch(ref):
+            errors.append(f"{check_where}.ref: 必须使用 K-<id>@<revision> 格式")
+        else:
+            if ref in seen_checks:
+                errors.append(f"{check_where}.ref: 检查结果重复: {ref}")
+            seen_checks.add(ref)
+            if ref not in refs:
+                errors.append(f"{check_where}.ref: {ref} 不在 knowledgeRefs 中")
+        if result not in KNOWLEDGE_CHECK_RESULTS:
+            errors.append(
+                f"{check_where}.result: 必须是 {sorted(KNOWLEDGE_CHECK_RESULTS)}"
+            )
+        if not isinstance(evidence, str) or not evidence.strip():
+            errors.append(f"{check_where}.evidence: 必须提供非空证据")
+        if status == "verified" and result == "failed":
+            errors.append(f"{check_where}: verified 任务不能保留失败的知识检查")
+
+
+def validate_delivery_runs(
+    value: object,
+    task_statuses: dict[str, object],
+    errors: list[str],
+    *,
+    delivery_operation_ids: set[str] | None = None,
+) -> None:
+    if not isinstance(value, list):
+        errors.append("deliveryRuns 必须是列表")
+        return
+
+    excluded_task_ids = delivery_operation_ids or set()
+    seen_run_ids: set[str] = set()
+    for index, run in enumerate(value):
+        where = f"deliveryRuns[{index}]"
+        if not isinstance(run, dict):
+            errors.append(f"{where}: 必须是对象")
+            continue
+        reject_unknown_fields(run, DELIVERY_RUN_FIELDS, where, errors)
+        missing = sorted(DELIVERY_RUN_FIELDS - set(run))
+        for field in missing:
+            errors.append(f"{where}.{field}: 必填")
+
+        run_id = run.get("id")
+        if not isinstance(run_id, str) or DELIVERY_RUN_ID_RE.fullmatch(run_id) is None:
+            errors.append(f"{where}.id: 必须使用 DR-<id> 格式")
+        elif run_id in seen_run_ids:
+            errors.append(f"{where}.id: 不能重复 {run_id!r}")
+        else:
+            seen_run_ids.add(run_id)
+
+        profile = run.get("profile")
+        if not isinstance(profile, str) or DELIVERY_PROFILE_RE.fullmatch(profile) is None:
+            errors.append(f"{where}.profile: 必须使用小写连字符 ID")
+        status = run.get("status")
+        if status not in DELIVERY_STATUSES:
+            errors.append(f"{where}.status: 必须是 {sorted(DELIVERY_STATUSES)}")
+
+        task_ids = run.get("taskIds")
+        if (
+            not isinstance(task_ids, list)
+            or not task_ids
+            or any(not _nonempty_string(task_id) for task_id in task_ids)
+        ):
+            errors.append(f"{where}.taskIds: 必须是非空任务 ID 列表")
+            task_ids = []
+        elif len(task_ids) != len(set(task_ids)):
+            errors.append(f"{where}.taskIds: 不能包含重复值")
+        for task_id in task_ids:
+            if task_id not in task_statuses:
+                errors.append(f"{where}.taskIds: 未知任务 {task_id!r}")
+            elif task_id in excluded_task_ids:
+                errors.append(
+                    f"{where}.taskIds: deliveryRuns 不能引用 delivery-operation "
+                    f"{task_id!r}"
+                )
+            elif task_statuses[task_id] != "verified":
+                errors.append(
+                    f"{where}: delivery run 只能引用 verified 任务，"
+                    f"{task_id!r} 当前是 {task_statuses[task_id]!r}"
+                )
+
+        for field in ("sourceRevision", "configRevision"):
+            revision = run.get(field)
+            if revision is not None and (
+                not isinstance(revision, str) or GIT_REVISION_RE.fullmatch(revision) is None
+            ):
+                errors.append(f"{where}.{field}: 必须是 null 或 7..64 位小写十六进制 revision")
+        pull_request = run.get("pullRequest")
+        if pull_request is not None and not isinstance(pull_request, str):
+            errors.append(f"{where}.pullRequest: 必须是字符串或 null")
+        if status != "skipped":
+            for field in ("sourceRevision", "configRevision"):
+                if not _nonempty_string(run.get(field)):
+                    errors.append(f"{where}.{field}: status={status!r} 时必须填写")
+        if status in {"review_ready", "released"}:
+            if not _nonempty_string(run.get("pullRequest")):
+                errors.append(f"{where}.pullRequest: status={status!r} 时必须填写")
+
+        artifacts = run.get("artifacts")
+        if not isinstance(artifacts, list):
+            errors.append(f"{where}.artifacts: 必须是列表")
+        else:
+            seen_artifacts: set[str] = set()
+            for artifact_index, artifact in enumerate(artifacts):
+                artifact_where = f"{where}.artifacts[{artifact_index}]"
+                if not isinstance(artifact, dict):
+                    errors.append(f"{artifact_where}: 必须是对象")
+                    continue
+                reject_unknown_fields(
+                    artifact,
+                    DELIVERY_ARTIFACT_FIELDS,
+                    artifact_where,
+                    errors,
+                )
+                artifact_id = artifact.get("id")
+                if (
+                    not isinstance(artifact_id, str)
+                    or DELIVERY_PROFILE_RE.fullmatch(artifact_id) is None
+                ):
+                    errors.append(f"{artifact_where}.id: 必须使用小写连字符 ID")
+                elif artifact_id in seen_artifacts:
+                    errors.append(f"{artifact_where}.id: 不能重复 {artifact_id!r}")
+                else:
+                    seen_artifacts.add(artifact_id)
+                if artifact.get("type") not in {"deb", "oci-image", "file"}:
+                    errors.append(f"{artifact_where}.type: 必须是 deb/oci-image/file")
+                if not _nonempty_string(artifact.get("reference")):
+                    errors.append(f"{artifact_where}.reference: 必须是非空字符串")
+                digest = artifact.get("digest")
+                if digest is not None and (
+                    not isinstance(digest, str)
+                    or re.fullmatch(r"sha256:[0-9a-f]{64}", digest) is None
+                ):
+                    errors.append(f"{artifact_where}.digest: 必须是 sha256:<64 hex> 或 null")
+                if status in {"review_ready", "released"} and not _nonempty_string(digest):
+                    errors.append(
+                        f"{artifact_where}.digest: status={status!r} 时必须填写"
+                    )
+
+        deployments = run.get("deployments")
+        if not isinstance(deployments, list):
+            errors.append(f"{where}.deployments: 必须是列表")
+        else:
+            seen_environments: set[str] = set()
+            for deployment_index, deployment in enumerate(deployments):
+                deployment_where = f"{where}.deployments[{deployment_index}]"
+                if not isinstance(deployment, dict):
+                    errors.append(f"{deployment_where}: 必须是对象")
+                    continue
+                reject_unknown_fields(
+                    deployment,
+                    DELIVERY_DEPLOYMENT_FIELDS,
+                    deployment_where,
+                    errors,
+                )
+                environment = deployment.get("environment")
+                if (
+                    not isinstance(environment, str)
+                    or DELIVERY_PROFILE_RE.fullmatch(environment) is None
+                ):
+                    errors.append(f"{deployment_where}.environment: 必须使用小写连字符 ID")
+                elif environment in seen_environments:
+                    errors.append(f"{deployment_where}.environment: 不能重复 {environment!r}")
+                else:
+                    seen_environments.add(environment)
+                if deployment.get("result") not in {"succeeded", "failed", "rolled_back"}:
+                    errors.append(
+                        f"{deployment_where}.result: 必须是 succeeded/failed/rolled_back"
+                    )
+                if not _nonempty_string(deployment.get("evidence")):
+                    errors.append(f"{deployment_where}.evidence: 必须是非空字符串")
+
+        evidence = run.get("evidence")
+        if not isinstance(evidence, list) or any(
+            not _nonempty_string(item) for item in evidence
+        ):
+            errors.append(f"{where}.evidence: 必须是字符串列表")
+        elif status in {"blocked", "failed", "review_ready", "released", "skipped"} and not evidence:
+            errors.append(f"{where}.evidence: status={status!r} 时不能为空")
+        if not _nonempty_string(run.get("updatedAt")):
+            errors.append(f"{where}.updatedAt: 必须是非空字符串")
+
+
+def validate_with_schema(data: dict, schema_path: Path) -> list[str]:
+    import jsonschema  # type: ignore
+
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    validator = jsonschema.Draft7Validator(schema)
+    errors = []
+    for err in sorted(validator.iter_errors(data), key=lambda e: list(e.path)):
+        loc = "/".join(str(p) for p in err.path) or "<root>"
+        errors.append(f"[schema] {loc}: {err.message}")
+    return errors
+
+
+def validate_builtin(data: dict) -> list[str]:
+    errors: list[str] = []
+
+    def validate_string_fields(
+        value: dict,
+        fields: set[str],
+        where: str,
+        *,
+        nullable: bool = False,
+    ) -> None:
+        expected = "必须是字符串或 null" if nullable else "必须是字符串"
+        for field in sorted(fields):
+            if field not in value:
+                continue
+            field_value = value[field]
+            if not isinstance(field_value, str) and not (
+                nullable and field_value is None
+            ):
+                errors.append(f"{where}.{field}: {expected}")
+
+    def validate_string_lists(
+        value: dict,
+        fields: set[str],
+        where: str,
+    ) -> None:
+        for field in sorted(fields):
+            if field not in value:
+                continue
+            items = value[field]
+            if not isinstance(items, list):
+                errors.append(f"{where}.{field}: 必须是列表")
+            elif any(not isinstance(item, str) for item in items):
+                errors.append(f"{where}.{field}: 列表项必须是字符串")
+
+    def validate_object_fields(
+        value: dict,
+        fields: set[str],
+        where: str,
+    ) -> None:
+        for field in sorted(fields):
+            if field in value and not isinstance(value[field], dict):
+                errors.append(f"{where}.{field}: 必须是对象")
+
+    version = data.get("version")
+    if (
+        not isinstance(version, int)
+        or isinstance(version, bool)
+        or version < 1
+    ):
+        errors.append("version 必须是 >=1 的整数")
+    validate_string_fields(
+        data,
+        {"updatedAt", "source", "ackVersion", "kitVersion"},
+        "<root>",
+    )
+
+    project = data.get("project")
+    if not isinstance(project, dict):
+        errors.append("project 必须是对象")
+    else:
+        if not _nonempty_string(project.get("name")):
+            errors.append("project.name 必须是非空字符串")
+        validate_string_fields(
+            project,
+            {"repoPath", "baseUrl", "devWorktree", "overlayFile", "deliveryFile"},
+            "project",
+        )
+        if (
+            "knowledgeFile" in project
+            and project.get("knowledgeFile") != "docs/ack/knowledge.yaml"
+        ):
+            errors.append(
+                "project.knowledgeFile 必须固定为 docs/ack/knowledge.yaml"
+            )
+        if (
+            "deliveryFile" in project
+            and project.get("deliveryFile") != "docs/ack/delivery.yaml"
+        ):
+            errors.append(
+                "project.deliveryFile 必须固定为 docs/ack/delivery.yaml"
+            )
+        if "deliveryFile" in project and not isinstance(data.get("deliveryRuns"), list):
+            errors.append("引用 deliveryFile 的任务板必须包含 deliveryRuns 列表")
+        if "deliveryRuns" in data and "deliveryFile" not in project:
+            errors.append("deliveryRuns 存在时 project.deliveryFile 必须存在")
+
+    ack_version = data.get("ackVersion")
+    version_match = SEMVER_RE.fullmatch(ack_version) if isinstance(ack_version, str) else None
+    if "ackVersion" in data and version_match is None:
+        errors.append("ackVersion 必须是合法 SemVer（例如 0.10.0）")
+    routing_required = (
+        (isinstance(project, dict) and "orchestration" in project)
+        or "workerReceipts" in data
+        or (
+            version_match is not None
+            and (int(version_match.group(1)), int(version_match.group(2)))
+            >= (0, 10)
+        )
+    )
+    if routing_required:
+        errors.extend(validate_routing_document(data))
+
+    if "summary" in data:
+        summary = data["summary"]
+        if not isinstance(summary, dict):
+            errors.append("summary 必须是对象")
+        else:
+            validate_string_lists(
+                summary,
+                {"verified", "open", "failedRetest", "leftovers"},
+                "summary",
+            )
+    if "statusReference" in data and not isinstance(
+        data["statusReference"], dict
+    ):
+        errors.append("statusReference 必须是对象")
+
+    tasks = data.get("tasks")
+    if not isinstance(tasks, list):
+        errors.append("tasks 必须是列表")
+        return errors
+
+    seen_ids: set[str] = set()
+    for i, task in enumerate(tasks):
+        where = f"tasks[{i}]"
+        if not isinstance(task, dict):
+            errors.append(f"{where}: 必须是对象")
+            continue
+        tid = task.get("id")
+        title = task.get("title")
+        status = task.get("status")
+        if not _nonempty_string(tid):
+            errors.append(f"{where}: id 必须是非空字符串")
+        else:
+            where = f"tasks[{i}] {tid}"
+            if routing_required and TASK_ID_RE.fullmatch(tid) is None:
+                errors.append(
+                    f"{where}: v0.10 自动路由 id 只允许字母、数字、点、下划线和连字符"
+                )
+            if tid in seen_ids:
+                errors.append(f"{where}: id 重复")
+            seen_ids.add(tid)
+        if not _nonempty_string(title):
+            errors.append(f"{where}: title 必须是非空字符串")
+        if status not in STATUS_ENUM:
+            errors.append(
+                f"{where}: status={status!r} 非法，应为 {sorted(STATUS_ENUM)}"
+            )
+
+        validate_string_fields(
+            task,
+            {
+                "type",
+                "priority",
+                "assignee",
+                "component",
+                "description",
+                "expected",
+                "actual",
+            },
+            where,
+        )
+        validate_string_lists(
+            task,
+            {"specRefs", "testRefs", "stepsToReproduce"},
+            where,
+        )
+        validate_object_fields(task, {"evidence", "verification"}, where)
+
+        operation = task.get("operation")
+        if operation is not None:
+            if not isinstance(operation, dict):
+                errors.append(f"{where}.operation: 必须是对象")
+            else:
+                reject_unknown_fields(
+                    operation,
+                    DELIVERY_OPERATION_FIELDS,
+                    f"{where}.operation",
+                    errors,
+                )
+                skill = operation.get("skill")
+                if skill not in DELIVERY_OPERATION_SKILLS:
+                    errors.append(
+                        f"{where}.operation.skill: 必须是 "
+                        "manage-release/deb-publisher/publish-docker-image"
+                    )
+                if not _nonempty_string(operation.get("request")):
+                    errors.append(f"{where}.operation.request: 必须保留非空用户请求")
+
+        if task.get("type") == "delivery-operation":
+            if not isinstance(operation, dict):
+                errors.append(f"{where}: delivery-operation 必须声明 operation")
+
+        validate_knowledge_fields(task, where, status, errors)
+
+        if "dispatch" not in task:
+            dispatch = {}
+        elif not isinstance(task["dispatch"], dict):
+            errors.append(f"{where}.dispatch: 必须是对象")
+            dispatch = {}
+        else:
+            dispatch = task["dispatch"]
+            reject_unknown_fields(
+                dispatch,
+                DISPATCH_FIELDS,
+                f"{where}.dispatch",
+                errors,
+            )
+            validate_string_fields(
+                dispatch,
+                {"taskId", "dispatchId", "worker"},
+                f"{where}.dispatch",
+                nullable=True,
+            )
+
+        if task.get("type") == "delivery-operation" and (
+            not isinstance(dispatch, dict)
+            or not isinstance(dispatch.get("operator"), dict)
+        ):
+            errors.append(f"{where}: delivery-operation 必须声明 dispatch.operator")
+
+        rounds = dispatch.get("rounds", [])
+        if not isinstance(rounds, list):
+            errors.append(f"{where}.dispatch.rounds: 必须是列表")
+        else:
+            if len(rounds) > MAX_ROUNDS:
+                errors.append(
+                    f"{where}: 派发轮次 {len(rounds)} 超过上限 {MAX_ROUNDS}"
+                )
+            seen_attempt_ids: set[str] = set()
+            round_numbers: list[int] = []
+            for round_index, round_item in enumerate(rounds):
+                round_where = f"{where}.dispatch.rounds[{round_index}]"
+                if not isinstance(round_item, dict):
+                    errors.append(f"{round_where}: 必须是对象")
+                    continue
+                if round_item.get("result") not in {"passed", "failed"}:
+                    errors.append(f"{round_where}.result: 必须是 passed/failed")
+                if "evidence" in round_item and not isinstance(
+                    round_item["evidence"], str
+                ):
+                    errors.append(f"{round_where}.evidence: 必须是字符串")
+                round_number = round_item.get("round")
+                round_number_is_valid = (
+                    isinstance(round_number, int)
+                    and not isinstance(round_number, bool)
+                    and 1 <= round_number <= MAX_ROUNDS
+                )
+                if not round_number_is_valid:
+                    errors.append(
+                        f"{round_where}.round: 必须是 1..{MAX_ROUNDS} 的整数"
+                    )
+                else:
+                    round_numbers.append(round_number)
+                if "attemptId" in round_item:
+                    attempt_id = round_item["attemptId"]
+                    if (
+                        not isinstance(attempt_id, str)
+                        or not ATTEMPT_ID_RE.fullmatch(attempt_id)
+                    ):
+                        errors.append(
+                            f"{round_where}.attemptId: "
+                            "必须使用 <task-id>-A<round> 格式"
+                        )
+                    else:
+                        if attempt_id in seen_attempt_ids:
+                            errors.append(
+                                f"{round_where}.attemptId: "
+                                f"轮次内不能重复: {attempt_id}"
+                            )
+                        seen_attempt_ids.add(attempt_id)
+                        if (
+                            isinstance(tid, str)
+                            and round_number_is_valid
+                            and attempt_id != f"{tid}-A{round_number}"
+                        ):
+                            errors.append(
+                                f"{round_where}.attemptId: 应为 "
+                                f"{tid}-A{round_number}"
+                            )
+            expected_rounds = list(range(1, len(rounds) + 1))
+            if round_numbers != expected_rounds:
+                errors.append(
+                    f"{where}.dispatch.rounds: round 必须从 1 连续递增且不重复"
+                )
+
+        resolution = task.get("resolution")
+        if "resolution" in task:
+            if not isinstance(resolution, dict):
+                errors.append(f"{where}.resolution: 必须是对象")
+            else:
+                validate_string_fields(
+                    resolution,
+                    {
+                        "fixedBy",
+                        "verifiedBy",
+                        "verifiedAt",
+                        "leftoverReason",
+                    },
+                    f"{where}.resolution",
+                    nullable=True,
+                )
+                validate_object_fields(
+                    resolution,
+                    {"evidence"},
+                    f"{where}.resolution",
+                )
+
+        if status == "leftover":
+            if (
+                not isinstance(resolution, dict)
+                or not _nonempty_string(resolution.get("leftoverReason"))
+            ):
+                errors.append(f"{where}: leftover 必须填 resolution.leftoverReason")
+
+    if "deliveryRuns" in data:
+        task_statuses = {
+            task.get("id"): task.get("status")
+            for task in tasks
+            if isinstance(task, dict) and _nonempty_string(task.get("id"))
+        }
+        delivery_operation_ids = {
+            task["id"]
+            for task in tasks
+            if isinstance(task, dict)
+            and _nonempty_string(task.get("id"))
+            and task.get("type") == "delivery-operation"
+        }
+        validate_delivery_runs(
+            data["deliveryRuns"],
+            task_statuses,
+            errors,
+            delivery_operation_ids=delivery_operation_ids,
+        )
+
+    return errors
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="校验 tasks.yaml 结构")
+    parser.add_argument("tasks", nargs="?", default="tasks.yaml", help="任务板路径")
+    parser.add_argument("--schema", help="tasks.schema.json 路径（默认自动探测）")
+    args = parser.parse_args(argv)
+
+    tasks_path = Path(args.tasks)
+    if not tasks_path.is_file():
+        sys.stderr.write(f"找不到任务板文件: {tasks_path}\n")
+        return 2
+
+    data = load_document(tasks_path)
+
+    schema_path = Path(args.schema) if args.schema else (
+        Path(__file__).resolve().parent.parent / "templates" / "tasks.schema.json"
+    )
+    if args.schema and not schema_path.is_file():
+        sys.stderr.write(f"找不到指定的 schema 文件: {schema_path}\n")
+        return 2
+
+    errors = validate_builtin(data)
+    mode = "内置语义规则"
+    try:
+        import jsonschema  # type: ignore  # noqa: F401
+
+        if schema_path.is_file():
+            errors = validate_with_schema(data, schema_path) + errors
+            mode = f"schema ({schema_path.name}) + 内置语义规则"
+        else:
+            mode = "内置语义规则（未找到 schema 文件）"
+    except ImportError:
+        pass
+
+    if errors:
+        sys.stderr.write(f"任务板校验失败（{mode}），共 {len(errors)} 项：\n")
+        for e in errors:
+            sys.stderr.write(f"  - {e}\n")
+        return 1
+
+    sys.stdout.write(f"任务板校验通过（{mode}）：{tasks_path}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Fail-closed migration shim for ACK's removed free-form command validator.
+
+ACK v0.10 no longer accepts a shell command as worker configuration.  Keep this
+file only so older documentation or automation fails with a precise migration
+message instead of silently retaining the unsafe path.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+MIGRATION_MESSAGE = (
+    "ACK v0.10 已停用自由 worker command 校验器；请在 "
+    "docs/ack/tasks.yaml 的 project.orchestration 中声明 profile，并仅调用 "
+    "scripts/launch_worker.py profile-hash|plan|launch。"
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if arguments == ["--self-test"]:
+        print("legacy worker command 路径已 fail-closed")
+        return 0
+    sys.stderr.write(MIGRATION_MESSAGE + "\n")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,686 @@
+#!/usr/bin/env python3
+"""ACK YAML 的零依赖、fail-closed 子集解析器。
+
+这不是通用 YAML 实现。它只覆盖 ACK 状态文件所需的 mapping、
+sequence、flow collection、标量和 ``>`` / ``|`` block scalar。锚点、
+alias、tag、多文档和其它未实现语法会显式失败，不会猜测或静默误解析。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+
+class YamlSubsetError(ValueError):
+    """YAML 超出 ACK 子集或语法无效。"""
+
+
+class DuplicateKeyError(ValueError):
+    """JSON/YAML mapping 包含重复键。"""
+
+
+@dataclass(frozen=True)
+class _Line:
+    number: int
+    indent: int
+    content: str
+
+
+_DECIMAL_INT_RE = re.compile(r"[-+]?(?:0|[1-9][0-9]*)\Z")
+_AMBIGUOUS_NUMBER_RE = re.compile(
+    r"[-+]?(?:"
+    r"[0-9][0-9_]*\.[0-9_]*(?:[eE][-+]?[0-9]+)?|"
+    r"[0-9][0-9_]*(?:[eE][-+]?[0-9]+)|"
+    r"0[xX][0-9a-fA-F_]+|0[oO][0-7_]+|0[bB][01_]+|"
+    r"0[0-9_]+|[0-9][0-9_]*:[0-9_:]+"
+    r")\Z"
+)
+_PLAIN_KEY_FORBIDDEN_RE = re.compile(r"[\[\]{},#]")
+_ANCHOR_OR_ALIAS_RE = re.compile(
+    r"(?:^|\s)[&*][A-Za-z0-9_-]+(?:\s|$)"
+)
+
+
+def load_json_unique(content: str) -> Any:
+    """Parse JSON while rejecting duplicate object keys at every depth."""
+
+    def unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for key, value in pairs:
+            if key in result:
+                raise DuplicateKeyError(f"JSON 存在重复键 {key!r}")
+            result[key] = value
+        return result
+
+    return json.loads(content, object_pairs_hook=unique_object)
+
+
+def make_unique_pyyaml_loader(yaml_module: Any) -> type:
+    """Build a SafeLoader that rejects duplicate keys and graph features.
+
+    ACK documents are trees. Anchors/aliases can introduce shared identity or
+    cycles, which are unnecessary here and make recursive validation unsafe.
+    Explicit tags are also outside the fallback grammar, so both code paths
+    reject them consistently.
+    """
+
+    class UniqueKeySafeLoader(yaml_module.SafeLoader):  # type: ignore[misc]
+        def compose_node(self, parent: Any, index: Any) -> Any:
+            if self.check_event(yaml_module.events.AliasEvent):
+                event = self.peek_event()
+                raise yaml_module.YAMLError(
+                    f"ACK YAML 不支持 alias: *{event.anchor}"
+                )
+            event = self.peek_event()
+            if getattr(event, "anchor", None) is not None:
+                raise yaml_module.YAMLError(
+                    f"ACK YAML 不支持 anchor: &{event.anchor}"
+                )
+            if getattr(event, "tag", None) is not None:
+                raise yaml_module.YAMLError(
+                    f"ACK YAML 不支持显式 tag: {event.tag}"
+                )
+            return super().compose_node(parent, index)
+
+    def construct_unique_mapping(
+        loader: Any,
+        node: Any,
+        deep: bool = False,
+    ) -> dict[str, Any]:
+        for key_node, _ in node.value:
+            if (
+                getattr(key_node, "tag", None) == "tag:yaml.org,2002:merge"
+                or getattr(key_node, "value", None) == "<<"
+            ):
+                raise yaml_module.constructor.ConstructorError(
+                    "while constructing an ACK mapping",
+                    node.start_mark,
+                    "merge keys are not supported",
+                    key_node.start_mark,
+                )
+        loader.flatten_mapping(node)
+        mapping: dict[str, Any] = {}
+        for key_node, value_node in node.value:
+            key = loader.construct_object(key_node, deep=deep)
+            if not isinstance(key, str):
+                raise yaml_module.constructor.ConstructorError(
+                    "while constructing an ACK mapping",
+                    node.start_mark,
+                    "mapping key must be a string",
+                    key_node.start_mark,
+                )
+            if key == "<<":
+                raise yaml_module.constructor.ConstructorError(
+                    "while constructing an ACK mapping",
+                    node.start_mark,
+                    "merge keys are not supported",
+                    key_node.start_mark,
+                )
+            if key in mapping:
+                raise yaml_module.constructor.ConstructorError(
+                    "while constructing an ACK mapping",
+                    node.start_mark,
+                    f"found duplicate key {key!r}",
+                    key_node.start_mark,
+                )
+            mapping[key] = loader.construct_object(value_node, deep=deep)
+        return mapping
+
+    UniqueKeySafeLoader.add_constructor(
+        yaml_module.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
+        construct_unique_mapping,
+    )
+    return UniqueKeySafeLoader
+
+
+def load_yaml_subset(content: str) -> Any:
+    """Parse the deliberately small YAML subset used by ACK files."""
+
+    return _SubsetParser(content).parse()
+
+
+class _SubsetParser:
+    def __init__(self, content: str) -> None:
+        if content.startswith("\ufeff"):
+            content = content[1:]
+        if "\t" in content:
+            raise YamlSubsetError("ACK YAML 子集不支持 Tab，请使用空格")
+        self.lines = [
+            _Line(number, len(raw) - len(raw.lstrip(" ")), raw.lstrip(" "))
+            for number, raw in enumerate(content.splitlines(), start=1)
+        ]
+        self.index = 0
+
+    def parse(self) -> Any:
+        self._skip_insignificant()
+        if self.index >= len(self.lines):
+            return None
+        first = self.lines[self.index]
+        if first.indent != 0:
+            self._error(first, "顶层不能缩进")
+        value = self._parse_node(0)
+        self._skip_insignificant()
+        if self.index != len(self.lines):
+            line = self.lines[self.index]
+            self._error(line, "文档尾部存在无法解析的内容")
+        return value
+
+    def _parse_node(self, indent: int) -> Any:
+        self._skip_insignificant()
+        if self.index >= len(self.lines):
+            return None
+        line = self.lines[self.index]
+        if line.indent != indent:
+            self._error(line, f"期望 {indent} 个空格的缩进")
+        content = self._without_comment(line.content).rstrip()
+        self._reject_document_syntax(content, line)
+        if self._is_sequence_marker(content):
+            return self._parse_sequence(indent)
+        return self._parse_mapping(indent)
+
+    def _parse_mapping(self, indent: int) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        while True:
+            self._skip_insignificant()
+            if self.index >= len(self.lines):
+                break
+            line = self.lines[self.index]
+            if line.indent < indent:
+                break
+            if line.indent > indent:
+                self._error(line, "mapping 存在意外缩进")
+            content = self._without_comment(line.content).rstrip()
+            self._reject_document_syntax(content, line)
+            if self._is_sequence_marker(content):
+                break
+            self.index += 1
+            self._consume_mapping_entry(
+                result,
+                content,
+                mapping_indent=indent,
+                line=line,
+            )
+        return result
+
+    def _parse_sequence(self, indent: int) -> list[Any]:
+        result: list[Any] = []
+        while True:
+            self._skip_insignificant()
+            if self.index >= len(self.lines):
+                break
+            line = self.lines[self.index]
+            if line.indent < indent:
+                break
+            if line.indent > indent:
+                self._error(line, "sequence 存在意外缩进")
+            content = self._without_comment(line.content).rstrip()
+            self._reject_document_syntax(content, line)
+            if not self._is_sequence_marker(content):
+                break
+            rest = content[1:].lstrip(" ")
+            self.index += 1
+            if not rest:
+                next_line = self._peek_significant()
+                if next_line is not None and next_line.indent > indent:
+                    result.append(self._parse_node(next_line.indent))
+                else:
+                    result.append(None)
+                continue
+            if self._is_sequence_marker(rest):
+                self._error(
+                    line,
+                    "不支持紧凑嵌套 sequence，请把内层 '-' 放到下一行",
+                )
+            if self._looks_like_mapping_entry(rest):
+                mapping_indent = indent + 2
+                item: dict[str, Any] = {}
+                self._consume_mapping_entry(
+                    item,
+                    rest,
+                    mapping_indent=mapping_indent,
+                    line=line,
+                )
+                while True:
+                    self._skip_insignificant()
+                    continuation = self._peek_significant()
+                    if continuation is None or continuation.indent < mapping_indent:
+                        break
+                    if continuation.indent > mapping_indent:
+                        self._error(
+                            continuation,
+                            "sequence mapping 存在意外缩进",
+                        )
+                    continuation_content = self._without_comment(
+                        continuation.content
+                    ).rstrip()
+                    if self._is_sequence_marker(continuation_content):
+                        self._error(
+                            continuation,
+                            "sequence mapping 中需要 key: value",
+                        )
+                    self.index += 1
+                    self._consume_mapping_entry(
+                        item,
+                        continuation_content,
+                        mapping_indent=mapping_indent,
+                        line=continuation,
+                    )
+                result.append(item)
+                continue
+            if rest in {">", "|"}:
+                result.append(self._parse_block_scalar(indent, rest, line))
+            else:
+                result.append(self._parse_inline_value(rest, line))
+                next_line = self._peek_significant()
+                if next_line is not None and next_line.indent > indent:
+                    self._error(next_line, "scalar sequence 项后存在意外缩进")
+        return result
+
+    def _consume_mapping_entry(
+        self,
+        result: dict[str, Any],
+        content: str,
+        *,
+        mapping_indent: int,
+        line: _Line,
+    ) -> None:
+        key_text, value_text = self._split_mapping_entry(content, line)
+        key = self._parse_key(key_text, line)
+        if key in result:
+            self._error(line, f"mapping 存在重复键 {key!r}")
+
+        value_text = value_text.strip()
+        if value_text in {">", "|"}:
+            value = self._parse_block_scalar(mapping_indent, value_text, line)
+        elif value_text:
+            if value_text.startswith((">", "|")):
+                self._error(
+                    line,
+                    "block scalar 只支持 '>' 或 '|'，不支持 chomping/indent 指示符",
+                )
+            value = self._parse_inline_value(value_text, line)
+            next_line = self._peek_significant()
+            if next_line is not None and next_line.indent > mapping_indent:
+                self._error(next_line, f"{key!r} 的 scalar 后存在意外缩进")
+        else:
+            next_line = self._peek_significant()
+            if next_line is not None and next_line.indent > mapping_indent:
+                value = self._parse_node(next_line.indent)
+            else:
+                value = None
+        result[key] = value
+
+    def _parse_block_scalar(
+        self,
+        parent_indent: int,
+        style: str,
+        header: _Line,
+    ) -> str:
+        probe = self.index
+        while probe < len(self.lines) and not self.lines[probe].content.strip():
+            probe += 1
+        if probe >= len(self.lines) or self.lines[probe].indent <= parent_indent:
+            return ""
+        block_indent = self.lines[probe].indent
+        if block_indent <= parent_indent:
+            self._error(header, "block scalar 内容必须比键更深缩进")
+
+        values: list[str] = []
+        while self.index < len(self.lines):
+            line = self.lines[self.index]
+            if not line.content.strip():
+                values.append("")
+                self.index += 1
+                continue
+            if line.indent < block_indent:
+                break
+            values.append(" " * (line.indent - block_indent) + line.content)
+            self.index += 1
+
+        while values and values[-1] == "":
+            values.pop()
+        if not values:
+            return ""
+        if style == "|":
+            return "\n".join(values) + "\n"
+
+        output = ""
+        previous: str | None = None
+        blank_count = 0
+        for value in values:
+            if value == "":
+                blank_count += 1
+                continue
+            if previous is None:
+                output = "\n" * blank_count + value
+            elif blank_count:
+                output += "\n" * blank_count + value
+            elif previous.startswith(" ") or value.startswith(" "):
+                output += "\n" + value
+            else:
+                output += " " + value
+            previous = value
+            blank_count = 0
+        return output + "\n"
+
+    def _parse_key(self, text: str, line: _Line) -> str:
+        text = text.strip()
+        if not text:
+            self._error(line, "mapping key 不能为空")
+        if text[0] in {'"', "'"}:
+            parsed = _FlowParser(text, line.number).parse_complete_value()
+            if not isinstance(parsed, str):
+                self._error(line, "mapping key 必须是字符串")
+            return parsed
+        if text == "<<":
+            self._error(line, "ACK YAML 子集不支持 merge key '<<'")
+        if text[0] in "-?:!&*%@`" or _PLAIN_KEY_FORBIDDEN_RE.search(text):
+            self._error(line, f"不支持的 plain mapping key {text!r}")
+        parsed = _plain_scalar(text, line.number)
+        if not isinstance(parsed, str):
+            self._error(line, "mapping key 必须是字符串，特殊标量请加引号")
+        return text
+
+    def _parse_inline_value(self, text: str, line: _Line) -> Any:
+        parser = _FlowParser(text, line.number)
+        return parser.parse_complete_value()
+
+    def _split_mapping_entry(self, content: str, line: _Line) -> tuple[str, str]:
+        quote: str | None = None
+        escaped = False
+        depth = 0
+        index = 0
+        while index < len(content):
+            char = content[index]
+            if quote == '"':
+                if escaped:
+                    escaped = False
+                elif char == "\\":
+                    escaped = True
+                elif char == quote:
+                    quote = None
+                index += 1
+                continue
+            if quote == "'":
+                if char == "'":
+                    if index + 1 < len(content) and content[index + 1] == "'":
+                        index += 2
+                        continue
+                    quote = None
+                index += 1
+                continue
+            if char in {'"', "'"}:
+                quote = char
+            elif char in "[{":
+                depth += 1
+            elif char in "]}":
+                depth -= 1
+                if depth < 0:
+                    self._error(line, "flow collection 括号不匹配")
+            elif (
+                char == ":"
+                and depth == 0
+                and (index + 1 == len(content) or content[index + 1].isspace())
+            ):
+                return content[:index], content[index + 1 :]
+            index += 1
+        self._error(line, "mapping 项必须使用 'key: value'")
+
+    def _looks_like_mapping_entry(self, content: str) -> bool:
+        try:
+            self._split_mapping_entry(content, self.lines[self.index - 1])
+        except YamlSubsetError:
+            return False
+        return True
+
+    @staticmethod
+    def _is_sequence_marker(content: str) -> bool:
+        return content == "-" or content.startswith("- ")
+
+    def _peek_significant(self) -> _Line | None:
+        probe = self.index
+        while probe < len(self.lines):
+            line = self.lines[probe]
+            if line.content.strip() and not line.content.lstrip().startswith("#"):
+                return line
+            probe += 1
+        return None
+
+    def _skip_insignificant(self) -> None:
+        while self.index < len(self.lines):
+            content = self.lines[self.index].content
+            if content.strip() and not content.lstrip().startswith("#"):
+                break
+            self.index += 1
+
+    def _without_comment(self, content: str) -> str:
+        quote: str | None = None
+        escaped = False
+        index = 0
+        while index < len(content):
+            char = content[index]
+            if quote == '"':
+                if escaped:
+                    escaped = False
+                elif char == "\\":
+                    escaped = True
+                elif char == quote:
+                    quote = None
+            elif quote == "'":
+                if char == "'":
+                    if index + 1 < len(content) and content[index + 1] == "'":
+                        index += 1
+                    else:
+                        quote = None
+            elif char in {'"', "'"}:
+                quote = char
+            elif char == "#" and (index == 0 or content[index - 1].isspace()):
+                return content[:index]
+            index += 1
+        if quote is not None:
+            raise YamlSubsetError("未结束的引号标量")
+        return content
+
+    def _reject_document_syntax(self, content: str, line: _Line) -> None:
+        if content in {"---", "..."} or content.startswith("%"):
+            self._error(line, "ACK YAML 子集只支持单文档，不支持 directive/marker")
+        if content.startswith(("!", "&", "*")):
+            self._error(line, "ACK YAML 子集不支持 tag/anchor/alias")
+
+    @staticmethod
+    def _error(line: _Line, message: str) -> None:
+        raise YamlSubsetError(f"第 {line.number} 行: {message}")
+
+
+class _FlowParser:
+    def __init__(self, text: str, line_number: int) -> None:
+        self.text = text
+        self.line_number = line_number
+        self.index = 0
+
+    def parse_complete_value(self) -> Any:
+        value = self._parse_value()
+        self._skip_space()
+        if self.index != len(self.text):
+            self._error(f"标量后存在未支持内容: {self.text[self.index:]!r}")
+        return value
+
+    def _parse_value(self) -> Any:
+        self._skip_space()
+        if self.index >= len(self.text):
+            self._error("缺少标量")
+        char = self.text[self.index]
+        if char == "[":
+            return self._parse_list()
+        if char == "{":
+            return self._parse_map()
+        if char in {'"', "'"}:
+            return self._parse_quoted()
+        if char in "]},":
+            self._error(f"意外字符 {char!r}")
+        return self._parse_plain({",", "]", "}"})
+
+    def _parse_list(self) -> list[Any]:
+        self.index += 1
+        result: list[Any] = []
+        self._skip_space()
+        if self._consume("]"):
+            return result
+        while True:
+            result.append(self._parse_value())
+            self._skip_space()
+            if self._consume("]"):
+                return result
+            if not self._consume(","):
+                self._error("flow list 项之间必须用 ',' 分隔")
+            self._skip_space()
+            if self.index >= len(self.text) or self.text[self.index] == "]":
+                self._error("flow list 不支持尾随逗号")
+
+    def _parse_map(self) -> dict[str, Any]:
+        self.index += 1
+        result: dict[str, Any] = {}
+        self._skip_space()
+        if self._consume("}"):
+            return result
+        while True:
+            self._skip_space()
+            if self.index >= len(self.text):
+                self._error("flow mapping 未结束")
+            if self.text[self.index] in {'"', "'"}:
+                key = self._parse_quoted()
+            else:
+                key = self._parse_plain({":"}, convert=False)
+            if not isinstance(key, str) or not key:
+                self._error("flow mapping key 必须是非空字符串")
+            if key == "<<":
+                self._error("ACK YAML 子集不支持 merge key '<<'")
+            self._skip_space()
+            if not self._consume(":"):
+                self._error("flow mapping key 后必须是 ':'")
+            value = self._parse_value()
+            if key in result:
+                self._error(f"flow mapping 存在重复键 {key!r}")
+            result[key] = value
+            self._skip_space()
+            if self._consume("}"):
+                return result
+            if not self._consume(","):
+                self._error("flow mapping 项之间必须用 ',' 分隔")
+            self._skip_space()
+            if self.index >= len(self.text) or self.text[self.index] == "}":
+                self._error("flow mapping 不支持尾随逗号")
+
+    def _parse_quoted(self) -> str:
+        quote = self.text[self.index]
+        self.index += 1
+        result: list[str] = []
+        while self.index < len(self.text):
+            char = self.text[self.index]
+            self.index += 1
+            if char == quote:
+                if quote == "'" and self.index < len(self.text) and self.text[
+                    self.index
+                ] == "'":
+                    result.append("'")
+                    self.index += 1
+                    continue
+                return "".join(result)
+            if quote == "'" or char != "\\":
+                result.append(char)
+                continue
+            if self.index >= len(self.text):
+                self._error("双引号标量以转义符结尾")
+            escape = self.text[self.index]
+            self.index += 1
+            simple = {
+                "0": "\0",
+                "a": "\a",
+                "b": "\b",
+                "t": "\t",
+                "n": "\n",
+                "v": "\v",
+                "f": "\f",
+                "r": "\r",
+                "e": "\x1b",
+                " ": " ",
+                '"': '"',
+                "/": "/",
+                "\\": "\\",
+            }
+            if escape in simple:
+                result.append(simple[escape])
+                continue
+            widths = {"x": 2, "u": 4, "U": 8}
+            if escape in widths:
+                width = widths[escape]
+                digits = self.text[self.index : self.index + width]
+                if len(digits) != width or not re.fullmatch(
+                    rf"[0-9a-fA-F]{{{width}}}", digits
+                ):
+                    self._error(f"无效 Unicode 转义 \\{escape}{digits}")
+                codepoint = int(digits, 16)
+                try:
+                    result.append(chr(codepoint))
+                except ValueError as exc:
+                    raise YamlSubsetError(
+                        f"第 {self.line_number} 行: 无效 Unicode 码点"
+                    ) from exc
+                self.index += width
+                continue
+            self._error(f"不支持的双引号转义 \\{escape}")
+        self._error("引号标量未结束")
+
+    def _parse_plain(
+        self,
+        delimiters: set[str],
+        *,
+        convert: bool = True,
+    ) -> Any:
+        start = self.index
+        while self.index < len(self.text) and self.text[self.index] not in delimiters:
+            self.index += 1
+        token = self.text[start : self.index].strip()
+        if not token:
+            self._error("空 plain scalar")
+        if "#" in token:
+            self._error("flow collection 内的注释不受支持")
+        if ": " in token:
+            self._error("plain scalar 中的 ': ' 必须加引号")
+        if token[0] in "!&*%@`?" or _ANCHOR_OR_ALIAS_RE.search(token):
+            self._error("ACK YAML 子集不支持 tag/anchor/alias/directive")
+        return _plain_scalar(token, self.line_number) if convert else token
+
+    def _skip_space(self) -> None:
+        while self.index < len(self.text) and self.text[self.index] == " ":
+            self.index += 1
+
+    def _consume(self, expected: str) -> bool:
+        if self.index < len(self.text) and self.text[self.index] == expected:
+            self.index += 1
+            return True
+        return False
+
+    def _error(self, message: str) -> None:
+        raise YamlSubsetError(f"第 {self.line_number} 行: {message}")
+
+
+def _plain_scalar(token: str, line_number: int) -> Any:
+    lowered = token.lower()
+    if lowered in {"null", "~"}:
+        return None
+    if lowered in {"true", "yes", "on"}:
+        return True
+    if lowered in {"false", "no", "off"}:
+        return False
+    if _DECIMAL_INT_RE.fullmatch(token):
+        return int(token, 10)
+    if _AMBIGUOUS_NUMBER_RE.fullmatch(token):
+        raise YamlSubsetError(
+            f"第 {line_number} 行: ACK YAML 子集不支持该数字格式 {token!r}，"
+            "如需字符串请加引号"
+        )
+    return token
@@ -0,0 +1,228 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://git.yumee.top/laily/skills/skills/ack/templates/delivery.schema.json",
+  "title": "ACK project delivery contract",
+  "description": "docs/ack/delivery.yaml 的权威结构；语义规则由 scripts/validate_delivery.py 补充。",
+  "type": "object",
+  "required": [
+    "version",
+    "project",
+    "enabled",
+    "defaultProfile",
+    "entrypoints",
+    "artifacts",
+    "destinations",
+    "environments",
+    "profiles"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "updatedAt": { "type": "string" },
+    "project": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "pattern": "\\S" }
+      }
+    },
+    "enabled": { "type": "boolean" },
+    "defaultProfile": {
+      "type": ["string", "null"],
+      "pattern": "^[a-z][a-z0-9-]{0,63}$"
+    },
+    "entrypoints": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/definitions/id" },
+      "additionalProperties": { "$ref": "#/definitions/entrypoint" }
+    },
+    "artifacts": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/definitions/id" },
+      "additionalProperties": { "$ref": "#/definitions/artifact" }
+    },
+    "destinations": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/definitions/id" },
+      "additionalProperties": { "$ref": "#/definitions/destination" }
+    },
+    "environments": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/definitions/id" },
+      "additionalProperties": { "$ref": "#/definitions/environment" }
+    },
+    "profiles": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/definitions/id" },
+      "additionalProperties": { "$ref": "#/definitions/profile" }
+    }
+  },
+  "definitions": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,63}$"
+    },
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._/*?+-]+$"
+    },
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "secretName": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
+    },
+    "entrypoint": {
+      "type": "object",
+      "required": [
+        "kind",
+        "args",
+        "requiredSecrets",
+        "workingDirectory",
+        "timeoutSeconds"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["make", "just", "task", "dagger", "script"]
+        },
+        "target": { "type": "string", "minLength": 1 },
+        "function": { "type": "string", "minLength": 1 },
+        "path": { "$ref": "#/definitions/relativePath" },
+        "args": { "$ref": "#/definitions/stringList" },
+        "requiredSecrets": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "#/definitions/secretName" }
+        },
+        "workingDirectory": { "$ref": "#/definitions/relativePath" },
+        "timeoutSeconds": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400
+        }
+      }
+    },
+    "artifact": {
+      "type": "object",
+      "required": ["type", "build"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "enum": ["deb", "oci-image", "file"] },
+        "build": { "$ref": "#/definitions/id" },
+        "outputs": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/definitions/relativePath" }
+        },
+        "image": { "type": "string", "minLength": 1 },
+        "platforms": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z0-9]+/[A-Za-z0-9._-]+$" }
+        }
+      }
+    },
+    "destination": {
+      "type": "object",
+      "required": ["type", "channel"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["apt-repository", "oci-registry", "ci-artifact"]
+        },
+        "channel": {
+          "type": "string",
+          "enum": ["preview", "staging", "stable"]
+        },
+        "registry": { "type": "string", "minLength": 1 },
+        "repository": { "type": "string", "minLength": 1 },
+        "endpoint": { "type": "string", "minLength": 1 },
+        "artifactName": { "type": "string", "minLength": 1 },
+        "upload": { "$ref": "#/definitions/id" }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "required": [
+        "type",
+        "classification",
+        "target",
+        "deploy",
+        "healthCheck",
+        "mutex"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["ssh-host", "docker-compose", "kubernetes", "custom"]
+        },
+        "classification": {
+          "type": "string",
+          "enum": ["development", "staging", "production"]
+        },
+        "target": { "type": "string", "minLength": 1 },
+        "deploy": { "$ref": "#/definitions/id" },
+        "healthCheck": { "$ref": "#/definitions/id" },
+        "rollback": { "$ref": "#/definitions/id" },
+        "mutex": { "type": "string", "minLength": 1 }
+      }
+    },
+    "step": {
+      "type": "object",
+      "required": ["id", "action"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/definitions/id" },
+        "action": {
+          "type": "string",
+          "enum": [
+            "verify",
+            "pull-request",
+            "build",
+            "publish",
+            "deploy",
+            "health-check",
+            "approval",
+            "mark-ready"
+          ]
+        },
+        "entrypoint": { "$ref": "#/definitions/id" },
+        "artifact": { "$ref": "#/definitions/id" },
+        "destination": { "$ref": "#/definitions/id" },
+        "environment": { "$ref": "#/definitions/id" },
+        "gate": { "type": "string", "enum": ["release", "production"] },
+        "draft": { "type": "boolean" },
+        "remote": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+        },
+        "baseBranch": { "type": "string", "minLength": 1, "maxLength": 255 }
+      }
+    },
+    "profile": {
+      "type": "object",
+      "required": ["stopAt", "steps"],
+      "additionalProperties": false,
+      "properties": {
+        "stopAt": {
+          "type": "string",
+          "enum": ["verified", "review_ready", "released"]
+        },
+        "steps": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/step" }
+        }
+      }
+    }
+  }
+}
@@ -0,0 +1,24 @@
+# 复制为 docs/ack/delivery.yaml。默认关闭；由用户明确配置后再启用。
+version: 1
+updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
+project:
+  name: "<project_name>"
+
+enabled: false
+defaultProfile: null
+
+# 所有可执行入口都使用结构化 argv 语义；requiredSecrets 只保存名称，不保存值。
+# 不在此保存 shell、env 或凭据正文。
+entrypoints: {}
+
+# 支持 deb、oci-image 和 file。复杂构建逻辑留在项目已有入口中。
+artifacts: {}
+
+# 支持 apt-repository、oci-registry 和 ci-artifact。
+destinations: {}
+
+# 支持 ssh-host、docker-compose、kubernetes 和 custom。
+environments: {}
+
+# enabled=true 时，defaultProfile 必须指向一个非空 profile。
+profiles: {}
@@ -0,0 +1,367 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://git.yumee.top/laily/skills/skills/ack/templates/knowledge.schema.json",
+  "title": "ACK project knowledge guardrails",
+  "description": "docs/ack/knowledge.yaml 的权威结构。知识只描述约束和验证引用，不保存可执行命令。",
+  "type": "object",
+  "required": ["version", "updatedAt", "project", "verificationRegistry", "entries"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "project": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "verificationRegistry": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/verificationTarget"
+      }
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/entry"
+      }
+    }
+  },
+  "definitions": {
+    "stableRef": {
+      "type": "string",
+      "pattern": "^K-[A-Z0-9][A-Z0-9-]*@[1-9][0-9]*$"
+    },
+    "stringSet": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      }
+    },
+    "scope": {
+      "type": "object",
+      "required": [
+        "all",
+        "components",
+        "paths",
+        "dependencies",
+        "versions",
+        "tags",
+        "symbols",
+        "errorSignatures"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "all": {
+          "type": "boolean"
+        },
+        "components": {
+          "$ref": "#/definitions/stringSet"
+        },
+        "paths": {
+          "$ref": "#/definitions/stringSet"
+        },
+        "dependencies": {
+          "$ref": "#/definitions/stringSet"
+        },
+        "versions": {
+          "$ref": "#/definitions/stringSet"
+        },
+        "tags": {
+          "$ref": "#/definitions/stringSet"
+        },
+        "symbols": {
+          "$ref": "#/definitions/stringSet"
+        },
+        "errorSignatures": {
+          "$ref": "#/definitions/stringSet"
+        }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "required": ["ref", "expected"],
+      "additionalProperties": false,
+      "properties": {
+        "ref": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+        },
+        "expected": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "verificationTarget": {
+      "type": "object",
+      "required": ["path", "args"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?=.*\\S)[A-Za-z0-9][A-Za-z0-9._/-]*$",
+          "description": "项目内可执行文件；运行时 cwd 为项目根，脚本不得依赖自身文件路径定位资源"
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "required": ["taskId", "attemptId", "codeRef", "evidenceRef"],
+      "additionalProperties": false,
+      "properties": {
+        "taskId": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "attemptId": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "codeRef": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "evidenceRef": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "required": [
+        "id",
+        "revision",
+        "kind",
+        "status",
+        "title",
+        "subject",
+        "scope",
+        "appliesWhen",
+        "directive",
+        "rationale",
+        "verification",
+        "provenance",
+        "owner",
+        "author",
+        "reviewer",
+        "approval",
+        "createdAt",
+        "lastValidatedAt",
+        "reviewAfter",
+        "temporary",
+        "removalCondition",
+        "statusReason",
+        "supersedes",
+        "conflictsWith"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^K-[A-Z0-9][A-Z0-9-]*$"
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["guardrail", "pitfall", "verification"]
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "stale", "superseded", "archived"]
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "subject": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z0-9][a-z0-9-]*$"
+        },
+        "scope": {
+          "$ref": "#/definitions/scope"
+        },
+        "appliesWhen": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "directive": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "rationale": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "verification": {
+          "$ref": "#/definitions/verification"
+        },
+        "provenance": {
+          "$ref": "#/definitions/provenance"
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "author": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "reviewer": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "approval": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "#/definitions/approval" }
+          ]
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "lastValidatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "reviewAfter": {
+          "type": ["string", "null"],
+          "format": "date-time"
+        },
+        "temporary": {
+          "type": "boolean"
+        },
+        "removalCondition": {
+          "type": ["string", "null"],
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "statusReason": {
+          "type": ["string", "null"],
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "supersedes": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/stableRef"
+          }
+        },
+        "conflictsWith": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/stableRef"
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "temporary": {
+                "const": true
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "reviewAfter": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "removalCondition": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "enum": ["stale", "superseded", "archived"]
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "statusReason": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      ]
+    },
+    "approval": {
+      "type": "object",
+      "required": ["approvedBy", "approvedAt", "evidenceRef"],
+      "additionalProperties": false,
+      "properties": {
+        "approvedBy": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "approvedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "evidenceRef": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    }
+  }
+}
@@ -0,0 +1,9 @@
+# 复制为 docs/ack/knowledge.yaml，替换占位符。结构见 templates/knowledge.schema.json。
+# Developer/Test 只能在任务证据中提出 candidate；只有 Coordinator 写入这里。
+version: 1
+updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
+project:
+  name: "<project_name>"
+# 检查 ID 映射到仓库内相对 path 和结构化 args；这里的内容不会被校验器执行。
+verificationRegistry: {}
+entries: []
@@ -0,0 +1,129 @@
+# <项目名> Agent 协作协议（项目覆盖层）
+
+> 本项目基于 ACK Skill v<ack_version>。通用规范由 `/ack` 从 Skill 自身的
+> `references/` 读取；本文件只保存项目差异。
+>
+> **本文件是「项目覆盖层」，文件名可配置。** 默认放 `docs/ack/project.md`，
+> 不占用 `AGENTS.md`，避免与团队已有的 `AGENTS.md` 约定冲突。
+> 若希望 Agent 自动加载，可由项目维护者自行在 `AGENTS.md` 中引用本文件；ACK
+> 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+> 无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。
+> `docs/ack/` 只保存本项目的 `project.md`、`tasks.yaml`、`knowledge.yaml` 与默认关闭的
+> `delivery.yaml`，
+> 不复制或链接 Skill。
+
+## 项目概览
+
+- 项目：`<project_name>`
+- 技术栈：`<tech_stack>`
+- 运行命令：`<run_command>`
+- Base URL：`<base_url>`
+- 任务板：`docs/ack/tasks.yaml`
+- 项目知识：`docs/ack/knowledge.yaml`
+- 交付契约：`docs/ack/delivery.yaml`（默认关闭）
+- 覆盖层文件：`<overlay_file_path>`（默认 `docs/ack/project.md`）
+
+## 通用规范（由 ACK Skill 按需读取）
+
+- 开始需求：`references/kickoff.md`
+- 角色、权限、状态机与完成定义：`references/roles-and-permissions.md`
+- 模型档位与升级规则：`references/model-routing.md`
+- 闭环流程与 worktree 对齐：`references/closed-loop.md`
+- 验收信号与三轮策略：`references/optimization-method.md`
+- 派发 prompt 模板：`references/prompt-templates.md`
+- Orca 编排命令（可选）：`references/orca-adapter.md`
+- 验证后交付与配置维护（可选）：`references/delivery.md`
+- 一次性源码/DEB/镜像发布路由（可选）：`references/delivery-routing.md`
+
+## Worker 路由
+
+机器可校验的模型、reasoning effort、权限模式、默认 profile、允许 worktree 和启动
+receipt 全部以 `docs/ack/tasks.yaml` 的 `project.orchestration` 与顶层
+`workerReceipts` 为准。本文件不保存可执行 worker 命令。
+
+默认 profile：
+
+| 角色 | profile ID | 档位 |
+|------|------------|------|
+| Developer | `codex-dev-standard` | standard |
+| Test | `codex-test-standard` | standard |
+| Operator | `codex-operator-standard` | standard（模型/effort 与 Test 相同） |
+| Developer 升级 | `codex-dev-strong` | strong |
+
+项目如改用 Cursor，应修改结构化 profile、allowlist 和 defaults，再运行任务板
+校验；不能在这里粘贴 `orca --command`、Agent CLI 参数或自由 shell。
+每次自动派发必须先审阅 launcher plan，再把其中的 `launchFingerprint` 作为
+`--expected-launch-fingerprint` 启动 fresh worker。v0.10 的 `receiptHash` 只作
+审计 checksum，不授权自动复用旧终端。
+
+## 路径权限（项目覆盖层，必须填实际路径）
+
+| 路径 | Coordinator | Test | Developer | 说明 |
+|------|:-----------:|:----:|:---------:|------|
+| `<spec_paths>` | R/W | Read-only | Read-only | 产品规格、API 文档、计划（PM 拥有） |
+| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器/API 回归（Test 拥有） |
+| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录 |
+| `<source_paths>` | Read-only | Read-only | R/W | 应用源码 |
+| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
+| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
+| `<local_config_paths>` | Read-only | Read-only | Read-only | 本地私有配置 |
+| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
+| `knowledge.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写；Developer/Test 通过回报提名或验证 |
+| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 项目交付能力，不是执行授权 |
+
+## 命令（项目覆盖层）
+
+Developer 白盒验证：
+
+```bash
+<unit_test_command>
+<build_command>
+<local_run_command>
+```
+
+Test 黑盒复测：
+
+```bash
+<preflight_command>
+<api_smoke_command>
+<browser_regression_command>
+```
+
+知识项的 `verification.ref` 只能引用 `knowledge.yaml.verificationRegistry` 中已
+审查的检查入口。Registry 只保存仓库内相对 path 和结构化 args，不保存或执行自由
+shell 命令；新项目没有知识时保持空对象。Developer/Test 只能把 registry ID 交给
+Skill 的 `scripts/run_verification.py` 执行，不直接拼接 path/args。检查脚本从项目
+根 cwd 或 `ACK_PROJECT_ROOT` 定位资源，不能依赖自身文件路径。
+`ACK_PROJECT_ROOT` 是 runner 固定的根目录 fd 路径；仅用于日志的原始路径位于
+`ACK_PROJECT_ROOT_DISPLAY`。
+
+项目状态校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py`、
+`scripts/validate_knowledge.py` 和 `scripts/validate_delivery.py` 执行。
+构建/发布/部署的机器入口以 `delivery.yaml` 为准；本文件不维护第二套交付命令。
+
+## 硬规则（其余见 references/）
+
+- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
+- 一次性交付 Operator 不进入三角色闭环；它使用 Test 同档模型执行被路由的低层 Skill，
+  只回传证据，不写 ACK 状态文件。
+- 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 references/model-routing.md）。
+- 自动 worker 只能由 ACK 的 `scripts/launch_worker.py` 按结构化 profile 启动；
+  禁止直接拼 `orca terminal create --command`，禁止 `command`、`extraArgs`、`env`
+  等第二配置面。
+- v0.10 自动 launcher 只支持 `read-only` 和 `workspace-write`。full-access、
+  bypass、YOLO/force 与关闭 sandbox 均 fail closed；需要可信平台审批通道后再开放。
+- v0.10 不自动复用持久化 receipt 指向的旧终端；每次自动派发都重新 plan/launch。
+- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
+- 只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`；Developer 与 Test 都只读，
+  通过消息回报。
+- Coordinator 只派发按 scope 命中并显式写入 `knowledgeRefs` 的 `active` 知识；
+  `candidate` 不派发，知识库不全量注入。
+- Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
+  `knowledgeChecks`。关键约束应下沉为测试、lint、CI 或正式规范。
+- ACK 不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+- `delivery.yaml` 默认关闭，只描述能力，不自动授权提交、推送、发布或部署；交付仅在
+  任务 `verified` 且本次 profile/目标/停止点得到确认后运行。
+- 默认交付 profile 最多到 `review_ready`；stable 发布或 production 部署必须有
+  approval 步骤并再次获得明确批准。配置变更只影响下一次 run。
+- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
+- 不提交、推送、发布或部署，除非用户确认的 ACK 任务或 delivery profile 明确包含。
@@ -0,0 +1,163 @@
+# 复制为 docs/ack/tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
+version: 1
+updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
+source: "Coordinator (PM) Agent"
+ackVersion: "<接入时的 ack skill 版本>"
+project:
+  name: "<project_name>"
+  repoPath: "<repo_path>"
+  baseUrl: "<base_url>"
+  devWorktree: "<dev_worktree>"
+  overlayFile: "docs/ack/project.md"
+  knowledgeFile: "docs/ack/knowledge.yaml"
+  deliveryFile: "docs/ack/delivery.yaml"
+  orchestration:
+    profileVersion: 1
+    mode: "orca"
+    allowedWorktrees:
+      - "<dev_worktree>"
+    modelAllowlist:
+      codex:
+        developer:
+          standard: ["gpt-5.6-terra"]
+          strong: ["gpt-5.6-sol"]
+        test:
+          standard: ["gpt-5.6-luna"]
+        operator:
+          standard: ["gpt-5.6-luna"]
+      cursor-agent:
+        developer:
+          standard: ["auto"]
+        test:
+          standard: ["auto"]
+        operator:
+          standard: ["auto"]
+    profiles:
+      codex-dev-standard:
+        role: "developer"
+        cli: "codex"
+        tier: "standard"
+        model: "gpt-5.6-terra"
+        reasoningEffort: "medium"
+        permissionMode: "workspace-write"
+      codex-test-standard:
+        role: "test"
+        cli: "codex"
+        tier: "standard"
+        model: "gpt-5.6-luna"
+        reasoningEffort: "low"
+        permissionMode: "workspace-write"
+      codex-operator-standard:
+        role: "operator"
+        cli: "codex"
+        tier: "standard"
+        model: "gpt-5.6-luna"
+        reasoningEffort: "low"
+        permissionMode: "workspace-write"
+      codex-dev-strong:
+        role: "developer"
+        cli: "codex"
+        tier: "strong"
+        model: "gpt-5.6-sol"
+        reasoningEffort: "high"
+        permissionMode: "workspace-write"
+      cursor-dev-standard:
+        role: "developer"
+        cli: "cursor-agent"
+        tier: "standard"
+        model: "auto"
+        reasoningEffort: null
+        permissionMode: "workspace-write"
+      cursor-test-standard:
+        role: "test"
+        cli: "cursor-agent"
+        tier: "standard"
+        model: "auto"
+        reasoningEffort: null
+        permissionMode: "workspace-write"
+      cursor-operator-standard:
+        role: "operator"
+        cli: "cursor-agent"
+        tier: "standard"
+        model: "auto"
+        reasoningEffort: null
+        permissionMode: "workspace-write"
+    defaults:
+      developer: "codex-dev-standard"
+      test: "codex-test-standard"
+      operator: "codex-operator-standard"
+      developerUpgraded: "codex-dev-strong"
+
+workerReceipts: []
+deliveryRuns: []
+
+summary:
+  verified: []
+  open: []
+  failedRetest: []
+  leftovers: []
+
+tasks:
+  - id: "BUG-001"
+    type: "bug"
+    title: "<short title>"
+    priority: "P0"
+    status: "open"
+    assignee: "developer"
+    component: "<source file or module>"
+    specRefs:
+      - "<docs/spec.md#section>"
+    testRefs:
+      - "<tests/browser/cases/01-case.md>"
+    knowledgeRefs: []
+    knowledgeApplied: []
+    knowledgeCandidates: []
+    knowledgeChecks: []
+
+    description: >
+      <What is wrong, in user-visible terms.>
+
+    stepsToReproduce:
+      - "<step 1>"
+      - "<step 2>"
+
+    expected: >
+      <Expected behavior.>
+
+    actual: >
+      <Actual behavior observed by Test.>
+
+    evidence:
+      browser: "<snapshot text, screenshot path, or UI finding>"
+      api: "<curl result or API mismatch>"
+      logs: "<relevant log line if any>"
+
+    verification:
+      commands:
+        - "<unit/build command>"
+        - "<browser/API smoke command>"
+      browser:
+        page: "<page path>"
+        checks:
+          - "<visible text or interaction expected>"
+
+    dispatch:
+      developer:
+        profileId: "codex-dev-standard"
+        receiptId: null
+        attemptId: null
+        taskId: null
+        dispatchId: null
+      test:
+        profileId: "codex-test-standard"
+        receiptId: null
+        attemptId: null
+        taskId: null
+        dispatchId: null
+      rounds: []
+
+    resolution:
+      fixedBy: null
+      verifiedBy: null
+      verifiedAt: null
+      leftoverReason: null
@@ -0,0 +1,80 @@
+# deb-publisher
+
+帮助 Agent 复用项目已有的 DEB 打包与发布方式，完成构建、包检查、上传和发布验证。
+
+## 什么时候使用
+
+当你希望 Agent 处理以下任务时使用：
+
+- “帮我构建这个项目的 DEB 包”
+- “把 1.2.3 版本的 DEB 发布到包仓库”
+- “看看项目里的 DEB 发布流程”
+- “检查这个 DEB 是否可以发布”
+
+只想在本机安装一个 `.deb`，或者要构建 RPM、Docker 镜像时，不需要使用这个 skill。
+
+## 使用前准备
+
+请准备或确认：
+
+- 要构建或发布的版本号。
+- 项目已经配置好构建脚本、Make 目标或 `debian/` 目录；上传脚本由 skill 自带，
+  不需要放进项目。
+- 发布所需的令牌已经放入项目约定的环境变量或密钥系统。
+- 如果要真实发布，明确告诉 Agent 目标仓库以及是否允许覆盖同版本。
+
+不要把令牌直接粘贴到对话、命令参数或项目文件中。
+
+## 使用示例
+
+仅分析，不产生或上传包：
+
+```text
+看看这个项目的 DEB 是怎么构建和发布的。
+```
+
+只构建和检查，不上传：
+
+```text
+使用 deb-publisher 构建 1.2.3 的 DEB，检查包元数据和内容，不要上传。
+```
+
+构建并发布：
+
+```text
+使用 deb-publisher 构建并发布 1.2.3 的 amd64 DEB 到项目已配置的测试仓库。
+```
+
+发布已有产物：
+
+```text
+使用 deb-publisher 检查并发布 ./dist/example_1.2.3_amd64.deb。
+```
+
+## Agent 会做什么
+
+Agent 会优先发现和复用项目已有入口，然后：
+
+1. 确认版本、架构、产物路径、目标仓库和授权范围。
+2. 构建 DEB，或定位你指定的已有产物。
+3. 检查包的元数据、内容和 SHA-256。
+4. 在你明确要求发布时，通过 skill 自带的 `scripts/upload_deb.sh` 上传。
+5. 检查服务端响应，并在仓库支持时确认该版本已经可见。
+
+## 如何判断完成
+
+结果中应包含包名、版本、架构、产物路径、SHA-256，以及构建、上传和仓库可见性的
+独立状态。异步索引尚未完成时，Agent 应明确说明“上传已接受，索引待更新”。
+
+## 上传协议
+
+自带脚本适用于接收 multipart 字段 `package`、`token` 和 `repository_name` 的
+HTTP DEB 仓库，默认路径是 `/api/v2/upload/package`。使用以下环境变量：
+
+- `DEB_SERVER_URL`：仓库服务地址。
+- `DEB_TOKEN`：认证令牌。
+- `DEB_REPOSITORY`：目标仓库名。
+- `DEB_UPLOAD_PATH`：可选的上传路径覆盖。
+
+令牌只从环境变量读取，不作为命令行参数传递。若你的仓库使用其他 API 协议，应先告诉
+Agent，不要直接套用该脚本。
@@ -0,0 +1,150 @@
+---
+name: deb-publisher
+description: >-
+  构建并发布 Debian DEB 包：发现项目已有的 Makefile 和打包入口，使用 skill 自带的
+  通用上传脚本提交包，校验包元数据与内容，并验证发布结果。触发词：构建 deb、
+  发布 deb、上传 deb、提交 deb、推送 apt 仓库、打 Debian 包。仅分析打包逻辑时也可使用，
+  但不会在未获授权时执行上传。
+---
+
+# DEB Publisher
+
+复用项目已有发布约定，安全地完成“发现入口 → 构建 → 检查 → 上传 → 验证”。
+
+## 何时使用
+
+- 用户要求构建、发布、上传或提交 `.deb` 包。
+- 用户要求梳理或接通项目现有的 DEB 发布流程。
+- 用户要求把已经生成的 `.deb` 推送到 APT/DEB 包仓库。
+
+## 不适用
+
+- 只需要安装或卸载本地 DEB 包。
+- 目标是 RPM、APK、容器镜像或语言包管理器。
+- 用户只要求设计全新的 Debian 打包体系；此时应先完成方案设计。
+
+## 工作流
+
+### 1. 发现项目约定
+
+从项目根目录查找，不预设文件位置：
+
+```bash
+rg -n -i --hidden --glob '!.git' \
+  'build-deb|upload-deb|publish-deb|dpkg-deb|debuild|curl.*deb|\.deb\b|aptly|reprepro'
+```
+
+重点检查：
+
+- `Makefile`、CI 配置、`debian/`、构建脚本和发布文档。
+- 版本号、包名、架构、产物目录和仓库名如何传入。
+- 发布端点、认证方式以及发布是否由构建目标自动触发。
+- 当前工作树和目标版本是否匹配。
+
+优先复用已有构建入口。上传默认使用本 skill 的 `scripts/upload_deb.sh`，不要把它
+复制到项目中；仅当目标仓库协议不兼容时才复用或修改项目专属上传逻辑。
+
+### 2. 确认发布边界
+
+上传是外部写操作。仅当用户明确要求发布、上传或提交时执行；若用户只要求查看、
+诊断或构建，则停在相应阶段。
+
+执行上传前确认：
+
+- 目标服务和仓库来自项目配置或用户输入，不猜测生产端点。
+- 认证令牌已通过环境变量或密钥系统提供。
+- 目标版本、架构和产物路径能够从构建配置推导。
+- 相同版本是否允许覆盖；无法确认且可能覆盖时，先询问用户。
+
+绝不把令牌写入命令输出、文件、提交或最终回复。不要用 `set -x` 执行含凭据的脚本。
+
+### 3. 构建包
+
+使用项目声明的构建目标，并显式传入版本。例如项目提供 Make 目标时：
+
+```bash
+make build-deb VERSION="$RELEASE_VERSION"
+```
+
+如果构建目标会自动上传，而当前仅获构建授权，应改用其纯构建子目标。执行前检查
+所需工具和环境，例如 Docker、`dpkg-deb`、编译器、SSH 访问或前端工具链。
+
+不得擅自清理宽泛目录。若脚本包含 `rm -rf`，先解析并确认目标是明确、受限的构建目录。
+
+### 4. 上传前检查
+
+定位唯一目标产物；若匹配多个包，不凭文件时间猜测：
+
+```bash
+find <artifact-dir> -maxdepth 2 -type f -name '*.deb' -print
+dpkg-deb --info <package.deb>
+dpkg-deb --contents <package.deb>
+```
+
+至少验证：
+
+- 文件存在、非空且 `dpkg-deb --info` 成功。
+- `Package`、`Version`、`Architecture` 与本次发布一致。
+- 包内容包含预期的主程序或关键文件。
+- maintainer scripts 存在时权限正确，且没有明显的宿主机破坏性操作。
+
+建议记录 SHA-256：
+
+```bash
+sha256sum <package.deb>
+```
+
+### 5. 发布
+
+解析当前 `SKILL.md` 所在目录，以绝对路径调用随 skill 分发的脚本：
+
+```bash
+DEB_SERVER_URL="$DEB_SERVER_URL" \
+DEB_TOKEN="$DEB_TOKEN" \
+DEB_REPOSITORY="$DEB_REPOSITORY" \
+  <skill-dir>/scripts/upload_deb.sh <exact-package-path.deb>
+```
+
+不要把脚本复制进当前项目，也不要将 token 作为命令行参数。脚本默认请求
+`/api/v2/upload/package`，以 multipart 字段 `package`、`token`、
+`repository_name` 上传，接受 `200` 和 `201` 为成功。端点路径不同时可设置
+`DEB_UPLOAD_PATH`。
+
+调用前确认目标服务使用上述协议；不兼容时不要强行调用。传入刚刚校验过的确切路径，
+不要使用宽泛 glob。项目已有 `make upload-deb` 时，检查它是否只是包装了同一协议：
+如果是，直接使用 skill 脚本；若 CI 或其他人仍依赖 Make 目标，可将目标改为调用已安装
+skill 的脚本，但不要提交脚本副本。
+
+脚本支持多个确切文件路径，会汇总每个文件的结果，并在任一失败时返回非零。
+
+### 6. 验证与汇报
+
+发布成功不能只依据“curl 已执行”。综合检查：
+
+- 上传命令退出码为零。
+- HTTP 状态和响应体明确表示成功。
+- 若仓库提供只读查询、索引或下载地址，再确认该包和版本已可见。
+- 若索引更新是异步的，报告“上传已接受，索引尚待更新”，不要声称已完全可用。
+
+最终回复给出：
+
+- 包名、版本、架构。
+- 产物路径和 SHA-256。
+- 目标服务/仓库的非敏感标识。
+- 构建、上传及仓库可见性各自的验证结果。
+- 任何未完成项或回滚/覆盖风险。
+
+## 修改已有发布逻辑时
+
+- 保持项目现有变量名和调用入口，避免无关重构。
+- 修复行为缺陷时增加最小静态检查或可离线运行的测试。
+- 可用 `bash -n` 检查脚本语法；项目有 ShellCheck 时一并运行。
+- skill 自带上传脚本是 SSOT；通用上传行为的修改应落在
+  `skills/deb-publisher/scripts/upload_deb.sh`，不要同步复制到业务项目。
+- 不通过真实生产上传来测试脚本，除非用户明确授权并给出测试版本或测试仓库。
+
+## 完成标准
+
+- 仅分析：入口、调用链、配置来源和风险已被准确说明。
+- 仅构建：DEB 已生成，元数据、内容和校验和通过检查，未发生上传。
+- 发布：构建检查通过，服务端接受上传，且仓库可见性已验证或被准确标记为待更新。
@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  DEB_SERVER_URL=https://deb.example.com \
+  DEB_TOKEN=secret \
+  DEB_REPOSITORY=main \
+    upload_deb.sh FILE.deb [FILE.deb ...]
+
+Options:
+  -s SERVER_URL       Override DEB_SERVER_URL
+  -n REPOSITORY       Override DEB_REPOSITORY
+  -p UPLOAD_PATH      Override DEB_UPLOAD_PATH (default: /api/v2/upload/package)
+  -h                  Show help
+
+The endpoint must accept multipart fields named package, token, and
+repository_name. Authentication is read only from DEB_TOKEN so it is not
+exposed in the process command line.
+EOF
+}
+
+server_url=${DEB_SERVER_URL:-}
+repository=${DEB_REPOSITORY:-}
+upload_path=${DEB_UPLOAD_PATH:-/api/v2/upload/package}
+token=${DEB_TOKEN:-}
+
+while getopts ":s:n:p:h" option; do
+  case "$option" in
+    s) server_url=$OPTARG ;;
+    n) repository=$OPTARG ;;
+    p) upload_path=$OPTARG ;;
+    h) usage; exit 0 ;;
+    :) echo "Error: -$OPTARG requires a value" >&2; usage >&2; exit 2 ;;
+    \?) echo "Error: unknown option -$OPTARG" >&2; usage >&2; exit 2 ;;
+  esac
+done
+shift $((OPTIND - 1))
+
+if [[ -z "$server_url" || -z "$repository" || -z "$token" || $# -eq 0 ]]; then
+  echo "Error: DEB_SERVER_URL, DEB_TOKEN, DEB_REPOSITORY, and at least one file are required." >&2
+  usage >&2
+  exit 2
+fi
+if [[ "$upload_path" != /* ]]; then
+  echo "Error: upload path must start with /" >&2
+  exit 2
+fi
+if ! command -v curl >/dev/null 2>&1; then
+  echo "Error: curl is required." >&2
+  exit 2
+fi
+
+server_url=${server_url%/}
+success_count=0
+fail_count=0
+response_file=
+
+cleanup() {
+  if [[ -n "$response_file" && -f "$response_file" ]]; then
+    rm -f -- "$response_file"
+  fi
+}
+trap cleanup EXIT
+
+print_response() {
+  local file=$1
+  if command -v jq >/dev/null 2>&1 && jq -e . "$file" >/dev/null 2>&1; then
+    jq . "$file"
+  else
+    cat -- "$file"
+  fi
+}
+
+for package_file in "$@"; do
+  if [[ ! -f "$package_file" ]]; then
+    echo "Skip: file not found: $package_file" >&2
+    fail_count=$((fail_count + 1))
+    continue
+  fi
+  if [[ "$package_file" != *.deb ]]; then
+    echo "Skip: not a .deb file: $package_file" >&2
+    fail_count=$((fail_count + 1))
+    continue
+  fi
+  if [[ ! -s "$package_file" ]]; then
+    echo "Skip: empty file: $package_file" >&2
+    fail_count=$((fail_count + 1))
+    continue
+  fi
+
+  response_file=$(mktemp)
+  echo "Uploading $(basename -- "$package_file") to $server_url (repository $repository)..."
+
+  http_code=000
+  if http_code=$(curl --silent --show-error \
+    --output "$response_file" \
+    --write-out "%{http_code}" \
+    --request POST \
+    "$server_url$upload_path" \
+    --form "package=@${package_file};type=application/vnd.debian.binary-package" \
+    --form "token=${token}" \
+    --form "repository_name=${repository}"); then
+    :
+  else
+    echo "Failed (transport error): $(basename -- "$package_file")" >&2
+    print_response "$response_file" >&2
+    fail_count=$((fail_count + 1))
+    cleanup
+    response_file=
+    continue
+  fi
+
+  if [[ "$http_code" == 200 || "$http_code" == 201 ]]; then
+    echo "Success ($http_code): $(basename -- "$package_file")"
+    print_response "$response_file"
+    success_count=$((success_count + 1))
+  else
+    echo "Failed ($http_code): $(basename -- "$package_file")" >&2
+    print_response "$response_file" >&2
+    fail_count=$((fail_count + 1))
+  fi
+
+  cleanup
+  response_file=
+done
+
+echo "Done. Success: $success_count, Failed: $fail_count"
+if ((fail_count > 0)); then
+  exit 1
+fi
+
@@ -0,0 +1,121 @@
+# manage-release
+
+`manage-release` 帮助 Agent 管理从开发版本到发布的 Git 流程，包括 worktree、分支、
+版本号、PR/MR、合并和 release tag。它可以只处理其中一个阶段，也可以从准备开发目录
+一直执行到发布。
+
+## 使用前准备
+
+- 项目已经是 Git 仓库，并配置了可访问的远端。
+- 项目已有版本文件或发布约定；没有时可以让 Agent 先给出版本建议。
+- 创建或合并 PR/MR、创建 Forge Release 时，准备好 GitHub、GitLab、Gitea 或 Forgejo
+  对应的已认证 CLI。只发布 Git tag 时不要求 Forge CLI，但 Git remote 必须可读写。
+- 请求里写清目标版本、基线分支，以及允许执行到哪一步。没有明确授权的远端写操作
+  不会执行。
+
+## 常见用法
+
+### 通过 ACK 只创建普通 PR
+
+```text
+$ack 把当前分支推送并创建一个指向 main 的 PR，不要合并。
+```
+
+ACK 会把这类一次性请求路由到 `manage-release` 的 PR-only 流程。Agent 只核对当前
+head、base、remote、提交边界、验证和 Forge 账号，然后创建或复用 PR；不会顺带升级
+版本、创建 release 分支、合并、打 tag 或创建 Forge Release。
+
+### 确定下一个版本号
+
+```text
+使用 manage-release 检查当前版本和这次改动，建议下一个版本号。只分析，不修改文件。
+```
+
+适合还没决定该发 patch、minor 还是 major 时使用。Agent 会读取项目版本规则、现有 tag
+和实际改动，给出建议及依据。
+
+### 开始开发新版本
+
+```text
+使用 manage-release，从 main 为 1.6.0 创建独立 worktree 和分支。先不要 push，也不要创建 PR。
+```
+
+Agent 会检查已有 worktree、分支和 tag，确认没有冲突后准备开发目录。这个请求只授权
+本地操作。
+
+### 把开发分支提交为 PR
+
+```text
+使用 manage-release 检查当前分支，更新版本号和 CHANGELOG，运行项目测试，然后 push 并创建指向 main 的 PR。不要合并。
+```
+
+适合开发已经完成，只需要整理版本信息并送审。Agent 会停在 PR 创建成功的位置，返回
+PR 地址、测试结果和待处理项。
+
+### 合并通过检查的 PR
+
+```text
+使用 manage-release 检查当前 PR。如果 CI、review 和冲突检查都通过，就按项目规则合并；不要打 tag。
+```
+
+Agent 只会在仓库要求全部满足后合并，不会使用管理员权限绕过保护规则。合并完成后会
+返回准确的 merged commit。
+
+### 为已合并版本发布 tag
+
+```text
+使用 manage-release，为已经合并到 main 的 1.6.0 发布 v1.6.0 tag。确认 tag 指向包含该版本号的 merged commit，不要创建 Forge Release。
+```
+
+适合依靠 Git tag 触发后续 CI 发布的项目。Agent 会分别验证版本文件、目标 commit 和
+远端 tag，不会给未合并分支打正式 tag。
+
+### 完成端到端发布
+
+```text
+使用 manage-release 完成 1.6.0 发布：从 main 创建 worktree 和分支，完成版本更新和验证，创建 PR，检查通过后合并，推送 v1.6.0 tag，并创建 Forge Release。
+```
+
+这条请求授权完整流程。遇到 review 未通过、CI 失败、版本冲突或已有同名 tag 时，
+Agent 会停止并说明卡在哪一步，不会绕过检查继续发布。
+
+### 发布紧急修复版本
+
+```text
+使用 manage-release 从 main 准备 1.6.1 hotfix。创建独立 worktree，完成修复后开 PR；检查通过就合并并发布 v1.6.1。
+```
+
+适合线上问题修复。Skill 仍走正常 PR 和保护分支流程，不会因为是 hotfix 就直接推送
+main 或覆盖已有 tag。
+
+### 从中断位置继续
+
+```text
+使用 manage-release 检查 v1.6.0 当前发布状态，从尚未完成的步骤继续。不要重复创建分支、PR、tag 或 release。
+```
+
+适合合并后打 tag 失败、tag 已推送但 release 未创建，或者 Agent 会话中断的情况。
+Skill 会从 Git 和代码托管平台重新判断状态，再继续缺失的步骤。
+
+## Agent 会做什么
+
+Agent 会先发现项目自己的版本、分支和发布规则，再检查本地 Git 与远端状态。它只执行
+请求中明确授权的阶段，并在合并、tag 或 release 条件不满足时停止。完整流程结束后，
+结果中会分别列出 worktree、分支、版本、PR/MR、merged commit、tag 和 Forge Release
+状态。
+
+## 如何判断完成
+
+- 只分析版本时，结果包含建议版本及依据。
+- 创建开发环境时，结果包含 worktree 路径、分支和基线 commit。
+- 创建或合并 PR/MR 时，结果包含 URL、检查状态和 merged commit。
+- 发布 tag 时，远端 tag 解引用后的 commit 与 merged commit 一致。
+- 创建 Forge Release 时，结果包含可访问的 release URL。
+- 中途停止时，结果说明停在哪一步、为什么停止，以及下次如何继续。
+
+## 不适用的场景
+
+普通功能开发、普通 worktree 或 PR/MR 操作、代码审查、构建 Docker 镜像或上传 DEB 包
+不需要直接触发 `manage-release`。只有任务明确涉及版本发布、发布分支、版本号、发布
+PR/MR 或 release tag，或者用户显式调用 `$ack` 要求 PR-only 委派时，才交给这个
+Skill。
@@ -0,0 +1,211 @@
+---
+name: manage-release
+description: >-
+  管理 Git 项目从开发版本到发布的完整生命周期：发现并遵循项目分支与版本策略，
+  创建或复用隔离 worktree 和版本分支，确定并同步版本号，推送并创建、检查或合并
+  PR/MR，在合并后的准确提交上创建并推送 release tag，并按需创建 Forge Release、
+  恢复中断流程或安全清理。用户要求开始发布相关的新版本、为发布开 worktree 或分支、
+  升版本、提交或合并发布 PR/MR、打 release tag、完成发版、处理 hotfix 或继续未完成
+  发布时使用。只做普通编码、普通 worktree 或 PR/MR 操作、代码审查、构建或上传
+  DEB/Docker 等产物、管理仓库权限时不使用。
+  由显式调用的 `$ack` 根据用户明确的普通 PR/MR 请求路由时，可只执行本文的
+  PR-only 流程，不把它扩大成版本发布。
+---
+
+# Manage Release
+
+根据项目现有规则管理源码版本生命周期。把项目策略当作规则来源，把 Git 与代码托管
+平台的实时状态当作运行状态；不要创建另一份会与分支、PR/MR 或 tag 分叉的状态文件。
+
+## 按需读取参考资料
+
+- 开始任何流程时读取 [project-policy.md](references/project-policy.md)，确定策略来源和默认值。
+- 需要选择、更新或核对版本号时读取 [versioning.md](references/versioning.md)。
+- 需要 push、创建或合并 PR/MR、创建 Forge Release 时读取
+  [forge-adapters.md](references/forge-adapters.md)。
+- 遇到重复资源、并发冲突、部分成功或清理请求时读取
+  [recovery.md](references/recovery.md)。
+- 仅当用户要求为项目固化发布规则时，复制并修改
+  [release-policy.template.yaml](templates/release-policy.template.yaml)。不要在普通发布中自动添加配置。
+
+## 授权边界
+
+### ACK PR-only 委派
+
+当且仅当用户显式调用 `$ack`，且 ACK 把用户原始的普通 PR/MR 请求委派给本 Skill 时，
+使用 PR-only 流程：执行“发现项目规则和当前状态”，锁定准确 head、base、remote、
+worktree、验证命令与活动 Forge 账号，然后只执行“推送并创建 PR/MR”及其完成检查。
+用户没有明确要求时，不创建 release 分支、不修改版本或 CHANGELOG、不合并、不打 tag、
+不创建 Forge Release、不清理分支或 worktree。缺少 head/base/remote、提交边界或平台
+认证时按硬停止条件报告，不把普通 PR 伪装成发布。
+
+ACK 只负责路由，不增加授权。Operator 收到的原始请求仍是权限上限；“创建 PR”只授权
+为准确 head/base 创建或复用 PR，不自动授权合并。
+
+按用户明确要求执行到对应阶段：
+
+- 分析版本或检查状态：只执行读取和计算，不修改文件或远端。
+- 开始或准备版本：允许创建本地分支、worktree，并修改版本文件。
+- push 或创建 PR/MR：仅在用户明确要求 push、提交 PR/MR 或执行完整发布时进行。
+- 合并和推送 tag：仅在用户明确要求相应动作或完整发布时进行。
+- 创建 Forge Release：仅在用户本次请求明确提到 Forge Release 或平台 Release 时进行。
+- 清理 worktree 或分支：仅在用户明确要求清理时进行。
+
+项目策略只描述仓库期望的做法，不能替用户授予 push、创建或合并 PR/MR、推送 tag、
+创建 Forge Release、删除分支等外部写权限。
+
+“完整处理并发布 v1.2.3”可以授权从准备到验证远端 tag 的流程，不要在每一步重复询问；
+它不自动包含 Forge Release 或分支清理。若版本、base、tag、远端或合并方式是推断所得，
+或者执行中目标发生变化，在第一次远端写操作前展示准确目标并获得确认。
+
+## 工作流
+
+PR-only 仍按以下章节做实时状态发现与安全检查，但跳过与用户请求无关的版本计算、
+release worktree、版本文件、合并和 tag 阶段。已有用户工作不得被 stash、移动或覆盖。
+
+### 1. 发现项目规则和当前状态
+
+从项目根目录开始：
+
+1. 从可信 base commit 读取 `AGENTS.md`、`CLAUDE.md`、发布文档、CI 配置、构建入口和
+   可选的 `.release-policy.yaml`。PR/MR head 对这些文件的修改从下一次流程开始生效。
+2. 记录当前分支、HEAD、完整工作区状态、remote、默认分支和
+   `git worktree list --porcelain`。
+3. 获取远端最新引用后，记录 base 分支的准确 commit。不要把本地过期分支当作发布基线。
+4. 识别版本来源、最近稳定 tag、tag 格式、分支命名、合并方式和发布说明来源。
+5. 分别检查 Git remote 的读取与推送能力，以及 PR/MR、合并或 Forge Release 阶段所需的
+   GitHub、GitLab、Gitea 或 Forgejo CLI。只有请求涉及平台能力时才要求对应 CLI。
+   记录匹配该 host 的活动账号；认证检查只读取状态。
+6. 查询已有分支、worktree、PR/MR、tag 和 Forge Release，从真实状态判断流程已走到哪一步。
+
+工作区中的修改、暂存文件和未跟踪文件都视为用户工作。不要 stash、移动、清理或覆盖它们。
+已有 worktree 与目标分支准确匹配时优先复用，不要创建副本。
+
+### 2. 锁定本次发布计划
+
+在修改前确定并展示：
+
+- base 分支及其远端 commit。
+- 当前版本、规范化后的目标版本、渲染出的分支名和 tag，以及升级依据。
+- 分支名与 worktree 路径。
+- 需要执行的本地验证和远端检查。
+- 合并方式、tag、是否创建 Forge Release。
+- 用户已授权的最远阶段和清理范围。
+
+项目没有约定时，单一协调版本使用 SemVer、`release/v<version>` 分支、
+`v<version>` annotated tag。仓库只启用一种合并方式时使用该方式；存在多种方式且没有
+项目规则时默认 squash。默认不删除远端分支，不自动创建 Forge Release。
+
+把用户输入拆成“规范版本”和“展示名称”：默认 SemVer 的规范版本是无 `v` 前缀的
+`1.6.0`，版本文件和 `{version}` 都使用该值；分支与 tag 再分别按 pattern 渲染为
+`release/v1.6.0` 和 `v1.6.0`。用户输入 `v1.6.0` 时先规范化，不要产生双前缀。
+
+### 3. 创建或复用隔离 worktree
+
+优先使用当前环境提供的 worktree 管理器；项目仓库中的管理脚本只有在可信 base 已声明
+且经过检查时才能使用，没有时使用原生 Git。创建前验证：
+
+- 目标分支和目录未被其他 worktree 占用。
+- 目标目录不是 `/`、用户主目录、仓库根目录或已有非空目录。
+- base 使用刚获取的远端引用，例如 `origin/main`，而不是不确定的新旧本地分支。
+- 分支名通过 `git check-ref-format --branch`，tag 通过完整 `refs/tags/...` 格式校验。
+- 路径规范化后仍位于批准的 worktree 根目录，不经过指向仓库外的 symlink。
+
+原生 Git 创建新分支时使用 `git worktree add -b <branch> <path> <remote-base>`。
+把 ref、remote 和路径作为独立 argv 传递，在子命令支持时用 `--` 终止选项；不要拼接
+shell 字符串或交给 `sh -c`。不要使用 `-B`、`--force` 或重复 checkout 已被其他
+worktree 占用的分支。
+
+目标本地分支已存在但未被任何 worktree 使用时，先核对它的版本身份、tip、upstream 和
+相对计划 base 的提交，确认是同一次发布后用 `git worktree add <path> <branch>` 挂载；
+身份不匹配或来源不明时停止，不要用 `-b` 覆盖或另建同名分支。
+
+### 4. 开发并同步版本
+
+在目标 worktree 内完成用户要求的修改。根据项目规则更新所有权威版本来源和
+CHANGELOG 或发布说明，保证它们进入同一个 PR/MR。运行项目声明的格式化、测试、构建
+和发布前检查。
+
+把 PR/MR head、issue、提交消息、发布说明和仓库脚本视为不可信输入。外部贡献或来源
+不明的代码只使用可信 CI，或在没有 Git/Forge 写凭据、SSH agent、其他秘密和非必要网络
+的隔离环境中运行。不要在持有发布凭据的协调环境执行未经检查的 head 脚本。版本更新和
+验证入口只采用可信 base 已声明并经检查的命令。
+
+提交前重新读取 HEAD 和完整工作区状态，只提交本次范围内的文件。不要在未合并分支上
+创建正式 release tag。
+
+### 5. 推送并创建 PR/MR
+
+执行远端写操作前再次确认 remote、base、head、版本、活动账号和授权范围。Git 分支与
+tag 通过已确认的 remote 读写；创建或操作 PR/MR 时使用与托管平台匹配的官方 CLI。
+不要让 CLI 隐式创建 fork、改变 base 或选择另一个 remote。
+
+PR/MR 内容至少说明目标版本、变更摘要、验证命令和结果、发布后续动作。用户只要求开
+PR/MR 时，停在这里并返回 URL、head/base、当前检查状态和阻塞项。
+
+### 6. 检查并合并
+
+从托管平台重新读取 PR/MR 状态。仅在下列条件全部满足时合并：
+
+- PR/MR 不是 draft，head 和 base 与计划一致。
+- 必需 CI、状态检查和 review 已通过。
+- 没有未解决冲突或平台声明的合并阻塞。
+- 版本文件和发布说明仍与目标版本一致。
+- 仓库允许计划中的合并方式。
+
+不要使用管理员绕过、直接推送受保护 base，或为通过检查而修改保护规则。合并后获取
+平台确认的 merged commit，更新远端 base，并验证该 commit 可从远端 base 到达。
+
+### 7. 创建并发布 tag
+
+在 merged commit 上核对目标版本后，再查询一次远端同名 tag。tag 不存在时创建
+annotated tag；项目要求签名时，必须先确认签名工具和密钥可用，创建 signed tag，并在
+本地验证签名成功后才允许 push。签名不可用或验证失败时停止，不得降级为 unsigned tag。
+显式指定 merged commit，并只推送这个 tag。
+
+同名远端 tag 已存在且指向其他 commit 时立即停止。不要覆盖、删除或移动已经发布的
+tag。推送后读取远端 tag，并将 annotated tag 解引用到 commit，确认它与 merged commit
+完全相同。
+
+仅当用户本次请求明确要求时创建 Forge Release；项目策略只能说明创建方式，不能授予
+外部写权限。必须引用已经存在并验证过的 tag，禁止让平台从默认分支隐式创建 tag。
+发布说明中的每项变化都应能追溯到本次 PR/MR、提交或项目 CHANGELOG。
+
+### 8. 验证、恢复和清理
+
+分别报告以下状态，不要用“发布成功”掩盖其中某一步未完成：
+
+- 版本文件和本地验证。
+- PR/MR URL、合并状态和 merged commit。
+- 远端 tag 及其解引用后的 commit。
+- Forge Release URL 和可见性，若本次要求创建。
+- worktree、本地分支和远端分支是否保留。
+
+清理时只移除干净且已确认不再使用的 linked worktree，不使用强制删除。删除本地或远端
+分支前确认其提交已合并且可从 base 或 tag 到达；本地和远端分支删除都必须有明确授权。
+
+## 硬停止条件
+
+遇到以下任一情况时停止相应写操作并说明恢复路径：
+
+- base、目标版本、版本来源、remote，或请求阶段所需的托管平台无法唯一确定。
+- 项目策略包含未知字段、错误类型、仓库外路径或不安全 ref。
+- 多个权威版本来源不一致。
+- 目标分支、worktree、PR/MR、tag 或 release 已存在但身份不匹配。
+- required checks、review 或冲突状态不满足合并规则。
+- 合并结果的准确 commit 无法从平台确认，或无法从远端 base 到达。
+- 远端 tag 已指向其他 commit。
+- 请求的 PR/MR、合并或 Forge Release 阶段所需的平台 CLI 缺失、未认证或无法读取状态。
+- 项目要求 tag 签名，但签名能力不可用或本地签名验证失败。
+- 操作需要 force push、管理员绕过、移动已发布 tag 或覆盖用户工作。
+- 不可信代码只能在带仓库写凭据、SSH agent、秘密或非必要网络的环境中运行。
+
+不要在命令参数、文件、提交、PR/MR、日志或最终回复中暴露 token、密码、私钥路径或
+认证配置。CLI 不可用时给出人工交接信息，不要擅自改用带 token 的 `curl`。
+
+## 完成标准
+
+只分析时，给出当前状态、建议版本、依据和下一步。开始版本时，给出 worktree 路径、
+分支和基线 commit。创建 PR/MR 时，给出 URL 与检查状态。合并时，给出 merged commit。
+发布 tag 时，证明远端 tag 解引用到该 commit。创建 Forge Release 时，再给出 release URL
+与可见性。任何部分未完成都要标明阻塞阶段和可恢复动作。
@@ -0,0 +1,77 @@
+# 代码托管平台适配
+
+## 区分 Git 与 Forge 能力
+
+fetch、查询 remote refs、推送分支和推送单个 tag 属于 Git transport 能力，可直接通过
+已配置的 Git remote 完成。创建或查看 PR/MR、合并以及创建 Forge Release 才需要平台
+CLI。只发布 tag 时，不要因为缺少 Forge CLI 而停止；仍要验证 remote、认证目标和推送
+授权，并在 push 后读回远端 ref。
+
+## 选择 Forge 适配器
+
+从 push remote URL 识别平台，并使用对应官方 CLI：
+
+| 平台 | CLI | PR/MR 命令域 | Release 命令域 |
+|---|---|---|---|
+| GitHub | `gh` | `gh pr` | `gh release` |
+| GitLab | `glab` | `glab mr` | `glab release` |
+| Gitea / Forgejo | `tea` | `tea pulls` | `tea releases` |
+
+先运行 CLI 的版本、认证状态和只读查看命令。记录匹配 remote host 的活动账号；存在多
+个账号或 profile 时，必须唯一确定本次使用的身份。CLI 版本之间的 flags 可能不同，
+每次执行写操作前读取对应子命令的 `--help`，不要凭记忆拼接参数。
+
+当请求确实涉及 PR/MR、合并或 Forge Release，且 remote host 无法识别、CLI 缺失、认证
+失败或 CLI 指向另一个实例时，停止对应平台阶段并报告：
+
+- host、owner/repository、remote 名称。
+- base、head 和当前 commit。
+- 已完成的本地验证。
+- 尚需人工执行的创建 PR/MR、合并或 release 步骤。
+
+不要自动安装 CLI，也不要把 token 放进命令行后改用 `curl`。用户明确提供受支持的其他
+集成时，可以使用该集成，但仍遵守同一套授权和验证闸门。
+
+## 创建 PR/MR
+
+使用显式的 repository、base、head、title 和 body，避免交互式默认值改变目标。把动态
+值作为独立 argv 或结构化输入传递，不拼接 shell 命令。创建前：
+
+1. 确认当前分支已经推送到计划中的 remote。
+2. 查询同一 head/base 是否已有 open PR/MR，有则复用并更新状态，不重复创建。
+3. 确认 head commit 与本地已验证 commit 相同。
+4. 确认 CLI 不会隐式创建 fork 或推送到另一个 remote。
+5. 再次读取活动账号，向用户展示 host、repository、账号和授权的最远阶段。
+
+PR/MR body 包含目标版本、变更摘要、验证命令与结果、发布后续。创建后读取平台返回的
+URL、编号、head/base 和状态，不以命令退出码代替远端读回。
+
+## 检查和合并
+
+用结构化输出读取 draft、head commit、base、review、required checks、冲突或
+mergeability、允许的合并方式。平台字段缺失时，使用平台提供的只读详情命令补足；不能
+证明闸门通过时保持未合并。
+
+GitHub 使用 `gh pr view`、`gh pr checks` 和 `gh pr merge`；GitLab 使用
+`glab mr view`、pipeline 状态和 `glab mr merge`；Gitea 或 Forgejo 使用
+`tea pulls` 的查看、检查和合并能力。实际参数以当前 CLI 的 `--help` 为准。
+
+若用户要求检查通过后自动合并，优先使用仓库已经启用的 auto-merge 或 merge queue。
+不要用管理员选项绕过 review、CI、conversation resolution 或 protected branch。
+
+合并后重新读取 PR/MR，取得平台确认的 merged commit。随后 fetch 远端 base，并验证该
+commit 已进入远端 base。只看到本地 merge commit 或分支关闭不足以证明平台已合并。
+
+## 创建 Forge Release
+
+把 Git tag 和 Forge Release 当成两个独立状态。先创建、推送并验证 tag，再创建 release。
+
+- GitHub 创建 release 时使用能够拒绝缺失 tag 的选项，例如当前 CLI 支持的
+  `--verify-tag`。
+- GitLab、Gitea 或 Forgejo 创建 release 前，先用只读命令证明 tag 已存在并指向计划的
+  commit；不要使用会顺便创建 tag 的默认行为。
+- 预发布版本按项目规则标记 prerelease，不要自动把它标为 latest 或 stable。
+- 发布后重新读取 release URL、tag 和可见性。
+
+Forge Release 创建失败但 tag 已成功推送时，保留 tag 并从 release 阶段恢复，不要重新
+合并或创建另一个 tag。
@@ -0,0 +1,73 @@
+# 项目发布策略
+
+## 策略优先级
+
+按以下顺序确定规则，并在来源冲突时停止说明，不要静默覆盖：
+
+1. 用户本次请求中明确给出的目标和授权范围。
+2. 项目 `AGENTS.md`、`CLAUDE.md`、发布文档和可选的 `.release-policy.yaml`。
+3. 构建脚本、包清单、CI 工作流和历史发布使用的实际入口。
+4. 代码托管平台当前的默认分支、保护规则、检查和允许的合并方式。
+5. 本 Skill 的默认值。
+
+用户请求若与项目硬规则或平台保护冲突，展示冲突并请求处理方式。不要借用户的一句
+“直接发布”绕过仓库声明的检查或保护。
+
+开始流程时记录 base commit，并读取该提交对应的项目策略。本次发布分支对策略文件的
+修改不应改变正在执行的流程；新策略从下一次发布开始生效。
+
+项目策略不能授予外部写权限。即使配置声明创建 Forge Release 或删除远端分支，也必须
+由用户本次请求明确授权相应动作。
+
+## 可选配置
+
+项目反复出现同一种歧义时，用户可以要求创建 `.release-policy.yaml`。从
+`templates/release-policy.template.yaml` 复制后，只保留项目真正需要固定的字段。
+
+配置只保存可提交的项目策略：
+
+- `schema`：配置结构版本，当前为 `1`。
+- `base_branch`：发布 PR/MR 的目标分支。
+- `branch_pattern`：版本分支格式，支持无展示前缀的规范 `{version}`。
+- `version.scheme`：`semver` 或项目已经使用的其他方案。
+- `version.sources`：构建和运行实际读取的权威版本文件。
+- `tag_pattern`：release tag 格式，支持无展示前缀的规范 `{version}`。
+- `merge_method`：`squash`、`merge` 或 `rebase`。
+- `forge_release`：项目是否建议在 tag 后创建 Forge Release；它不授予创建权限。
+- `tag_signing`：`off`、`optional` 或 `required`。
+- `delete_remote_branch`：发布完成后是否建议清理远端源分支；它只是计划偏好，不是删除
+  权限或自动执行指令，仍需用户在本次请求中明确授权。
+
+不要在配置中保存 token、账号、私钥路径、个人工作目录或一次性发布状态。不要加入任意
+shell 命令字段；本地验证继续从项目文档、CI 和构建入口发现。
+
+读取配置后校验字段集合、类型和枚举值，遇到未知字段时停止。`branch_pattern` 和
+`tag_pattern` 展开后分别用 Git branch/tag ref 规则校验；不要把配置值拼进 shell 字符串。
+`version.sources` 中每一项必须是仓库相对路径，拒绝绝对路径和 `..`。规范化并解析
+symlink 后，目标必须仍在当前 worktree 内；权威来源通常还应由 Git 跟踪。
+
+先按版本方案把用户输入规范化。默认 SemVer 接受 `1.6.0` 或作为用户输入的 `v1.6.0`，
+但内部 `{version}` 固定为 `1.6.0`；版本文件写入规范值，branch/tag pattern 分别负责添加
+展示前缀。自定义版本方案按项目文档定义规范值，不能从 pattern 猜测后重复添加前缀。
+
+## 无配置时的发现顺序
+
+1. 从 remote HEAD 和平台信息确定默认 base，不能确定时询问。
+2. 从项目文档、CI 和构建入口找版本文件及更新方式。
+3. 从已有分支和已合并 PR/MR 识别命名与合并方式。
+4. 从稳定 tag 识别前缀和版本方案，只把 tag 当作交叉验证。
+5. 无项目约定时使用 `release/v<version>`、SemVer、`v<version>` annotated tag 和
+   squash merge；默认不创建 Forge Release，不删除远端分支。
+
+## 每次执行的计划快照
+
+在第一次写操作前列出以下事实：
+
+- base 分支和远端 commit。
+- 当前版本、目标版本、版本来源和升级依据。
+- worktree 路径与分支名。
+- PR/MR 托管平台和合并方式。
+- tag 与 Forge Release 计划。
+- 用户授权的最远阶段和清理范围。
+
+任何事实在执行中改变时刷新计划。改变会影响已授权的远端写目标时，再次获得确认。
@@ -0,0 +1,52 @@
+# 中断恢复与安全清理
+
+## 恢复原则
+
+每次重入都从 Git 和代码托管平台读取状态，不依赖上一轮聊天结论。先记录准确的
+base、head、PR/MR、merged commit、tag 和 release，再执行唯一缺失的下一步。
+
+网络或平台调用返回超时、未知状态或非结构化错误时，先用只读命令刷新远端状态。不要把
+重试当成默认动作；创建 PR/MR、合并、推 tag 和创建 release 都可能已经成功。
+
+## 常见部分状态
+
+| 当前状态 | 继续方式 | 禁止事项 |
+|---|---|---|
+| worktree 已创建，无改动 | 继续开发，或经授权移除干净 worktree | 不使用强制删除 |
+| 本地发布分支已存在，没有 worktree | 核对版本身份、tip、upstream 和 base 后挂载现有分支 | 不用 `-b` 覆盖分支 |
+| 分支已推送，没有 PR/MR | 确认 head/base 后创建一次 PR/MR | 不重复推送新分支 |
+| PR/MR 已存在，未合并 | 复用 URL，刷新 checks、review 和冲突状态 | 不创建第二个 PR/MR |
+| PR/MR 已合并，没有 tag | 获取 merged commit，在该 commit 上继续发布 | 不重新合并 |
+| tag 已推送，没有 release | 验证 tag 后创建 Forge Release | 不创建替代 tag |
+| release 已创建，验证未完成 | 读回 release、tag 和可见性 | 不直接声称发布完成 |
+| 同名资源身份不匹配 | 停止并报告差异 | 不覆盖、关闭或删除未知资源 |
+
+## 并发冲突
+
+两个 Agent 或维护者可能同时准备相同版本。创建分支、PR/MR、tag 或 release 前都重新查询
+目标是否存在。推 tag 前立即检查远端引用；push 因同名引用失败时保持失败，不要 force。
+
+base 在开发期间前进时，让 PR/MR 和仓库规则决定是否需要更新分支。已经推送的发布分支
+不在本 Skill 中重写历史；需要更新时优先创建普通提交，或交给平台的 update branch、
+merge queue 和 auto-merge。任何 force push 都是硬停止条件。
+
+## 回滚边界
+
+- 未推送的本地版本提交可以在用户授权下修改或放弃，但不要覆盖其他工作。
+- 已推送但未合并的 PR/MR 可以关闭，分支默认保留。
+- 已合并变更通过新的 revert PR/MR 回滚，不重写 base 历史。
+- 已发布 tag 默认不可变。tag 错误时停止，由维护者决定撤销发布或发布新版本。
+- Forge Release 失败不回滚已经正确推送的 tag；从 release 阶段恢复。
+
+## 清理规则
+
+清理始终放在发布验证之后：
+
+1. 确认 worktree 没有修改、暂存或未跟踪文件。
+2. 确认分支提交已从远端 base 或已验证 tag 到达。
+3. 仅移除目标 linked worktree，不操作主 worktree，不使用 `--force`。
+4. 删除本地分支前再次确认已合并。
+5. 删除本地或远端分支都必须有用户本次请求的明确授权；项目策略不能代替授权。
+6. 使用 `git worktree prune --dry-run` 查看陈旧记录；不要把 prune 当作普通清理步骤。
+
+任何清理条件不满足时保留现场，并报告路径、分支、未提交状态和后续人工动作。
@@ -0,0 +1,79 @@
+# 版本号与 tag
+
+## 确定权威版本来源
+
+按项目实际构建链路寻找版本来源，不要遍历到一个看起来像版本号的字符串就修改。优先级：
+
+1. 项目发布文档或 `.release-policy.yaml` 明确声明的文件。
+2. 构建、打包或运行入口直接读取的清单，例如 `VERSION`、`package.json`、
+   `pyproject.toml`、`Cargo.toml` 或语言工具链的版本配置。
+3. 由权威文件生成的镜像文件、锁文件或发布元数据。
+4. 最近稳定 tag，只用于验证当前版本和发布历史。
+
+记录每个权威文件的当前值和更新方式。多个权威来源不一致时停止，不要选择修改时间最新
+的文件，也不要只改其中一个。
+
+配置声明的版本文件必须使用仓库相对路径。拒绝绝对路径、`..` 和解析后逃出目标
+worktree 的 symlink；修改前确认规范化后的准确路径。不要用 glob 或模糊搜索结果执行
+批量替换。
+
+## 选择目标版本
+
+项目已有 CalVer、单调构建号、独立包版本或自定义方案时继续使用，不要迁移到 SemVer。
+项目没有规则且只有一个协调版本时使用 SemVer：
+
+- 不兼容的公开 API 或行为变化增加 major。
+- 向后兼容的新功能增加 minor。
+- 向后兼容的修复增加 patch。
+
+根据实际兼容性判断，不要只凭 commit 前缀自动升级。项目明确采用 Conventional Commits
+或已有版本工具时，可以把它们的结果作为项目规则。破坏性影响无法确定时给出建议并请
+用户确定准确版本。
+
+预发布版本沿用项目格式；没有格式时使用 `-alpha.N`、`-beta.N` 或 `-rc.N`。正式 tag
+默认不加入 build metadata。不要从带 build metadata 的 tag 推断兼容性顺序。
+
+独立多包版本、多个维护分支和 release train 不属于默认单版本流程。无法确定一个目标
+版本时停止并说明需要增加包或发布线维度。
+
+## 规范化与渲染
+
+内部始终分别记录规范版本、分支名和 tag 名。默认 SemVer 的规范版本不含 `v`，例如
+用户输入 `v1.6.0` 时规范化为 `1.6.0`；版本文件写入 `1.6.0`，再将它代入
+`release/v{version}` 和 `v{version}`。不要把完整 tag 名直接代入 `{version}`。
+
+项目采用自定义前缀或非 SemVer 时，以项目版本来源定义规范值，以 branch/tag pattern
+定义展示形式。规范化结果无法唯一确定时停止并让用户确认。
+
+## 同步版本
+
+在发布分支中一次性更新所有权威版本来源、生成文件和项目要求的 CHANGELOG。运行项目
+自己的版本更新工具时，先检查它会修改哪些文件，避免隐式发布、提交或上传。
+
+提交前确认：
+
+- 所有权威来源都是目标版本。
+- 生成文件与来源一致。
+- CHANGELOG 或发布说明描述的是本次实际变更。
+- 项目构建和测试读取到了新版本。
+
+## 验证 merged commit
+
+合并后以代码托管平台返回的 merged commit 为准。获取远端 base 后，确认该 commit 可从
+远端 base 到达，并直接读取该 commit 中的版本文件。不要用仍停留在 feature worktree
+中的文件证明已合并版本。
+
+正式 tag 必须满足：
+
+- tag 名按项目格式由目标版本唯一生成。
+- 远端没有同名 tag，或同名 tag 已经准确指向本次 commit。
+- annotated tag 显式指向 merged commit。
+- 项目要求签名时，push 前已成功创建 signed tag，并在本地验证签名通过；不可用或失败
+  时停止，不得改用 unsigned tag。
+- 推送后从远端重新读取，并将 annotated tag 解引用到 commit。
+
+展开 tag pattern 后用 `git check-ref-format refs/tags/<tag>` 校验。把 tag 和 commit 作为
+独立 argv 传递，不拼接 shell 字符串。
+
+tag 已在远端指向其他 commit 时停止。不要 force push、删除或移动已发布 tag；由维护者
+决定撤销发布或创建新的修订版本。
@@ -0,0 +1,17 @@
+# 复制为项目根目录的 .release-policy.yaml，并按项目实际约定修改。
+# 此文件描述发布策略，不授予任何远端写操作权限。
+schema: 1
+base_branch: main
+# {version} 是规范版本，例如 1.6.0；前缀由 pattern 添加。
+branch_pattern: release/v{version}
+version:
+  scheme: semver
+  sources:
+    - VERSION
+tag_pattern: v{version}
+merge_method: squash
+# 只表示项目偏好；创建 Forge Release 仍需用户本次请求明确授权。
+forge_release: false
+tag_signing: optional
+# 只表示清理偏好；删除仍需用户在本次请求中明确授权。
+delete_remote_branch: false
@@ -0,0 +1,65 @@
+---
+name: publish-docker-image
+description: >-
+  构建当前项目的 Docker 镜像，并将其上传到用户指定的镜像仓库。仅当用户显式指定
+  $publish-docker-image、明确说“使用 publish-docker-image skill”，或由显式调用的 `$ack`
+  根据用户明确的 Docker/OCI 镜像发布请求路由时使用；
+  不要因普通编码、编辑 Dockerfile、本地构建、测试或一般 Docker 问题而自动触发。
+---
+
+# 发布 Docker 镜像
+
+安全、可复现地构建当前提交对应的 Docker 镜像，并按用户指定的目标上传。
+
+## 执行流程
+
+1. 读取项目的 `AGENTS.md`、Dockerfile、构建脚本和相关发布文档。
+2. 收集目标 registry、repository、tag、platform、构建上下文和 Dockerfile。优先使用用户已明确提供的值；缺少会改变发布结果的值时，停止并询问。
+3. 检查 Git 工作区与当前提交。若存在未提交修改，明确说明镜像将包含哪些修改。
+4. 按 [registry.md](references/registry.md) 检查仓库规则和认证状态。
+5. 在执行外部写操作前，向用户展示完整镜像引用、platform、Dockerfile、构建上下文和源 commit。只有用户已明确要求上传到该目标时才继续。
+6. 使用 [publish.sh](scripts/publish.sh) 构建并上传。不要自行拼接包含凭据的命令。
+7. 检查命令退出状态，并尽可能获取远端 digest。
+8. 汇报完整镜像引用、digest、platform、源 commit，以及是否包含未提交修改。
+
+## 命令
+
+默认构建并上传：
+
+```bash
+scripts/publish.sh \
+  --registry REGISTRY \
+  --repository NAMESPACE/IMAGE \
+  --tag TAG \
+  --platform PLATFORM
+```
+
+先验证而不构建或上传：
+
+```bash
+scripts/publish.sh \
+  --registry REGISTRY \
+  --repository NAMESPACE/IMAGE \
+  --tag TAG \
+  --platform PLATFORM \
+  --dry-run
+```
+
+仅当用户明确要求本地构建时使用 `--load`。多平台镜像不能使用 `--load`。
+
+## 安全边界
+
+- 不把密码、访问令牌或 Docker 配置写入 skill、项目文件、命令参数或输出。
+- 不主动执行 `docker login`；认证缺失时让用户通过交互式登录或其凭据管理器完成。
+- 不覆盖已存在的 release tag，除非用户明确授权。无法可靠检查远端 tag 时说明这一限制。
+- 不把 `latest` 作为隐含默认 tag。
+- 不上传用户未指定的附加 tag。
+- 不擅自修改 Dockerfile、发布配置、仓库权限或镜像保留策略。
+- 若仓库、tag、platform 或目标环境存在歧义，在上传前询问用户。
+
+## 验证
+
+- 确认 `docker buildx build` 成功且启用了 `--push`。
+- 优先用 `docker buildx imagetools inspect FULL_IMAGE_REF` 验证远端引用及平台。
+- 记录远端 digest；若仓库不允许检查，明确报告只验证了 push 命令成功。
+- 将发布所用的 Git commit 与工作区状态一并报告。
@@ -0,0 +1,39 @@
+# 镜像仓库规则
+
+执行发布前，从用户输入和当前项目文档中确定以下信息：
+
+| 字段 | 要求 |
+| --- | --- |
+| Registry | 必须显式确定，例如 `registry.example.com` |
+| Repository | 必须包含项目约定的 namespace，例如 `team/service` |
+| Tag | 必须显式确定；优先使用版本号或 Git SHA |
+| Platform | 必须显式确定，例如 `linux/amd64` 或 `linux/amd64,linux/arm64` |
+| Dockerfile | 默认 `Dockerfile`，不存在或项目另有约定时明确指定 |
+| Context | 默认当前项目根目录 |
+
+## 信息来源优先级
+
+1. 用户本次请求中明确给出的值。
+2. 当前项目的 `AGENTS.md` 和发布文档。
+3. `Makefile`、CI 配置、Compose 文件或现有构建脚本中一致且无歧义的配置。
+4. 询问用户。
+
+不要从其他项目、shell history 或无关的本地配置中猜测发布目标。
+
+## 认证
+
+使用 Docker 当前配置的 credential helper 或已有登录状态。可用不泄露凭据的只读操作检查目标是否可访问。认证缺失或过期时，停止并让用户自行完成登录。
+
+不要读取、打印或复制以下内容：
+
+- registry 密码或访问令牌
+- `~/.docker/config.json` 中的认证字段
+- CI secret 的值
+- 包含凭据的环境变量值
+
+## Tag 策略
+
+- release tag（如 `v1.2.3`）默认视为不可变。
+- Git SHA tag 应对应当前源 commit。
+- `latest`、`stable` 等浮动 tag 只有在用户明确要求时才发布。
+- 用户未给 tag 且项目没有唯一明确规则时，必须询问，不要自行选择。
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  sed -n '2,22p' "$0"
+}
+
+# Build and publish a Docker image with buildx.
+#
+# Usage:
+#   publish.sh --registry HOST --repository PATH --tag TAG --platform PLATFORMS [options]
+#
+# Options:
+#   --registry HOST       Registry host, without a URL scheme
+#   --repository PATH     Repository path, such as team/service
+#   --tag TAG             Image tag
+#   --platform LIST       Comma-separated platforms
+#   --file PATH           Dockerfile path (default: Dockerfile)
+#   --context PATH        Build context (default: .)
+#   --builder NAME        Existing buildx builder
+#   --load                Load a single-platform image instead of pushing
+#   --dry-run             Print the resolved build without executing it
+#   --help                Show this help
+
+registry=
+repository=
+tag=
+platform=
+dockerfile=Dockerfile
+build_context=.
+builder=
+mode=push
+dry_run=false
+
+while (($#)); do
+  case "$1" in
+    --registry) registry=${2-}; shift 2 ;;
+    --repository) repository=${2-}; shift 2 ;;
+    --tag) tag=${2-}; shift 2 ;;
+    --platform) platform=${2-}; shift 2 ;;
+    --file) dockerfile=${2-}; shift 2 ;;
+    --context) build_context=${2-}; shift 2 ;;
+    --builder) builder=${2-}; shift 2 ;;
+    --load) mode=load; shift ;;
+    --dry-run) dry_run=true; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) printf 'Unknown argument: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+for required_name in registry repository tag platform; do
+  if [[ -z ${!required_name} ]]; then
+    printf 'Missing required option: --%s\n' "$required_name" >&2
+    exit 2
+  fi
+done
+
+if [[ $registry == *://* || $registry == */* ]]; then
+  printf '%s\n' 'Registry must be a host without a URL scheme or path.' >&2
+  exit 2
+fi
+if [[ $repository == /* || $repository == */ || $repository != */* ]]; then
+  printf '%s\n' 'Repository must look like namespace/image.' >&2
+  exit 2
+fi
+if [[ $tag == *:* || $tag == */* ]]; then
+  printf '%s\n' 'Tag must not contain ":" or "/".' >&2
+  exit 2
+fi
+if [[ $mode == load && $platform == *,* ]]; then
+  printf '%s\n' '--load supports only one platform.' >&2
+  exit 2
+fi
+if [[ ! -f $dockerfile ]]; then
+  printf 'Dockerfile not found: %s\n' "$dockerfile" >&2
+  exit 2
+fi
+if [[ ! -d $build_context ]]; then
+  printf 'Build context not found: %s\n' "$build_context" >&2
+  exit 2
+fi
+if [[ $dry_run == false ]] && ! command -v docker >/dev/null 2>&1; then
+  printf '%s\n' 'docker is not installed or not available in PATH.' >&2
+  exit 127
+fi
+
+image_ref="${registry}/${repository}:${tag}"
+build_cmd=(docker buildx build --file "$dockerfile" --platform "$platform" --tag "$image_ref")
+if [[ -n $builder ]]; then
+  build_cmd+=(--builder "$builder")
+fi
+if [[ $mode == push ]]; then
+  build_cmd+=(--push)
+else
+  build_cmd+=(--load)
+fi
+build_cmd+=("$build_context")
+
+printf 'Image: %s\n' "$image_ref"
+printf 'Platform: %s\n' "$platform"
+printf 'Dockerfile: %s\n' "$dockerfile"
+printf 'Context: %s\n' "$build_context"
+printf 'Mode: %s\n' "$mode"
+
+if [[ $dry_run == true ]]; then
+  printf 'Command:'
+  printf ' %q' "${build_cmd[@]}"
+  printf '\n'
+  exit 0
+fi
+
+"${build_cmd[@]}"
+
+if [[ $mode == push ]]; then
+  docker buildx imagetools inspect "$image_ref"
+fi
@@ -0,0 +1,67 @@
+# skiff
+
+`skiff` 用于创建、维护、安装和发布团队自研的 Agent Skill。Skill 的唯一来源位于
+`~/.skills/skills/<name>/`，安装到各 Agent 时使用软链接。
+
+## 什么时候使用
+
+- 想把项目里的重复工作沉淀成一个 skill。
+- 想完善、校验、转正或发布已有 skill。
+- 想把自研 skill 安装到当前项目或全局 Agent。
+- 想检查并修复 skill 软链接。
+
+## 创建一个 skill
+
+```bash
+skiff create my-skill \
+  --idea "描述这个 skill 要解决的重复问题" \
+  --from-project .
+```
+
+命令会在 `~/.skills/.drafts/my-skill/` 创建：
+
+- `SKILL.md`：给 Agent 阅读的工作流与约束。
+- `README.md`：给人类阅读的用途、准备事项、示例和完成标准。
+- `brief.yaml`：草稿来源信息，转正时自动移除。
+
+完善 `SKILL.md` 和 `README.md` 后运行：
+
+```bash
+skiff check my-skill
+skiff finalize my-skill
+```
+
+## 提交和发布
+
+只提交：
+
+```bash
+skiff publish skills/my-skill -m "add my-skill"
+```
+
+提交并推送：
+
+```bash
+skiff publish skills/my-skill -m "add my-skill" --push
+```
+
+## 安装
+
+安装到当前项目的 Codex：
+
+```bash
+skiff add my-skill -a codex -y
+```
+
+安装到全局 Codex：
+
+```bash
+skiff add my-skill -a codex -g -y
+```
+
+## 如何判断完成
+
+- `skiff check <name>` 输出校验通过。
+- 正式 skill 同时包含 `SKILL.md` 和 `README.md`。
+- `skiff status` 或 `skiff doctor` 显示目标软链接正常。
+
@@ -0,0 +1,185 @@
+---
+name: skiff
+description: >-
+  创建和维护 ~/.skills 自研 skill：把项目开发中产生的想法提炼为草稿，完善并校验后发布，
+  用 skiff add/remove 在项目及全局挂卸 skill，或用 skiff init 初始化 skill 项目状态。
+  触发词：skiff、自研 skill、创建 skill、想做一个 skill、publish skill、安装自研 skill、
+  更新 skill 到项目、初始化 skill。
+---
+
+# skiff 自研 Skill 工作流
+
+SSOT 固定在 `~/.skills/skills/<name>/`。内容通过 **symlink** 分发到各 agent，改 SSOT 即全项目生效。
+
+---
+
+## 在项目中使用 skill
+
+先浏览可用的 builtin skill，再安装到当前项目：
+
+```bash
+skiff add --list
+skiff add <name> -a cursor -a claude -a codex -y
+```
+
+`skiff add <name>` 默认安装到当前项目；只有用户明确需要所有项目使用时才加 `-g`。安装结果是指向 `~/.skills/skills/<name>/` 的软链，不要在 Agent 目录创建副本。
+
+## 创建新的 skill
+
+### 从项目想法创建 skill
+
+当用户在项目开发中提出“想创建一个 skill”时：
+
+1. 用一句话确认它要解决的重复问题，并建议符合小写连字符规范的名称；信息足够时不要为了形式追问。
+2. 读取当前项目中与想法直接相关的代码和规范，区分可复用工作流与项目私有事实。
+3. 创建草稿：
+
+```bash
+skiff create <name> --idea "<用户原始想法>" --from-project .
+```
+
+4. 编辑 `~/.skills/.drafts/<name>/SKILL.md`，完善触发条件、不适用场景、步骤、边界与验证方法。
+5. 编辑同目录的 `README.md`，用面向人类的语言说明用途、准备事项、可直接复制的请求示例、Agent 会做什么以及如何判断完成。README 不应复述 Agent 内部指令。
+6. 仅在确有必要时增加 `references/`、`scripts/` 或 `assets/`。不要把项目专属路径、私有业务规则、一次性命令或密钥复制到通用 skill。
+7. 运行校验并修复所有问题：
+
+```bash
+skiff check <name>
+```
+
+8. 向用户展示名称、description、README 的人类使用方式、核心步骤和验证方式。获得确认后再转正：
+
+```bash
+skiff finalize <name>
+```
+
+转正不会自动 commit、push 或安装。用户明确要求后再执行 `skiff publish` 或 `skiff add`。
+
+## 问题或优化回流
+
+在项目里使用 skills 遇到问题，或者发现可复用的优化时：
+
+1. 先记录最小证据：触发用户表达、使用的 skill 名称、实际结果、期望结果，以及能复现问题的必要项目上下文。
+2. 判断归属：
+   - 通用工作流、触发条件或验证缺陷：回流 builtin skill。
+   - 仅当前项目成立的命令、路径、业务规则：留在项目文档或项目配置，不写回通用 skill。
+   - CLI 安装、软链或校验行为异常：修改 `~/.skills/skiff/` 中的 CLI 和测试。
+   - 第三方 skill：不要复制成 builtin skill 或直接改安装目录；整理证据反馈上游，除非用户明确决定维护 fork。
+3. 确认真实来源。Agent 目录通常是软链，builtin skill 的 SSOT 固定为：
+
+```text
+~/.skills/skills/<name>/
+```
+
+4. 修改 SSOT。行为修复应先补能复现问题的测试或示例，再改 `SKILL.md`、引用文件或脚本。
+5. 校验并在原项目重跑最初失败的场景：
+
+```bash
+skiff check <name>
+```
+
+6. 汇报修改内容、验证结果和影响范围。只有用户明确要求提交或推送时才运行：
+
+```bash
+skiff publish skills/<name> -m "update <name>" --push
+```
+
+软链正确时无需重新安装；SSOT 保存后项目立即读取新内容。
+
+## 安装与维护
+
+安装本项目的 `skiff` skill 到所有 Agent：
+
+```bash
+skiff bootstrap
+```
+
+安装其他 skill：
+
+```bash
+# 当前项目
+cd ~/code/my-app
+skiff add discussion-notes -a cursor -y
+
+# 全局（所有项目）
+skiff add discussion-notes -a cursor -g -y
+
+# 多个 agent
+skiff add discussion-notes -a cursor -a codex -g -y
+```
+
+catalog source既可以指向单个 skill，也可以指向包含多个 skill 目录的
+collection。安装 collection 全部内容或其中一个：
+
+```bash
+skiff add waza -a codex -g -y
+skiff add waza/think -a codex -g -y
+```
+
+`skiff select` 会把 collection 显示为两级菜单：选择 `waza` 仓库会选中其
+全部子 skill，也可以只选择 `waza/think`、`waza/ui` 中的若干项。
+普通 `skiff select` 只向项目安装，并只读显示每个 Agent 的全局安装状态；
+`skiff select -g` 只向全局安装。取消已勾选项不会卸载，卸载继续使用
+`skiff remove`。
+
+卸载：
+
+```bash
+skiff remove discussion-notes -a cursor -y          # 当前项目
+skiff remove discussion-notes -g -a cursor -y     # 全局
+skiff rm discussion-notes -g -y                     # rm 别名
+```
+
+浏览可用自研 skill：
+
+```bash
+skiff add --list
+```
+
+使用 Skill 自带模板初始化项目状态：
+
+```bash
+skiff init ack
+skiff init ack --project ~/app
+```
+
+`skiff` 只负责可靠地生成项目状态文件，不复制或链接 Skill。需要分析项目并完善
+ACK 配置、检查接入状态或
+运行三角色闭环时，显式调用全局 `/ack` skill。
+
+---
+
+## 与 Vercel `npx skills` 的分工
+
+| 场景 | 工具 |
+|------|------|
+| 自研 skill（~/.skills） | **skiff** |
+| 社区 skill（GitHub 任意仓库） | `npx skills add` |
+
+---
+
+## 命令对照
+
+| skiff | 说明 |
+|-------|------|
+| `bootstrap` | 将本项目的 `skiff` skill 全局安装到所有 Agent |
+| `update` | 在 `~/.skills` 执行 `git pull`，更新 skiff 自身 |
+| `add <name> [-g] [-a AGENT...] [-y]` | 安装 |
+| `remove <name> [-g] [-a AGENT...] [-y]` | 卸载（`rm` / `r` 别名） |
+| `add --list` | 列出可用自研 skill |
+| `publish [paths] -m MSG [--push]` | git add / commit / push |
+| `list` | 列出 ~/.skills 目录结构 |
+| `status` | 查看软链安装状态 |
+| `create <name> --idea TEXT [--from-project PATH]` | 创建自研 skill 草稿 |
+| `check <name>` | 校验草稿或正式 skill |
+| `finalize <name>` | 校验草稿并转为正式 skill |
+| `init <name> [--project DIR]` | 使用 skill 模板初始化项目状态 |
+
+---
+
+## 注意
+
+- 不要在 `project/.agents/skills/` 里直接改文件；应改 `~/.skills/skills/` 再 `publish`
+- 未完成的内容保留在 `~/.skills/.drafts/`，不要直接放进正式 `skills/`
+- symlink 正确时，**不需要 reinstall**；保存 SSOT 后各项目自动读到新内容
+- 社区 skill 用 `npx skills add`，不要用 skiff `catalog add` 除非团队要 pin 版本
@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import copy
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS_DIR = REPO_ROOT / "skills" / "ack" / "scripts"
+VALIDATOR = SCRIPTS_DIR / "validate_delivery.py"
+EXAMPLE = REPO_ROOT / "skills" / "ack" / "examples" / "delivery.example.yaml"
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+import validate_delivery  # noqa: E402
+
+
+def valid_contract() -> dict:
+    entrypoints = {
+        name: {
+            "kind": "make",
+            "target": name,
+            "args": [],
+            "requiredSecrets": [],
+            "workingDirectory": ".",
+            "timeoutSeconds": 300,
+        }
+        for name in ("verify", "build", "upload", "deploy", "health", "rollback")
+    }
+    return {
+        "version": 1,
+        "updatedAt": "2026-08-01T10:00:00+08:00",
+        "project": {"name": "demo"},
+        "enabled": True,
+        "defaultProfile": "review",
+        "entrypoints": entrypoints,
+        "artifacts": {
+            "service-deb": {
+                "type": "deb",
+                "build": "build",
+                "outputs": ["dist/*.deb"],
+            }
+        },
+        "destinations": {
+            "preview-apt": {
+                "type": "apt-repository",
+                "channel": "preview",
+                "endpoint": "https://packages.example.com",
+                "repository": "testing",
+                "upload": "upload",
+            }
+        },
+        "environments": {
+            "test-server": {
+                "type": "ssh-host",
+                "classification": "development",
+                "target": "test-server",
+                "deploy": "deploy",
+                "healthCheck": "health",
+                "rollback": "rollback",
+                "mutex": "test-server-deploy",
+            }
+        },
+        "profiles": {
+            "review": {
+                "stopAt": "review_ready",
+                "steps": [
+                    {"id": "verify", "action": "verify", "entrypoint": "verify"},
+                    {
+                        "id": "open-pr",
+                        "action": "pull-request",
+                        "draft": True,
+                        "remote": "origin",
+                        "baseBranch": "main",
+                    },
+                    {"id": "build", "action": "build", "artifact": "service-deb"},
+                    {
+                        "id": "publish",
+                        "action": "publish",
+                        "artifact": "service-deb",
+                        "destination": "preview-apt",
+                    },
+                    {
+                        "id": "deploy",
+                        "action": "deploy",
+                        "artifact": "service-deb",
+                        "environment": "test-server",
+                    },
+                    {
+                        "id": "health",
+                        "action": "health-check",
+                        "environment": "test-server",
+                    },
+                    {"id": "ready", "action": "mark-ready"},
+                ],
+            }
+        },
+    }
+
+
+class AckDeliveryValidationTests(unittest.TestCase):
+    def test_example_is_valid_with_and_without_site_packages(self) -> None:
+        for no_site_packages in (False, True):
+            command = [sys.executable]
+            if no_site_packages:
+                command.append("-S")
+            result = subprocess.run(
+                [*command, str(VALIDATOR), str(EXAMPLE)],
+                cwd=REPO_ROOT,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+            with self.subTest(no_site_packages=no_site_packages):
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertIn("交付契约校验通过", result.stdout)
+
+    def test_default_profile_rejects_stable_and_production_targets(self) -> None:
+        contract = valid_contract()
+        contract["destinations"]["preview-apt"]["channel"] = "stable"
+        contract["environments"]["test-server"]["classification"] = "production"
+
+        errors = validate_delivery.validate_builtin(contract)
+
+        self.assertTrue(any("stable 发布前必须有 release approval" in item for item in errors))
+        self.assertTrue(any("production 部署前必须有 production approval" in item for item in errors))
+        self.assertTrue(any("defaultProfile 不能发布 stable" in item for item in errors))
+        self.assertTrue(any("defaultProfile 不能部署 production" in item for item in errors))
+
+    def test_nondefault_release_profile_supports_stable_and_production_with_gates(self) -> None:
+        contract = valid_contract()
+        contract["destinations"]["stable-apt"] = {
+            "type": "apt-repository",
+            "channel": "stable",
+            "endpoint": "https://packages.example.com",
+            "repository": "stable",
+            "upload": "upload",
+        }
+        contract["environments"]["prod-server"] = {
+            "type": "ssh-host",
+            "classification": "production",
+            "target": "prod-server",
+            "deploy": "deploy",
+            "healthCheck": "health",
+            "rollback": "rollback",
+            "mutex": "prod-server-deploy",
+        }
+        contract["profiles"]["release"] = {
+            "stopAt": "released",
+            "steps": [
+                {"id": "verify-release", "action": "verify", "entrypoint": "verify"},
+                {
+                    "id": "open-release-pr",
+                    "action": "pull-request",
+                    "draft": True,
+                    "remote": "origin",
+                    "baseBranch": "main",
+                },
+                {"id": "build-release", "action": "build", "artifact": "service-deb"},
+                {"id": "approve-release", "action": "approval", "gate": "release"},
+                {
+                    "id": "publish-release",
+                    "action": "publish",
+                    "artifact": "service-deb",
+                    "destination": "stable-apt",
+                },
+                {"id": "approve-production", "action": "approval", "gate": "production"},
+                {
+                    "id": "deploy-production",
+                    "action": "deploy",
+                    "artifact": "service-deb",
+                    "environment": "prod-server",
+                },
+                {
+                    "id": "health-production",
+                    "action": "health-check",
+                    "environment": "prod-server",
+                },
+                {"id": "ready-release", "action": "mark-ready"},
+            ],
+        }
+
+        self.assertEqual(validate_delivery.validate_builtin(contract), [])
+
+    def test_publish_and_health_check_require_prior_steps(self) -> None:
+        contract = valid_contract()
+        steps = contract["profiles"]["review"]["steps"]
+        steps[2], steps[3] = steps[3], steps[2]
+        steps[4], steps[5] = steps[5], steps[4]
+
+        errors = validate_delivery.validate_builtin(contract)
+
+        self.assertTrue(any("publish 前必须先 build" in item for item in errors))
+        self.assertTrue(any("health-check 前必须先 deploy" in item for item in errors))
+
+    def test_pull_request_requires_explicit_safe_remote_and_base(self) -> None:
+        contract = valid_contract()
+        step = contract["profiles"]["review"]["steps"][1]
+        del step["remote"]
+        step["baseBranch"] = "../main"
+
+        errors = validate_delivery.validate_builtin(contract)
+
+        self.assertTrue(any(".remote: action='pull-request' 时必填" in item for item in errors))
+        self.assertTrue(any(".remote: 必须是安全的 Git remote 名称" in item for item in errors))
+        self.assertTrue(any(".baseBranch: 必须是安全的 Git 分支名" in item for item in errors))
+
+    def test_unknown_shell_and_inline_secret_are_rejected(self) -> None:
+        contract = valid_contract()
+        contract["entrypoints"]["verify"]["shell"] = "make verify"
+        contract["entrypoints"]["verify"]["requiredSecrets"] = ["token-value"]
+        contract["destinations"]["preview-apt"]["repository"] = (
+            "token=abcdefghijklmnop"
+        )
+        contract["destinations"]["preview-apt"]["registry"] = "unexpected.example"
+
+        errors = validate_delivery.validate_builtin(contract)
+
+        self.assertTrue(any("未知字段 'shell'" in item for item in errors))
+        self.assertTrue(any("requiredSecrets" in item for item in errors))
+        self.assertTrue(any("type='apt-repository' 不允许此字段" in item for item in errors))
+        self.assertTrue(any("疑似包含敏感信息" in item for item in errors))
+
+    def test_project_script_must_be_executable_and_not_a_symlink(self) -> None:
+        contract = valid_contract()
+        contract["entrypoints"]["verify"] = {
+            "kind": "script",
+            "path": "scripts/verify.sh",
+            "args": [],
+            "requiredSecrets": [],
+            "workingDirectory": ".",
+            "timeoutSeconds": 300,
+        }
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            scripts = root / "scripts"
+            scripts.mkdir()
+            target = scripts / "target.sh"
+            target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            target.chmod(0o755)
+            os.symlink("target.sh", scripts / "verify.sh")
+
+            errors = validate_delivery.validate_builtin(contract, root)
+            self.assertTrue(any("路径不能包含 symlink" in item for item in errors))
+
+            (scripts / "verify.sh").unlink()
+            plain = scripts / "verify.sh"
+            plain.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            plain.chmod(0o644)
+            errors = validate_delivery.validate_builtin(contract, root)
+            self.assertTrue(any("脚本不可执行" in item for item in errors))
+
+    def test_tasks_link_requires_fixed_path_runs_and_same_project(self) -> None:
+        contract = valid_contract()
+        tasks = {
+            "project": {"name": "other", "deliveryFile": "delivery.yaml"},
+            "tasks": [],
+        }
+
+        errors = validate_delivery.validate_tasks_link(contract, tasks)
+
+        self.assertIn(
+            "tasks.project.deliveryFile 必须固定为 docs/ack/delivery.yaml",
+            errors,
+        )
+        self.assertIn("delivery.project.name 必须与 tasks.project.name 一致", errors)
+        self.assertIn("引用 deliveryFile 的任务板必须包含 deliveryRuns 列表", errors)
+
+    def test_disabled_empty_contract_remains_valid(self) -> None:
+        contract = copy.deepcopy(valid_contract())
+        contract.update(
+            {
+                "enabled": False,
+                "defaultProfile": None,
+                "entrypoints": {},
+                "artifacts": {},
+                "destinations": {},
+                "environments": {},
+                "profiles": {},
+            }
+        )
+
+        self.assertEqual(validate_delivery.validate_builtin(contract), [])
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+import copy
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+ACK_DIR = REPO_ROOT / "skills" / "ack"
+SCRIPTS_DIR = ACK_DIR / "scripts"
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+import launch_worker  # noqa: E402
+import validate_tasks  # noqa: E402
+import worker_profiles  # noqa: E402
+
+
+def operator_orchestration() -> dict:
+    return {
+        "profileVersion": 1,
+        "mode": "orca",
+        "allowedWorktrees": ["/repo/demo"],
+        "modelAllowlist": {
+            "codex": {
+                "developer": {"standard": ["gpt-dev"]},
+                "test": {"standard": ["gpt-low"]},
+                "operator": {"standard": ["gpt-low"]},
+            }
+        },
+        "profiles": {
+            "codex-dev-standard": {
+                "role": "developer",
+                "cli": "codex",
+                "tier": "standard",
+                "model": "gpt-dev",
+                "reasoningEffort": "medium",
+                "permissionMode": "workspace-write",
+            },
+            "codex-test-standard": {
+                "role": "test",
+                "cli": "codex",
+                "tier": "standard",
+                "model": "gpt-low",
+                "reasoningEffort": "low",
+                "permissionMode": "workspace-write",
+            },
+            "codex-operator-standard": {
+                "role": "operator",
+                "cli": "codex",
+                "tier": "standard",
+                "model": "gpt-low",
+                "reasoningEffort": "low",
+                "permissionMode": "workspace-write",
+            },
+        },
+        "defaults": {
+            "developer": "codex-dev-standard",
+            "test": "codex-test-standard",
+            "operator": "codex-operator-standard",
+        },
+    }
+
+
+def routed_board() -> dict:
+    return {
+        "version": 1,
+        "ackVersion": "0.12.0",
+        "project": {
+            "name": "demo",
+            "orchestration": operator_orchestration(),
+        },
+        "workerReceipts": [],
+        "tasks": [
+            {
+                "id": "DELIVERY-001",
+                "type": "delivery-operation",
+                "title": "publish one DEB",
+                "status": "open",
+                "operation": {
+                    "skill": "deb-publisher",
+                    "request": "发布 1.2.3 的 amd64 DEB 到 testing 仓库",
+                },
+                "dispatch": {
+                    "operator": {
+                        "profileId": "codex-operator-standard",
+                        "receiptId": None,
+                        "attemptId": None,
+                        "taskId": None,
+                        "dispatchId": None,
+                    },
+                    "rounds": [],
+                },
+            }
+        ],
+    }
+
+
+class AckDeliveryRoutingTests(unittest.TestCase):
+    def test_operator_profile_uses_the_test_low_cost_model(self) -> None:
+        routing = operator_orchestration()
+
+        self.assertEqual(worker_profiles.validate_orchestration(routing), [])
+
+        routing["profiles"]["codex-operator-standard"]["model"] = "gpt-other"
+        routing["modelAllowlist"]["codex"]["operator"]["standard"] = [
+            "gpt-other"
+        ]
+        errors = worker_profiles.validate_orchestration(routing)
+        self.assertTrue(
+            any("operator default must use the Test default model" in error for error in errors),
+            errors,
+        )
+
+    def test_operator_is_standard_only_and_optional_for_legacy_projects(self) -> None:
+        routing = operator_orchestration()
+        operator = routing["profiles"]["codex-operator-standard"]
+        operator["tier"] = "strong"
+        routing["modelAllowlist"]["codex"]["operator"] = {
+            "strong": ["gpt-low"]
+        }
+
+        errors = worker_profiles.validate_orchestration(routing)
+        self.assertTrue(any("Operator may only use standard" in error for error in errors))
+
+        legacy = operator_orchestration()
+        del legacy["defaults"]["operator"]
+        del legacy["profiles"]["codex-operator-standard"]
+        del legacy["modelAllowlist"]["codex"]["operator"]
+        self.assertEqual(worker_profiles.validate_orchestration(legacy), [])
+
+    def test_delivery_operation_requires_a_supported_route_and_operator_dispatch(self) -> None:
+        board = routed_board()
+        self.assertEqual(validate_tasks.validate_builtin(board), [])
+
+        missing_operation = copy.deepcopy(board)
+        del missing_operation["tasks"][0]["operation"]
+        errors = validate_tasks.validate_builtin(missing_operation)
+        self.assertTrue(any("delivery-operation 必须声明 operation" in error for error in errors))
+
+        unsupported = copy.deepcopy(board)
+        unsupported["tasks"][0]["operation"]["skill"] = "shell"
+        errors = validate_tasks.validate_builtin(unsupported)
+        self.assertTrue(any("manage-release/deb-publisher/publish-docker-image" in error for error in errors))
+
+        missing_dispatch = copy.deepcopy(board)
+        del missing_dispatch["tasks"][0]["dispatch"]["operator"]
+        errors = validate_tasks.validate_builtin(missing_dispatch)
+        self.assertTrue(any("delivery-operation 必须声明 dispatch.operator" in error for error in errors))
+
+    def test_delivery_operation_cannot_be_reused_as_a_profile_delivery_run(self) -> None:
+        board = routed_board()
+        board["project"]["deliveryFile"] = "docs/ack/delivery.yaml"
+        board["tasks"][0]["status"] = "verified"
+        board["deliveryRuns"] = [
+            {
+                "id": "DR-duplicate-route",
+                "profile": "review",
+                "taskIds": ["DELIVERY-001"],
+                "status": "planned",
+                "sourceRevision": "a" * 40,
+                "configRevision": "b" * 40,
+                "pullRequest": None,
+                "artifacts": [],
+                "deployments": [],
+                "evidence": [],
+                "updatedAt": "2026-08-01T10:00:00+08:00",
+            }
+        ]
+
+        errors = validate_tasks.validate_builtin(board)
+
+        self.assertTrue(
+            any("deliveryRuns 不能引用 delivery-operation" in error for error in errors),
+            errors,
+        )
+
+    def test_launcher_creates_an_operator_plan_on_the_low_cost_profile(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            project = Path(temporary).resolve()
+            executable = project / "codex"
+            executable.write_text("#!/bin/sh\n", encoding="utf-8")
+            executable.chmod(0o700)
+            routing = operator_orchestration()
+            routing["allowedWorktrees"] = [str(project)]
+            board = routed_board()
+            board["project"]["repoPath"] = str(project)
+            board["project"]["orchestration"] = routing
+            metadata = project.stat()
+            identity = {
+                "path": str(project),
+                "device": metadata.st_dev,
+                "inode": metadata.st_ino,
+                "gitCommonDir": str(project / ".git"),
+                "gitCommonDevice": metadata.st_dev,
+                "gitCommonInode": metadata.st_ino,
+            }
+
+            with (
+                mock.patch.object(
+                    launch_worker,
+                    "load_authoritative_board",
+                    return_value=(project, board),
+                ),
+                mock.patch.object(
+                    launch_worker,
+                    "capture_worktree_identity",
+                    return_value=identity,
+                ),
+                mock.patch.object(
+                    launch_worker,
+                    "resolve_executable",
+                    return_value=executable,
+                ),
+                mock.patch.object(
+                    launch_worker,
+                    "run_text",
+                    return_value="codex-cli 1.0",
+                ),
+            ):
+                plan = launch_worker.build_plan(
+                    project_root_value=str(project),
+                    task_id="DELIVERY-001",
+                    attempt_id="DELIVERY-001-A1",
+                    role="operator",
+                    profile_id="codex-operator-standard",
+                    worktree_value=str(project),
+                    slot=1,
+                )
+            receipt = launch_worker.build_receipt(
+                "c" * 64,
+                plan,
+                "runtime-1",
+                {
+                    "handle": "terminal-1",
+                    "incarnationId": "incarnation-1",
+                    "connected": True,
+                    "writable": True,
+                    "worktreePath": str(project),
+                },
+                "2026-08-01T10:00:00+08:00",
+            )
+            receipt_errors = worker_profiles.validate_worker_receipt(
+                receipt,
+                orchestration=routing,
+                task_ids={"DELIVERY-001"},
+            )
+
+        self.assertEqual(plan["role"], "operator")
+        self.assertEqual(plan["requested"]["model"], "gpt-low")
+        self.assertEqual(
+            plan["requested"]["environmentPolicy"],
+            "per-cli-plus-operator-publish-v1",
+        )
+        self.assertTrue(plan["title"].startswith("ACK-OP-CODEX-STANDARD-"))
+        self.assertEqual(receipt_errors, [])
+
+    def test_launcher_binds_operator_to_delivery_operation_tasks(self) -> None:
+        delivery_board = routed_board()
+        ordinary_board = copy.deepcopy(delivery_board)
+        ordinary_task = ordinary_board["tasks"][0]
+        ordinary_task["id"] = "TASK-001"
+        ordinary_task["type"] = "feature"
+        del ordinary_task["operation"]
+
+        with mock.patch.object(
+            launch_worker,
+            "load_authoritative_board",
+            return_value=(Path("/repo/demo"), ordinary_board),
+        ):
+            with self.assertRaisesRegex(
+                launch_worker.LaunchError,
+                "operator 只能用于 delivery-operation",
+            ):
+                launch_worker.build_plan(
+                    project_root_value="/repo/demo",
+                    task_id="TASK-001",
+                    attempt_id="TASK-001-A1",
+                    role="operator",
+                    profile_id="codex-operator-standard",
+                    worktree_value="/repo/demo",
+                    slot=1,
+                )
+
+        with mock.patch.object(
+            launch_worker,
+            "load_authoritative_board",
+            return_value=(Path("/repo/demo"), delivery_board),
+        ):
+            with self.assertRaisesRegex(
+                launch_worker.LaunchError,
+                "delivery-operation 任务只能由 operator",
+            ):
+                launch_worker.build_plan(
+                    project_root_value="/repo/demo",
+                    task_id="DELIVERY-001",
+                    attempt_id="DELIVERY-001-A1",
+                    role="test",
+                    profile_id="codex-test-standard",
+                    worktree_value="/repo/demo",
+                    slot=1,
+                )
+
+    def test_operator_gets_only_fixed_release_credentials(self) -> None:
+        with mock.patch.dict(
+            "os.environ",
+            {
+                "OPENAI_API_KEY": "agent-token",
+                "DEB_TOKEN": "deb-token",
+                "DEB_SERVER_URL": "https://packages.example.com",
+                "DEB_REPOSITORY": "testing",
+                "SSH_AUTH_SOCK": "/tmp/agent.sock",
+                "GIT_SSH_COMMAND": "unsafe override",
+                "DOCKER_PASSWORD": "must-not-pass",
+            },
+            clear=True,
+        ):
+            operator = launch_worker.worker_environment("codex", "operator")
+            test = launch_worker.worker_environment("codex", "test")
+
+        self.assertEqual(operator["DEB_TOKEN"], "deb-token")
+        self.assertEqual(operator["SSH_AUTH_SOCK"], "/tmp/agent.sock")
+        self.assertEqual(operator["OPENAI_API_KEY"], "agent-token")
+        self.assertNotIn("DEB_TOKEN", test)
+        self.assertNotIn("SSH_AUTH_SOCK", test)
+        self.assertNotIn("GIT_SSH_COMMAND", operator)
+        self.assertNotIn("DOCKER_PASSWORD", operator)
+
+    def test_ack_documents_the_three_routes_and_non_release_pr_boundary(self) -> None:
+        skill = (ACK_DIR / "SKILL.md").read_text(encoding="utf-8")
+        routing = (ACK_DIR / "references" / "delivery-routing.md").read_text(
+            encoding="utf-8"
+        )
+        docker = (
+            REPO_ROOT / "skills" / "publish-docker-image" / "SKILL.md"
+        ).read_text(encoding="utf-8")
+        release = (
+            REPO_ROOT / "skills" / "manage-release" / "SKILL.md"
+        ).read_text(encoding="utf-8")
+
+        self.assertIn("references/delivery-routing.md", skill)
+        for name in ("manage-release", "deb-publisher", "publish-docker-image"):
+            self.assertIn(name, routing)
+        self.assertIn("普通 PR/MR", routing)
+        self.assertIn("由显式调用的 `$ack`", docker)
+        self.assertIn("由显式调用的 `$ack`", release)
+        self.assertIn("PR-only", release)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,937 @@
+from __future__ import annotations
+
+import copy
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import yaml
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+ACK_DIR = REPO_ROOT / "skills" / "ack"
+SCRIPTS_DIR = ACK_DIR / "scripts"
+SCHEMA_PATH = ACK_DIR / "templates" / "knowledge.schema.json"
+EXAMPLE_PATH = ACK_DIR / "examples" / "knowledge.example.yaml"
+TASKS_EXAMPLE_PATH = ACK_DIR / "examples" / "tasks.example.yaml"
+
+sys.path.insert(0, str(SCRIPTS_DIR))
+import select_knowledge  # noqa: E402
+import validate_knowledge  # noqa: E402
+
+
+def example_data() -> dict:
+    return yaml.safe_load(EXAMPLE_PATH.read_text(encoding="utf-8"))
+
+
+class AckKnowledgeTests(unittest.TestCase):
+    def test_schema_template_and_example_are_aligned(self) -> None:
+        schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+        template = yaml.safe_load(
+            (ACK_DIR / "templates" / "knowledge.template.yaml").read_text(
+                encoding="utf-8"
+            )
+        )
+        self.assertEqual(
+            schema["definitions"]["entry"]["properties"]["kind"]["enum"],
+            ["guardrail", "pitfall", "verification"],
+        )
+        self.assertEqual(
+            schema["definitions"]["entry"]["properties"]["status"]["enum"],
+            ["active", "stale", "superseded", "archived"],
+        )
+        self.assertEqual(template["entries"], [])
+        self.assertEqual(template["verificationRegistry"], {})
+
+        errors, _ = validate_knowledge.validate_all(
+            example_data(), SCHEMA_PATH, use_schema=False
+        )
+        self.assertEqual(errors, [])
+        self.assertEqual(
+            validate_knowledge.stable_ref(example_data()["entries"][0]), "K-001@1"
+        )
+
+    def test_semantics_run_even_when_schema_reports_no_errors(self) -> None:
+        data = example_data()
+        data["entries"].append(copy.deepcopy(data["entries"][0]))
+        with mock.patch.object(
+            validate_knowledge, "validate_with_schema", return_value=[]
+        ):
+            errors, mode = validate_knowledge.validate_all(
+                data, SCHEMA_PATH, use_schema=True
+            )
+        self.assertIn("内置语义", mode)
+        self.assertTrue(any("稳定引用 K-001@1 重复" in error for error in errors))
+
+    def test_blank_required_text_fails_in_builtin_and_schema_modes(self) -> None:
+        data = example_data()
+        data["entries"][0]["title"] = " \t "
+
+        builtin_errors, _ = validate_knowledge.validate_all(
+            data, SCHEMA_PATH, use_schema=False
+        )
+        with mock.patch.object(
+            validate_knowledge, "validate_with_schema", return_value=[]
+        ):
+            schema_errors, _ = validate_knowledge.validate_all(
+                data, SCHEMA_PATH, use_schema=True
+            )
+
+        self.assertTrue(any("title: 必须是非空字符串" in e for e in builtin_errors))
+        self.assertTrue(any("title: 必须是非空字符串" in e for e in schema_errors))
+        schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+        self.assertEqual(
+            schema["definitions"]["entry"]["properties"]["title"]["pattern"],
+            "\\S",
+        )
+
+    def test_temporary_entry_requires_removal_condition_and_review_date(self) -> None:
+        data = example_data()
+        entry = data["entries"][0]
+        entry["temporary"] = True
+        entry["removalCondition"] = None
+        entry["reviewAfter"] = None
+        errors = validate_knowledge.validate_semantics(data)
+        self.assertTrue(any("removalCondition" in error for error in errors))
+        self.assertTrue(any("reviewAfter" in error for error in errors))
+
+    def test_overdue_active_entry_requires_revalidation(self) -> None:
+        data = example_data()
+        data["entries"][0]["reviewAfter"] = "2020-01-01T00:00:00+00:00"
+
+        errors = validate_knowledge.validate_semantics(data)
+
+        self.assertTrue(any("必须重新验证或标记 stale" in error for error in errors))
+
+    def test_global_active_entry_requires_decision_owner_approval(self) -> None:
+        data = example_data()
+        data["entries"][0]["scope"] = {
+            "all": True,
+            "components": [],
+            "paths": [],
+            "dependencies": [],
+            "versions": [],
+            "tags": [],
+            "symbols": [],
+            "errorSignatures": [],
+        }
+
+        errors = validate_knowledge.validate_semantics(data)
+
+        self.assertTrue(any("Decision Owner approval" in error for error in errors))
+
+    def test_active_conflicts_and_duplicate_active_revision_are_rejected(self) -> None:
+        data = example_data()
+        conflicting = copy.deepcopy(data["entries"][0])
+        conflicting.update(
+            {
+                "id": "K-002",
+                "subject": "service-process-alignment",
+                "conflictsWith": ["K-001@1"],
+            }
+        )
+        data["entries"].append(conflicting)
+        errors = validate_knowledge.validate_semantics(data)
+        self.assertTrue(any("active 条目不能与 active K-001@1 冲突" in e for e in errors))
+
+        conflicting["id"] = "K-001"
+        conflicting["revision"] = 2
+        conflicting["conflictsWith"] = []
+        errors = validate_knowledge.validate_semantics(data)
+        self.assertTrue(any("多个 active revision" in error for error in errors))
+
+    def test_verification_ref_must_resolve_to_contained_registry_target(self) -> None:
+        data = example_data()
+        data["entries"][0]["verification"]["ref"] = "missing-check"
+        errors = validate_knowledge.validate_semantics(data)
+        self.assertTrue(any("未在 verificationRegistry 注册" in e for e in errors))
+
+        data = example_data()
+        data["verificationRegistry"]["service-worktree-alignment"]["path"] = "../run.sh"
+        errors = validate_knowledge.validate_semantics(data)
+        self.assertTrue(any("必须是仓库内相对路径" in error for error in errors))
+
+    def test_verification_registry_rejects_any_symlink_component(self) -> None:
+        data = example_data()
+        data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
+            "checks/verify.py"
+        )
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base = Path(temp_dir)
+            project = base / "project"
+            outside = base / "outside"
+            project.mkdir()
+            outside.mkdir()
+            (project / "checks").symlink_to(outside, target_is_directory=True)
+
+            errors = validate_knowledge.validate_semantics(
+                data, project_root=project
+            )
+
+        self.assertTrue(any("symlink" in error for error in errors))
+
+        data = example_data()
+        data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
+            "checks/verify.py"
+        )
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            real_checks = project / "real-checks"
+            real_checks.mkdir(parents=True)
+            target = real_checks / "verify.py"
+            target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            target.chmod(target.stat().st_mode | 0o111)
+            (project / "checks").symlink_to(
+                real_checks,
+                target_is_directory=True,
+            )
+
+            errors = validate_knowledge.validate_semantics(
+                data,
+                project_root=project,
+            )
+
+        self.assertTrue(any("symlink" in error for error in errors))
+
+        data = example_data()
+        data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
+            "tests/check.sh;touch"
+        )
+        errors = validate_knowledge.validate_semantics(data)
+        self.assertTrue(any("必须是仓库内相对路径" in error for error in errors))
+
+    def test_verification_registry_requires_regular_executable_target(self) -> None:
+        data = example_data()
+        data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
+            "checks/verify"
+        )
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            project.mkdir()
+
+            missing = validate_knowledge.validate_semantics(
+                data,
+                project_root=project,
+            )
+            self.assertTrue(any("不存在" in error for error in missing))
+
+            target = project / "checks" / "verify"
+            target.parent.mkdir()
+            target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            not_executable = validate_knowledge.validate_semantics(
+                data,
+                project_root=project,
+            )
+            self.assertTrue(
+                any("不可执行" in error for error in not_executable)
+            )
+
+            target.chmod(target.stat().st_mode | 0o111)
+            valid = validate_knowledge.validate_semantics(
+                data,
+                project_root=project,
+            )
+            self.assertFalse(
+                any("verificationRegistry" in error for error in valid),
+                valid,
+            )
+
+    def test_free_command_fields_are_rejected_and_never_executed(self) -> None:
+        data = example_data()
+        data["entries"][0]["command"] = "echo unsafe"
+        errors = validate_knowledge.validate_semantics(data)
+        self.assertTrue(any("不保存或执行自由命令" in error for error in errors))
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            marker = Path(temp_dir) / "should-not-exist"
+            safe = example_data()
+            safe["entries"][0]["directive"] = f"touch {marker}"
+            selected = select_knowledge.select_entries(
+                safe,
+                {
+                    "components": ["web"],
+                    "paths": ["web/app.py"],
+                    "dependencies": [],
+                    "versions": [],
+                    "tags": ["long-running-service"],
+                    "symbols": [],
+                    "errorSignatures": [],
+                },
+            )
+            self.assertEqual(len(selected), 1)
+            self.assertFalse(marker.exists())
+
+    def test_common_secret_material_is_rejected(self) -> None:
+        data = example_data()
+        data["entries"][0]["rationale"] = (
+            "debug token=sk-abcdefghijklmnopqrstuvwxyz123456"
+        )
+
+        errors = validate_knowledge.validate_semantics(data)
+
+        self.assertTrue(any("OpenAI-style token" in error for error in errors))
+        self.assertTrue(any("脱敏摘要" in error for error in errors))
+
+    def test_selection_is_active_deterministic_and_limited(self) -> None:
+        data = example_data()
+        stale = copy.deepcopy(data["entries"][0])
+        stale.update(
+            {
+                "id": "K-002",
+                "status": "stale",
+                "statusReason": "相关服务已移除",
+            }
+        )
+        global_entry = copy.deepcopy(data["entries"][0])
+        global_entry.update(
+            {
+                "id": "K-003",
+                "subject": "global-release-check",
+                "scope": {
+                    "all": True,
+                    "components": [],
+                    "paths": [],
+                    "dependencies": [],
+                    "versions": [],
+                    "tags": [],
+                    "symbols": [],
+                    "errorSignatures": [],
+                },
+            }
+        )
+        data["entries"].extend([stale, global_entry])
+        context = {
+            "components": ["web"],
+            "paths": ["web/app.py"],
+            "dependencies": [],
+            "versions": [],
+            "tags": ["long-running-service"],
+            "symbols": [],
+            "errorSignatures": [],
+        }
+        selected = select_knowledge.select_entries(data, context, limit=1)
+        self.assertEqual(
+            [validate_knowledge.stable_ref(entry) for entry in selected], ["K-003@1"]
+        )
+        self.assertFalse(
+            select_knowledge.scope_matches(
+                data["entries"][0]["scope"],
+                {**context, "tags": []},
+            )
+        )
+
+    def test_global_entries_are_never_silently_dropped_by_limit(self) -> None:
+        data = example_data()
+        for number in range(2, 13):
+            scoped = copy.deepcopy(data["entries"][0])
+            scoped.update(
+                {
+                    "id": f"K-{number:03d}",
+                    "subject": f"scoped-check-{number}",
+                }
+            )
+            data["entries"].append(scoped)
+        global_entry = copy.deepcopy(data["entries"][0])
+        global_entry.update(
+            {
+                "id": "K-999",
+                "subject": "global-release-check",
+                "scope": {
+                    "all": True,
+                    "components": [],
+                    "paths": [],
+                    "dependencies": [],
+                    "versions": [],
+                    "tags": [],
+                    "symbols": [],
+                    "errorSignatures": [],
+                },
+            }
+        )
+        data["entries"].append(global_entry)
+        context = {
+            "components": ["web"],
+            "paths": ["web/app.py"],
+            "dependencies": [],
+            "versions": [],
+            "tags": ["long-running-service"],
+            "symbols": [],
+            "errorSignatures": [],
+        }
+
+        selected = select_knowledge.select_entries(data, context, limit=10)
+
+        refs = [validate_knowledge.stable_ref(entry) for entry in selected]
+        self.assertEqual(len(refs), 10)
+        self.assertIn("K-999@1", refs)
+
+        second_global = copy.deepcopy(global_entry)
+        second_global.update({"id": "K-998", "subject": "global-security-check"})
+        data["entries"].append(second_global)
+        with self.assertRaisesRegex(ValueError, "不能静默丢弃"):
+            select_knowledge.select_entries(data, context, limit=1)
+
+    def test_path_glob_does_not_let_single_star_cross_directory(self) -> None:
+        self.assertTrue(select_knowledge._path_glob_matches("web/app.py", "web/*"))
+        self.assertFalse(
+            select_knowledge._path_glob_matches("web/pages/app.py", "web/*")
+        )
+        self.assertTrue(
+            select_knowledge._path_glob_matches("web/pages/app.py", "web/**")
+        )
+
+    def test_limit_prefers_narrow_scope_without_rewarding_or_patterns(self) -> None:
+        data = example_data()
+        narrow = copy.deepcopy(data["entries"][0])
+        narrow.update({"id": "K-002", "subject": "narrow-service-check"})
+        narrow["scope"]["paths"] = ["web/special/**"]
+        broad_or = copy.deepcopy(data["entries"][0])
+        broad_or.update({"id": "K-003", "subject": "broad-or-service-check"})
+        broad_or["scope"]["paths"] = ["web/special/**", "api/**"]
+        data["entries"].extend([narrow, broad_or])
+        context = {
+            "components": ["web"],
+            "paths": ["web/special/pages/app.py"],
+            "dependencies": [],
+            "versions": [],
+            "tags": ["long-running-service"],
+            "symbols": [],
+            "errorSignatures": [],
+        }
+
+        selected = select_knowledge.select_entries(data, context, limit=1)
+
+        self.assertEqual(validate_knowledge.stable_ref(selected[0]), "K-002@1")
+
+    def test_task_cross_validation_requires_active_exact_ref_and_passed_check(self) -> None:
+        data = example_data()
+        task = {
+            "id": "BUG-002",
+            "status": "verified",
+            "knowledgeRefs": ["K-001@1"],
+            "knowledgeApplied": [
+                {
+                    "ref": "K-001@1",
+                    "result": "applied",
+                    "evidence": "developer report",
+                }
+            ],
+            "knowledgeChecks": [
+                {
+                    "ref": "K-001@1",
+                    "result": "passed",
+                    "evidence": "test report",
+                }
+            ],
+            "dispatch": {
+                "rounds": [
+                    {
+                        "round": 1,
+                        "attemptId": "BUG-002-A1",
+                        "result": "failed",
+                    },
+                    {
+                        "round": 2,
+                        "attemptId": "BUG-002-A2",
+                        "result": "passed",
+                    }
+                ]
+            },
+        }
+        tasks_data = {
+            "project": {
+                "name": "notes-web",
+                "knowledgeFile": "docs/ack/knowledge.yaml",
+            },
+            "tasks": [task],
+        }
+        self.assertEqual(
+            validate_knowledge.validate_task_references(data, tasks_data), []
+        )
+
+        task["knowledgeChecks"][0]["result"] = "not_applicable"
+        errors = validate_knowledge.validate_task_references(data, tasks_data)
+        self.assertTrue(any("缺少 passed knowledgeCheck" in error for error in errors))
+
+        data["entries"][0]["kind"] = "pitfall"
+        errors = validate_knowledge.validate_task_references(data, tasks_data)
+        self.assertTrue(any("缺少 passed knowledgeCheck" in error for error in errors))
+
+        task["knowledgeRefs"] = ["K-001@2"]
+        errors = validate_knowledge.validate_task_references(data, tasks_data)
+        self.assertTrue(any("找不到精确版本 K-001@2" in error for error in errors))
+
+    def test_task_cross_validation_rejects_another_project(self) -> None:
+        data = example_data()
+        tasks = {
+            "project": {
+                "name": "another-project",
+                "knowledgeFile": "docs/ack/knowledge.yaml",
+            },
+            "tasks": [],
+        }
+
+        errors = validate_knowledge.validate_task_references(data, tasks)
+
+        self.assertTrue(any("与知识库项目" in error for error in errors))
+
+    def test_cross_validation_requires_traceable_explicit_attempt_id(self) -> None:
+        data = example_data()
+        task = {
+            "id": "BUG-002",
+            "status": "open",
+            "dispatch": {
+                "rounds": [
+                    {
+                        "round": 1,
+                        "attemptId": "BUG-002-A1",
+                        "result": "failed",
+                    },
+                    {
+                        "round": 2,
+                        "attemptId": "orca-dispatch-91",
+                        "result": "passed",
+                    }
+                ]
+            },
+        }
+        tasks_data = {
+            "project": {
+                "name": "notes-web",
+                "knowledgeFile": "docs/ack/knowledge.yaml",
+            },
+            "tasks": [task],
+        }
+
+        errors = validate_knowledge.validate_task_references(data, tasks_data)
+
+        self.assertTrue(any("必须精确等于 'BUG-002-A2'" in e for e in errors))
+        self.assertTrue(any("未命中任务 'BUG-002'" in e for e in errors))
+
+        task["dispatch"]["rounds"][1]["attemptId"] = "BUG-002-A2"
+        errors = validate_knowledge.validate_task_references(data, tasks_data)
+        self.assertFalse(any("provenance" in error for error in errors))
+
+    def test_cross_validation_rejects_non_contiguous_rounds(self) -> None:
+        data = example_data()
+        data["entries"][0]["provenance"]["attemptId"] = "BUG-002-A3"
+        tasks_data = {
+            "project": {
+                "name": "notes-web",
+                "knowledgeFile": "docs/ack/knowledge.yaml",
+            },
+            "tasks": [
+                {
+                    "id": "BUG-002",
+                    "status": "open",
+                    "dispatch": {
+                        "rounds": [
+                            {
+                                "round": 3,
+                                "attemptId": "BUG-002-A3",
+                                "result": "passed",
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+
+        errors = validate_knowledge.validate_task_references(data, tasks_data)
+
+        self.assertTrue(any("round 必须按 1..N 连续" in error for error in errors))
+
+    def test_cross_validation_binds_configured_knowledge_file(self) -> None:
+        data = example_data()
+        task = {
+            "id": "BUG-002",
+            "status": "open",
+            "dispatch": {
+                "rounds": [
+                    {
+                        "round": 1,
+                        "attemptId": "BUG-002-A1",
+                        "result": "failed",
+                    },
+                    {
+                        "round": 2,
+                        "attemptId": "BUG-002-A2",
+                        "result": "passed",
+                    }
+                ]
+            },
+        }
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            ack_dir = project / "docs" / "ack"
+            ack_dir.mkdir(parents=True)
+            knowledge_path = ack_dir / "knowledge.yaml"
+            tasks_path = ack_dir / "tasks.yaml"
+            knowledge_path.write_text(
+                yaml.safe_dump(data, allow_unicode=True), encoding="utf-8"
+            )
+            tasks_data = {
+                "project": {
+                    "name": "notes-web",
+                    "repoPath": str(project),
+                    "knowledgeFile": "docs/ack/other.yaml",
+                },
+                "tasks": [task],
+            }
+
+            errors = validate_knowledge.validate_task_references(
+                data,
+                tasks_data,
+                knowledge_path=knowledge_path,
+                tasks_path=tasks_path,
+            )
+            self.assertTrue(any("与当前知识文件" in error for error in errors))
+
+            del tasks_data["project"]["knowledgeFile"]
+            errors = validate_knowledge.validate_task_references(data, tasks_data)
+            self.assertTrue(any("project.knowledgeFile 必填" in e for e in errors))
+
+            tasks_data["project"]["knowledgeFile"] = "docs/ack/knowledge.yaml"
+            staging_root = Path(temp_dir) / "staging"
+            staged = staging_root / "docs" / "ack" / "knowledge.yaml"
+            staged.parent.mkdir(parents=True)
+            staged.write_text(
+                yaml.safe_dump(data, allow_unicode=True), encoding="utf-8"
+            )
+            errors = validate_knowledge.validate_task_references(
+                data,
+                tasks_data,
+                knowledge_path=staged,
+                tasks_path=tasks_path,
+                project_root=staging_root,
+                project_root_is_explicit=True,
+            )
+            self.assertFalse(any("knowledgeFile" in error for error in errors))
+
+    def test_cli_fails_closed_for_missing_repo_root_and_wrong_binding(self) -> None:
+        data = example_data()
+        task = {
+            "id": "BUG-002",
+            "title": "source task",
+            "status": "open",
+            "dispatch": {
+                "rounds": [
+                    {
+                        "round": 1,
+                        "attemptId": "BUG-002-A1",
+                        "result": "failed",
+                    },
+                    {
+                        "round": 2,
+                        "attemptId": "BUG-002-A2",
+                        "result": "passed",
+                    }
+                ]
+            },
+        }
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base = Path(temp_dir)
+            project = base / "project"
+            ack_dir = project / "docs" / "ack"
+            outside = base / "outside"
+            ack_dir.mkdir(parents=True)
+            outside.mkdir()
+            (project / "checks").symlink_to(outside, target_is_directory=True)
+            data["verificationRegistry"]["service-worktree-alignment"]["path"] = (
+                "checks/verify.py"
+            )
+            knowledge_path = ack_dir / "knowledge.yaml"
+            knowledge_path.write_text(
+                yaml.safe_dump(data, allow_unicode=True), encoding="utf-8"
+            )
+            tasks_data = {
+                "version": 1,
+                "project": {
+                    "name": "notes-web",
+                    "repoPath": str(project / "missing"),
+                    "knowledgeFile": "docs/ack/not-the-current-file.yaml",
+                },
+                "tasks": [task],
+            }
+            tasks_path = ack_dir / "tasks.yaml"
+            tasks_path.write_text(
+                yaml.safe_dump(tasks_data, allow_unicode=True), encoding="utf-8"
+            )
+
+            command = [
+                sys.executable,
+                str(SCRIPTS_DIR / "validate_knowledge.py"),
+                str(knowledge_path),
+                "--tasks",
+                str(tasks_path),
+            ]
+            inferred = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            explicit = subprocess.run(
+                [*command, "--project-root", str(project)],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+        self.assertEqual(inferred.returncode, 1)
+        self.assertIn("project.repoPath", inferred.stderr)
+        self.assertIn("与当前知识文件", inferred.stderr)
+        self.assertIn("symlink", inferred.stderr)
+        self.assertEqual(explicit.returncode, 1)
+        self.assertIn("与当前知识文件", explicit.stderr)
+        self.assertIn("symlink", explicit.stderr)
+
+    def test_cli_requires_root_for_nonempty_registry_outside_project_layout(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            knowledge_path = Path(temp_dir) / "knowledge.yaml"
+            knowledge_path.write_text(
+                EXAMPLE_PATH.read_text(encoding="utf-8"), encoding="utf-8"
+            )
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(SCRIPTS_DIR / "validate_knowledge.py"),
+                    str(knowledge_path),
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("无法确定项目根目录", result.stderr)
+        self.assertIn("--project-root", result.stderr)
+
+    def test_terminal_task_keeps_historical_ref_after_entry_becomes_stale(self) -> None:
+        data = example_data()
+        data["entries"][0]["status"] = "stale"
+        data["entries"][0]["statusReason"] = "service architecture changed"
+        task = {
+            "id": "BUG-002",
+            "status": "verified",
+            "knowledgeRefs": ["K-001@1"],
+            "knowledgeApplied": [],
+            "knowledgeChecks": [
+                {
+                    "ref": "K-001@1",
+                    "result": "passed",
+                    "evidence": "historical test evidence",
+                }
+            ],
+            "dispatch": {
+                "rounds": [
+                    {
+                        "round": 1,
+                        "attemptId": "BUG-002-A1",
+                        "result": "failed",
+                    },
+                    {
+                        "round": 2,
+                        "attemptId": "BUG-002-A2",
+                        "result": "passed",
+                    }
+                ]
+            },
+        }
+        tasks_data = {
+            "project": {
+                "name": "notes-web",
+                "knowledgeFile": "docs/ack/knowledge.yaml",
+            },
+            "tasks": [task],
+        }
+
+        terminal_errors = validate_knowledge.validate_task_references(
+            data, tasks_data
+        )
+        self.assertFalse(any("必须 active" in error for error in terminal_errors))
+
+        task["status"] = "open"
+        active_errors = validate_knowledge.validate_task_references(
+            data, tasks_data
+        )
+        self.assertTrue(any("必须 active" in error for error in active_errors))
+
+    def test_cli_validates_tasks_and_selector_outputs_stable_refs(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            ack_dir = project / "docs" / "ack"
+            ack_dir.mkdir(parents=True)
+            knowledge_path = ack_dir / "knowledge.yaml"
+            knowledge_path.write_text(
+                EXAMPLE_PATH.read_text(encoding="utf-8"), encoding="utf-8"
+            )
+            target = project / "tests" / "ack" / "check_service_worktree.py"
+            target.parent.mkdir(parents=True)
+            target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            target.chmod(target.stat().st_mode | 0o111)
+            tasks = {
+                "project": {
+                    "name": "notes-web",
+                    "repoPath": str(project),
+                    "knowledgeFile": "docs/ack/knowledge.yaml",
+                },
+                "tasks": [
+                    {
+                        "id": "BUG-002",
+                        "status": "verified",
+                        "knowledgeRefs": ["K-001@1"],
+                        "knowledgeApplied": [],
+                        "knowledgeChecks": [
+                            {
+                                "ref": "K-001@1",
+                                "result": "passed",
+                                "evidence": "independent retest",
+                            }
+                        ],
+                        "dispatch": {
+                            "rounds": [
+                                {
+                                    "round": 1,
+                                    "attemptId": "BUG-002-A1",
+                                    "result": "failed",
+                                },
+                                {
+                                    "round": 2,
+                                    "attemptId": "BUG-002-A2",
+                                    "result": "passed",
+                                }
+                            ]
+                        },
+                    }
+                ],
+            }
+            tasks_path = ack_dir / "tasks.yaml"
+            tasks_path.write_text(
+                yaml.safe_dump(tasks, allow_unicode=True), encoding="utf-8"
+            )
+            validated = subprocess.run(
+                [
+                    sys.executable,
+                    str(SCRIPTS_DIR / "validate_knowledge.py"),
+                    str(knowledge_path),
+                    "--tasks",
+                    str(tasks_path),
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            self.assertEqual(validated.returncode, 0, validated.stderr)
+
+            selected = subprocess.run(
+                [
+                    sys.executable,
+                    str(SCRIPTS_DIR / "select_knowledge.py"),
+                    str(knowledge_path),
+                    "--component",
+                    "web",
+                    "--path",
+                    "web/app.py",
+                    "--tag",
+                    "long-running-service",
+                    "--limit",
+                    "1",
+                    "--format",
+                    "refs",
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            self.assertEqual(selected.returncode, 0, selected.stderr)
+            self.assertEqual(selected.stdout.strip(), "K-001@1")
+
+            selected_json = subprocess.run(
+                [
+                    sys.executable,
+                    str(SCRIPTS_DIR / "select_knowledge.py"),
+                    str(knowledge_path),
+                    "--component",
+                    "web",
+                    "--path",
+                    "web/app.py",
+                    "--tag",
+                    "long-running-service",
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            self.assertEqual(selected_json.returncode, 0, selected_json.stderr)
+            payload = json.loads(selected_json.stdout)
+            self.assertEqual(
+                payload["entries"][0]["verificationTarget"]["path"],
+                "tests/ack/check_service_worktree.py",
+            )
+
+    def test_paired_examples_validate_when_installed_in_project_layout(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "notes-web"
+            ack_dir = project / "docs" / "ack"
+            ack_dir.mkdir(parents=True)
+            knowledge_path = ack_dir / "knowledge.yaml"
+            tasks_path = ack_dir / "tasks.yaml"
+            knowledge_path.write_text(
+                EXAMPLE_PATH.read_text(encoding="utf-8"),
+                encoding="utf-8",
+            )
+            tasks = yaml.safe_load(
+                TASKS_EXAMPLE_PATH.read_text(encoding="utf-8")
+            )
+            tasks["project"]["repoPath"] = str(project)
+            tasks["project"]["devWorktree"] = str(project)
+            tasks_path.write_text(
+                yaml.safe_dump(tasks, allow_unicode=True, sort_keys=False),
+                encoding="utf-8",
+            )
+            target = project / "tests" / "ack" / "check_service_worktree.py"
+            target.parent.mkdir(parents=True)
+            target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            target.chmod(target.stat().st_mode | 0o111)
+
+            tasks_result = subprocess.run(
+                [
+                    sys.executable,
+                    str(SCRIPTS_DIR / "validate_tasks.py"),
+                    str(tasks_path),
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            knowledge_result = subprocess.run(
+                [
+                    sys.executable,
+                    str(SCRIPTS_DIR / "validate_knowledge.py"),
+                    str(knowledge_path),
+                    "--tasks",
+                    str(tasks_path),
+                    "--project-root",
+                    str(project),
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+        self.assertEqual(tasks_result.returncode, 0, tasks_result.stderr)
+        self.assertEqual(
+            knowledge_result.returncode,
+            0,
+            knowledge_result.stderr,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+class AckSkillContentTests(unittest.TestCase):
+    def test_ack_skill_owns_resources_without_modifying_agent_instructions(self) -> None:
+        content = (REPO_ROOT / "skills" / "ack" / "SKILL.md").read_text(encoding="utf-8")
+
+        for expected in (
+            "skiff init ack --project <project-root>",
+            "docs/ack/project.md",
+            "docs/ack/tasks.yaml",
+            "docs/ack/knowledge.yaml",
+            "docs/ack/delivery.yaml",
+            "tasks: []",
+            "validate_tasks.py",
+            "validate_knowledge.py",
+            "validate_delivery.py",
+            "select_knowledge.py",
+            "references/kickoff.md",
+            "不要修改项目的 `AGENTS.md`",
+            "当前会话担任 Coordinator",
+        ):
+            self.assertIn(expected, content)
+
+    def test_ack_skill_is_explicit_only(self) -> None:
+        metadata = (REPO_ROOT / "skills" / "ack" / "agents" / "openai.yaml").read_text(
+            encoding="utf-8"
+        )
+
+        self.assertIn('display_name: "ACK"', metadata)
+        self.assertIn("allow_implicit_invocation: false", metadata)
+
+    def test_model_routing_is_fingerprint_bound_and_does_not_trust_receipt_reuse(self) -> None:
+        content = (
+            REPO_ROOT / "skills" / "ack" / "references" / "model-routing.md"
+        ).read_text(encoding="utf-8")
+
+        self.assertIn("--expected-launch-fingerprint", content)
+        self.assertIn("allowlist-v1", content)
+        self.assertIn("禁止根据持久化 receipt 自动复用", content)
+        self.assertIn("launcher 身份证明", content)
+
+    def test_ack_knowledge_resources_and_version_are_present(self) -> None:
+        ack_dir = REPO_ROOT / "skills" / "ack"
+
+        for relative_path in (
+            "templates/knowledge.template.yaml",
+            "templates/knowledge.schema.json",
+            "examples/knowledge.example.yaml",
+            "scripts/validate_knowledge.py",
+            "scripts/select_knowledge.py",
+            "scripts/run_verification.py",
+            "scripts/worker_profiles.py",
+            "scripts/launch_worker.py",
+            "templates/delivery.template.yaml",
+            "templates/delivery.schema.json",
+            "examples/delivery.example.yaml",
+            "references/delivery.md",
+            "references/delivery-routing.md",
+        ):
+            self.assertTrue((ack_dir / relative_path).is_file(), relative_path)
+        self.assertEqual((ack_dir / "VERSION").read_text(encoding="utf-8").strip(), "0.12.0")
+        self.assertIn(
+            'ackVersion: "<接入时的 ack skill 版本>"',
+            (ack_dir / "templates" / "tasks.template.yaml").read_text(
+                encoding="utf-8"
+            ),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,591 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import yaml
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+RUNNER = REPO_ROOT / "skills" / "ack" / "scripts" / "run_verification.py"
+sys.path.insert(0, str(RUNNER.parent))
+RUNNER_SPEC = importlib.util.spec_from_file_location("ack_run_verification", RUNNER)
+assert RUNNER_SPEC is not None and RUNNER_SPEC.loader is not None
+RUNNER_MODULE = importlib.util.module_from_spec(RUNNER_SPEC)
+RUNNER_SPEC.loader.exec_module(RUNNER_MODULE)
+
+
+def knowledge_with_target(path: str, args: list[str]) -> dict:
+    return {
+        "version": 1,
+        "updatedAt": "2026-07-31T12:00:00+08:00",
+        "project": {"name": "demo"},
+        "verificationRegistry": {
+            "reviewed-check": {
+                "path": path,
+                "args": args,
+            }
+        },
+        "entries": [],
+    }
+
+
+class AckVerificationRunnerTests(unittest.TestCase):
+    def run_check(
+        self,
+        project: Path,
+        knowledge: dict,
+    ) -> subprocess.CompletedProcess[str]:
+        knowledge_path = project / "docs" / "ack" / "knowledge.yaml"
+        knowledge_path.parent.mkdir(parents=True, exist_ok=True)
+        knowledge_path.write_text(
+            yaml.safe_dump(knowledge, allow_unicode=True),
+            encoding="utf-8",
+        )
+        return subprocess.run(
+            [
+                sys.executable,
+                str(RUNNER),
+                str(knowledge_path),
+                "reviewed-check",
+                "--project-root",
+                str(project),
+            ],
+            cwd=REPO_ROOT,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+    def test_executes_reviewed_target_with_structured_args(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            target = project / "checks" / "write-marker"
+            target.parent.mkdir(parents=True)
+            target.write_text(
+                "#!/bin/sh\nprintf 'passed' > \"$1\"\n",
+                encoding="utf-8",
+            )
+            target.chmod(target.stat().st_mode | 0o111)
+
+            result = self.run_check(
+                project,
+                knowledge_with_target(
+                    "checks/write-marker",
+                    ["verification-marker.txt"],
+                ),
+            )
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertEqual(
+                (project / "verification-marker.txt").read_text(encoding="utf-8"),
+                "passed",
+            )
+
+    def test_exposes_project_rooted_execution_contract(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            target = project / "checks" / "show-context"
+            target.parent.mkdir(parents=True)
+            target.write_text(
+                "#!/bin/sh\n"
+                "printf '%s\\n%s\\n%s\\n%s\\n' "
+                '"$PWD" "$ACK_PROJECT_ROOT" "$ACK_VERIFICATION_REF" '
+                '"$ACK_VERIFICATION_PATH" > "$1"\n',
+                encoding="utf-8",
+            )
+            target.chmod(target.stat().st_mode | 0o111)
+
+            result = self.run_check(
+                project,
+                knowledge_with_target(
+                    "checks/show-context",
+                    ["verification-context.txt"],
+                ),
+            )
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            context = (
+                (project / "verification-context.txt")
+                .read_text(encoding="utf-8")
+                .splitlines()
+            )
+            self.assertEqual(context[0], str(project))
+            self.assertRegex(context[1], r"^/(?:proc/self|dev)/fd/[0-9]+$")
+            self.assertEqual(context[2:], ["reviewed-check", "checks/show-context"])
+
+    def test_rejects_missing_or_non_executable_target(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            project.mkdir()
+
+            missing = self.run_check(
+                project,
+                knowledge_with_target("checks/missing", []),
+            )
+            self.assertEqual(missing.returncode, 1)
+            self.assertIn("不存在", missing.stderr)
+
+            target = project / "checks" / "not-executable"
+            target.parent.mkdir(parents=True)
+            target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            target.chmod(target.stat().st_mode & ~0o111)
+            not_executable = self.run_check(
+                project,
+                knowledge_with_target("checks/not-executable", []),
+            )
+
+            self.assertEqual(not_executable.returncode, 1)
+            self.assertIn("不可执行", not_executable.stderr)
+
+    def test_rejects_project_root_that_is_wider_than_knowledge_project(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base = Path(temp_dir)
+            project = base / "project"
+            outside = base / "outside"
+            outside.mkdir()
+            target = outside / "unsafe"
+            target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            target.chmod(target.stat().st_mode | 0o111)
+            knowledge_path = project / "docs" / "ack" / "knowledge.yaml"
+            knowledge_path.parent.mkdir(parents=True)
+            knowledge_path.write_text(
+                yaml.safe_dump(
+                    knowledge_with_target("outside/unsafe", []),
+                    allow_unicode=True,
+                ),
+                encoding="utf-8",
+            )
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(RUNNER),
+                    str(knowledge_path),
+                    "reviewed-check",
+                    "--project-root",
+                    str(base),
+                ],
+                cwd=REPO_ROOT,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 2)
+            self.assertIn("推断的项目根目录", result.stderr)
+
+    def test_rejects_duplicate_registry_ids_before_execution(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            checks = project / "checks"
+            checks.mkdir(parents=True)
+            marker = project / "unsafe-marker"
+            for name in ("safe", "unsafe"):
+                target = checks / name
+                target.write_text(
+                    f"#!/bin/sh\nprintf '{name}' > {marker}\n",
+                    encoding="utf-8",
+                )
+                target.chmod(target.stat().st_mode | 0o111)
+            knowledge_path = project / "docs" / "ack" / "knowledge.yaml"
+            knowledge_path.parent.mkdir(parents=True)
+            knowledge_path.write_text(
+                """\
+version: 1
+updatedAt: "2026-07-31T12:00:00+08:00"
+project:
+  name: demo
+verificationRegistry:
+  reviewed-check:
+    path: checks/safe
+    args: []
+  reviewed-check:
+    path: checks/unsafe
+    args: []
+entries: []
+""",
+                encoding="utf-8",
+            )
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(RUNNER),
+                    str(knowledge_path),
+                    "reviewed-check",
+                    "--project-root",
+                    str(project),
+                ],
+                cwd=REPO_ROOT,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("duplicate key", result.stderr)
+            self.assertFalse(marker.exists())
+
+    @unittest.skipUnless(hasattr(os, "symlink"), "requires symlink support")
+    def test_rejects_non_authoritative_knowledge_files(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base = Path(temp_dir)
+            project = base / "project"
+            ack_dir = project / "docs" / "ack"
+            ack_dir.mkdir(parents=True)
+            document = yaml.safe_dump(
+                knowledge_with_target("checks/reviewed", []),
+                allow_unicode=True,
+            )
+
+            for label, knowledge_path in (
+                ("external", base / "attacker-knowledge.yaml"),
+                ("alternate", ack_dir / "alternate.yaml"),
+            ):
+                with self.subTest(label=label):
+                    knowledge_path.write_text(document, encoding="utf-8")
+                    result = subprocess.run(
+                        [
+                            sys.executable,
+                            str(RUNNER),
+                            str(knowledge_path),
+                            "reviewed-check",
+                            "--project-root",
+                            str(project),
+                        ],
+                        cwd=REPO_ROOT,
+                        text=True,
+                        capture_output=True,
+                        check=False,
+                    )
+                    self.assertEqual(result.returncode, 2)
+                    self.assertIn("权威知识库", result.stderr)
+
+            outside = base / "outside-knowledge.yaml"
+            outside.write_text(document, encoding="utf-8")
+            canonical = ack_dir / "knowledge.yaml"
+            canonical.symlink_to(outside)
+            symlinked = subprocess.run(
+                [
+                    sys.executable,
+                    str(RUNNER),
+                    str(canonical),
+                    "reviewed-check",
+                    "--project-root",
+                    str(project),
+                ],
+                cwd=REPO_ROOT,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+            self.assertEqual(symlinked.returncode, 2)
+            self.assertIn("路径包含软链接", symlinked.stderr)
+
+    def test_authoritative_knowledge_is_read_from_an_opened_snapshot(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base = Path(temp_dir)
+            project = base / "project"
+            canonical = project / "docs" / "ack" / "knowledge.yaml"
+            canonical.parent.mkdir(parents=True)
+            safe_document = knowledge_with_target("checks/safe", [])
+            forged_document = knowledge_with_target("checks/danger", [])
+            canonical.write_text(
+                yaml.safe_dump(safe_document, allow_unicode=True),
+                encoding="utf-8",
+            )
+            forged_path = base / "forged.yaml"
+            forged_path.write_text(
+                yaml.safe_dump(forged_document, allow_unicode=True),
+                encoding="utf-8",
+            )
+            original_reader = RUNNER_MODULE._read_stable_bytes
+
+            def swap_after_open(
+                source_fd: int,
+                *,
+                maximum: int,
+            ) -> tuple[bytes | None, str | None]:
+                canonical.unlink()
+                canonical.symlink_to(forged_path)
+                return original_reader(source_fd, maximum=maximum)
+
+            with mock.patch.object(
+                RUNNER_MODULE,
+                "_read_stable_bytes",
+                side_effect=swap_after_open,
+            ):
+                data, error = RUNNER_MODULE.load_authoritative_knowledge(project)
+
+            self.assertIsNone(error)
+            self.assertEqual(
+                data["verificationRegistry"]["reviewed-check"]["path"],
+                "checks/safe",
+            )
+
+    def test_authoritative_knowledge_rejects_same_inode_change_during_read(
+        self,
+    ) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            canonical = project / "docs" / "ack" / "knowledge.yaml"
+            canonical.parent.mkdir(parents=True)
+            canonical.write_text(
+                yaml.safe_dump(
+                    knowledge_with_target("checks/safe", []),
+                    allow_unicode=True,
+                ),
+                encoding="utf-8",
+            )
+            source_fd, error = RUNNER_MODULE._open_regular_beneath(
+                project,
+                "docs/ack/knowledge.yaml",
+                require_executable=False,
+            )
+            self.assertIsNone(error)
+            self.assertIsNotNone(source_fd)
+            assert source_fd is not None
+            original_read = os.read
+            changed = False
+
+            def mutate_during_read(
+                file_descriptor: int,
+                size: int,
+            ) -> bytes:
+                nonlocal changed
+                chunk = original_read(file_descriptor, size)
+                if not changed:
+                    changed = True
+                    canonical.write_text(
+                        yaml.safe_dump(
+                            knowledge_with_target("checks/danger", []),
+                            allow_unicode=True,
+                        ),
+                        encoding="utf-8",
+                    )
+                return chunk
+
+            try:
+                with mock.patch.object(
+                    RUNNER_MODULE.os,
+                    "read",
+                    side_effect=mutate_during_read,
+                ):
+                    content, read_error = RUNNER_MODULE._read_stable_bytes(
+                        source_fd,
+                        maximum=RUNNER_MODULE.MAX_KNOWLEDGE_BYTES,
+                    )
+            finally:
+                os.close(source_fd)
+
+            self.assertIsNone(content)
+            self.assertIn("读取期间发生变化", read_error)
+
+    @unittest.skipUnless(hasattr(os, "symlink"), "requires symlink support")
+    def test_rejects_target_that_resolves_outside_project(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base = Path(temp_dir)
+            project = base / "project"
+            outside = base / "outside"
+            project.mkdir()
+            outside.mkdir()
+            target = outside / "unsafe"
+            target.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
+            target.chmod(target.stat().st_mode | 0o111)
+            (project / "checks").symlink_to(outside, target_is_directory=True)
+
+            result = self.run_check(
+                project,
+                knowledge_with_target("checks/unsafe", []),
+            )
+
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("不能包含 symlink", result.stderr)
+
+    @unittest.skipUnless(
+        hasattr(os, "O_NOFOLLOW") and Path("/proc/self/fd").is_dir(),
+        "requires fd-based POSIX execution",
+    )
+    def test_opened_target_cannot_be_swapped_before_execution(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base = Path(temp_dir)
+            project = base / "project"
+            target = project / "checks" / "reviewed"
+            outside = base / "outside"
+            marker = project / "marker.txt"
+            target.parent.mkdir(parents=True)
+            target.write_text(
+                "#!/bin/sh\nprintf 'reviewed' > \"$1\"\n",
+                encoding="utf-8",
+            )
+            target.chmod(target.stat().st_mode | 0o111)
+            outside.write_text(
+                "#!/bin/sh\nprintf 'swapped' > \"$1\"\n",
+                encoding="utf-8",
+            )
+            outside.chmod(outside.stat().st_mode | 0o111)
+            data = knowledge_with_target("checks/reviewed", [str(marker)])
+
+            target_fd, target_args, error = RUNNER_MODULE.open_target(
+                data,
+                "reviewed-check",
+                project,
+            )
+            self.assertIsNone(error)
+            self.assertIsNotNone(target_fd)
+            self.assertIsNotNone(target_args)
+            assert target_fd is not None and target_args is not None
+            target.unlink()
+            target.symlink_to(outside)
+            executable = RUNNER_MODULE._fd_executable_path(target_fd)
+            self.assertIsNotNone(executable)
+            try:
+                completed = subprocess.run(
+                    [str(executable), *target_args],
+                    cwd=project,
+                    pass_fds=(target_fd,),
+                    check=False,
+                )
+            finally:
+                os.close(target_fd)
+
+            self.assertEqual(completed.returncode, 0)
+            self.assertEqual(marker.read_text(encoding="utf-8"), "reviewed")
+
+    @unittest.skipUnless(
+        hasattr(os, "O_NOFOLLOW") and Path("/proc/self/fd").is_dir(),
+        "requires fd-based POSIX execution",
+    )
+    def test_opened_target_snapshot_ignores_same_inode_rewrite(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            target = project / "checks" / "reviewed"
+            marker = project / "marker.txt"
+            target.parent.mkdir(parents=True)
+            target.write_text(
+                "#!/bin/sh\nprintf 'reviewed' > \"$1\"\n",
+                encoding="utf-8",
+            )
+            target.chmod(target.stat().st_mode | 0o111)
+            data = knowledge_with_target("checks/reviewed", [str(marker)])
+
+            target_fd, target_args, error = RUNNER_MODULE.open_target(
+                data,
+                "reviewed-check",
+                project,
+            )
+            self.assertIsNone(error)
+            self.assertIsNotNone(target_fd)
+            self.assertIsNotNone(target_args)
+            assert target_fd is not None and target_args is not None
+            target.write_text(
+                "#!/bin/sh\nprintf 'mutated' > \"$1\"\n",
+                encoding="utf-8",
+            )
+            target.chmod(target.stat().st_mode | 0o111)
+            executable = RUNNER_MODULE._fd_executable_path(target_fd)
+            self.assertIsNotNone(executable)
+            try:
+                completed = subprocess.run(
+                    [str(executable), *target_args],
+                    cwd=project,
+                    pass_fds=(target_fd,),
+                    check=False,
+                )
+            finally:
+                os.close(target_fd)
+
+            self.assertEqual(completed.returncode, 0)
+            self.assertEqual(marker.read_text(encoding="utf-8"), "reviewed")
+
+    @unittest.skipUnless(
+        hasattr(os, "O_NOFOLLOW") and Path("/proc/self/fd").is_dir(),
+        "requires fd-based POSIX execution",
+    )
+    def test_project_root_replacement_cannot_swap_target_or_cwd(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            base = Path(temp_dir)
+            project = base / "project"
+            original = base / "original-project"
+            target = project / "checks" / "reviewed"
+            target.parent.mkdir(parents=True)
+            target.write_text(
+                "#!/bin/sh\nprintf 'reviewed' > marker.txt\n",
+                encoding="utf-8",
+            )
+            target.chmod(target.stat().st_mode | 0o111)
+            knowledge_path = project / "docs" / "ack" / "knowledge.yaml"
+            knowledge_path.parent.mkdir(parents=True)
+            knowledge_path.write_text(
+                yaml.safe_dump(
+                    knowledge_with_target("checks/reviewed", []),
+                    allow_unicode=True,
+                ),
+                encoding="utf-8",
+            )
+            original_loader = RUNNER_MODULE.load_authoritative_knowledge
+
+            def replace_root_after_knowledge(
+                project_root: Path | int,
+            ) -> tuple[dict | None, str | None]:
+                data, error = original_loader(project_root)
+                project.rename(original)
+                replacement = project / "checks" / "reviewed"
+                replacement.parent.mkdir(parents=True)
+                replacement.write_text(
+                    "#!/bin/sh\nprintf 'swapped' > marker.txt\n",
+                    encoding="utf-8",
+                )
+                replacement.chmod(replacement.stat().st_mode | 0o111)
+                return data, error
+
+            with mock.patch.object(
+                RUNNER_MODULE,
+                "load_authoritative_knowledge",
+                side_effect=replace_root_after_knowledge,
+            ):
+                result = RUNNER_MODULE.main(
+                    [
+                        str(knowledge_path),
+                        "reviewed-check",
+                        "--project-root",
+                        str(project),
+                    ]
+                )
+
+            self.assertEqual(result, 0)
+            self.assertEqual(
+                (original / "marker.txt").read_text(encoding="utf-8"),
+                "reviewed",
+            )
+            self.assertFalse((project / "marker.txt").exists())
+
+    def test_rejects_oversized_verification_target_before_snapshot(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project = Path(temp_dir) / "project"
+            target = project / "checks" / "oversized"
+            target.parent.mkdir(parents=True)
+            with target.open("wb") as target_file:
+                target_file.truncate(RUNNER_MODULE.MAX_TARGET_BYTES + 1)
+            target.chmod(target.stat().st_mode | 0o111)
+
+            target_fd, target_args, error = RUNNER_MODULE.open_target(
+                knowledge_with_target("checks/oversized", []),
+                "reviewed-check",
+                project,
+            )
+
+            self.assertIsNone(target_fd)
+            self.assertIsNone(target_args)
+            self.assertIn("超过大小上限", error)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,895 @@
+from __future__ import annotations
+
+import copy
+import sys
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS_DIR = REPO_ROOT / "skills" / "ack" / "scripts"
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+import worker_profiles  # noqa: E402
+
+
+def valid_orchestration() -> dict:
+    return {
+        "profileVersion": 1,
+        "mode": "orca",
+        "allowedWorktrees": ["/repo/demo"],
+        "modelAllowlist": {
+            "codex": {
+                "developer": {
+                    "standard": ["gpt-safe-dev"],
+                    "strong": ["gpt-safe-strong"],
+                },
+                "test": {"standard": ["gpt-safe-test"]},
+            },
+            "cursor-agent": {
+                "developer": {"standard": ["cursor-auto"]},
+                "test": {"standard": ["cursor-auto"]},
+            },
+        },
+        "profiles": {
+            "codex-dev-standard": {
+                "role": "developer",
+                "cli": "codex",
+                "tier": "standard",
+                "model": "gpt-safe-dev",
+                "reasoningEffort": "medium",
+                "permissionMode": "workspace-write",
+            },
+            "codex-dev-strong": {
+                "role": "developer",
+                "cli": "codex",
+                "tier": "strong",
+                "model": "gpt-safe-strong",
+                "reasoningEffort": "high",
+                "permissionMode": "workspace-write",
+            },
+            "cursor-test-standard": {
+                "role": "test",
+                "cli": "cursor-agent",
+                "tier": "standard",
+                "model": "cursor-auto",
+                "reasoningEffort": None,
+                "permissionMode": "read-only",
+            },
+            "cursor-dev-standard": {
+                "role": "developer",
+                "cli": "cursor-agent",
+                "tier": "standard",
+                "model": "cursor-auto",
+                "reasoningEffort": None,
+                "permissionMode": "workspace-write",
+            },
+        },
+        "defaults": {
+            "developer": "codex-dev-standard",
+            "test": "cursor-test-standard",
+            "developerUpgraded": "codex-dev-strong",
+        },
+    }
+
+
+def valid_receipt(orchestration: dict | None = None) -> dict:
+    routing = orchestration or valid_orchestration()
+    profile_id = "codex-dev-standard"
+    profile = routing["profiles"][profile_id]
+    executable = "/usr/local/bin/codex"
+    worktree_path = "/repo/demo"
+    argv = worker_profiles.render_worker_argv(profile, executable, worktree_path)
+    launch_id = "a" * 64
+    requested = {
+        "cli": profile["cli"],
+        "tier": profile["tier"],
+        "model": profile["model"],
+        "reasoningEffort": profile["reasoningEffort"],
+        "permissionMode": profile["permissionMode"],
+        "executable": executable,
+        "executableDevice": 8,
+        "executableInode": 201,
+        "cliVersion": "codex 1.0.0",
+        "argv": argv,
+        "argvHash": worker_profiles.canonical_sha256(argv),
+        "environmentPolicy": "per-cli-allowlist-v1",
+    }
+    worktree = {
+        "path": worktree_path,
+        "device": 8,
+        "inode": 101,
+        "gitCommonDir": "/repo/demo/.git",
+        "gitCommonDevice": 8,
+        "gitCommonInode": 102,
+    }
+    receipt = {
+        "receiptVersion": 1,
+        "id": f"WR-{launch_id}",
+        "launchId": launch_id,
+        "profileId": profile_id,
+        "profileHash": worker_profiles.profile_hash(profile),
+        "launchFingerprint": worker_profiles.canonical_sha256(
+            {
+                "protocolVersion": 1,
+                "backend": "orca",
+                "profileId": profile_id,
+                "profileHash": worker_profiles.profile_hash(profile),
+                "createdFor": {
+                    "taskId": "TASK-001",
+                    "attemptId": "TASK-001-A1",
+                    "role": "developer",
+                },
+                "worktree": worktree,
+                "requested": requested,
+                "slot": 1,
+            }
+        ),
+        "slot": 1,
+        "createdFor": {
+            "taskId": "TASK-001",
+            "attemptId": "TASK-001-A1",
+            "role": "developer",
+        },
+        "worktree": worktree,
+        "requested": requested,
+        "binding": {
+            "orchestrator": "orca",
+            "runtimeId": "runtime-001",
+            "handle": "terminal-001",
+            "incarnationId": "incarnation-001",
+            "observedWorktreePath": worktree_path,
+            "connected": True,
+            "writable": True,
+            "boundAt": "2026-07-31T12:00:01+08:00",
+        },
+        "createdAt": "2026-07-31T12:00:00+08:00",
+        "receiptHash": "",
+    }
+    receipt["receiptHash"] = worker_profiles.receipt_hash(receipt)
+    return receipt
+
+
+class CanonicalHashTests(unittest.TestCase):
+    def test_hash_is_prefixed_order_independent_and_content_sensitive(self) -> None:
+        first = worker_profiles.canonical_sha256(
+            {"b": [2, 1], "a": {"enabled": True}}
+        )
+        reordered = worker_profiles.canonical_sha256(
+            {"a": {"enabled": True}, "b": [2, 1]}
+        )
+        changed = worker_profiles.canonical_sha256(
+            {"a": {"enabled": False}, "b": [2, 1]}
+        )
+
+        self.assertEqual(first, reordered)
+        self.assertNotEqual(first, changed)
+        self.assertRegex(first, r"^sha256:[0-9a-f]{64}$")
+
+    def test_hash_rejects_non_json_and_non_finite_values(self) -> None:
+        with self.assertRaises(ValueError):
+            worker_profiles.canonical_sha256({"bad": object()})
+        with self.assertRaises(ValueError):
+            worker_profiles.canonical_sha256({"bad": float("nan")})
+        cyclic: list = []
+        cyclic.append(cyclic)
+        with self.assertRaises(ValueError):
+            worker_profiles.canonical_sha256(cyclic)
+
+    def test_profile_hash_rejects_invalid_profile(self) -> None:
+        profile = valid_orchestration()["profiles"]["codex-dev-standard"]
+        profile["command"] = "codex; touch forged"
+
+        with self.assertRaises(ValueError):
+            worker_profiles.profile_hash(profile)
+
+    def test_profile_hash_binds_profile_version(self) -> None:
+        profile = valid_orchestration()["profiles"]["codex-dev-standard"]
+
+        self.assertNotEqual(
+            worker_profiles.profile_hash(profile, profile_version=1),
+            worker_profiles.profile_hash(profile, profile_version=2),
+        )
+
+
+class ProfileValidationTests(unittest.TestCase):
+    def test_valid_orchestration_passes(self) -> None:
+        self.assertEqual(
+            worker_profiles.validate_orchestration(valid_orchestration()),
+            [],
+        )
+
+    def test_manual_mode_accepts_empty_structured_routing(self) -> None:
+        routing = {
+            "profileVersion": 1,
+            "mode": "manual",
+            "allowedWorktrees": [],
+            "modelAllowlist": {},
+            "profiles": {},
+            "defaults": {},
+        }
+
+        self.assertEqual(worker_profiles.validate_orchestration(routing), [])
+
+    def test_partial_empty_allowlist_nodes_are_rejected(self) -> None:
+        routing = {
+            "profileVersion": 1,
+            "mode": "manual",
+            "allowedWorktrees": [],
+            "modelAllowlist": {"codex": {}},
+            "profiles": {},
+            "defaults": {},
+        }
+
+        errors = worker_profiles.validate_orchestration(routing)
+
+        self.assertTrue(any("modelAllowlist.codex: must not be empty" in error for error in errors))
+
+    def test_profile_rejects_all_command_shaped_and_unknown_fields(self) -> None:
+        forbidden = ("command", "args", "env", "executable", "argv", "extraArgs")
+        for field in forbidden:
+            with self.subTest(field=field):
+                routing = valid_orchestration()
+                routing["profiles"]["codex-dev-standard"][field] = "forged"
+                errors = worker_profiles.validate_orchestration(routing)
+                self.assertTrue(any(f"unknown field '{field}'" in error for error in errors))
+
+    def test_routing_rejects_unknown_top_level_fields(self) -> None:
+        routing = valid_orchestration()
+        routing["command"] = "codex"
+
+        errors = worker_profiles.validate_orchestration(routing)
+
+        self.assertIn("project.orchestration: unknown field 'command'", errors)
+
+    def test_model_id_rejects_shell_and_whitespace_syntax(self) -> None:
+        for model in (
+            "safe;touch-forged",
+            "safe && forged",
+            "$(touch-forged)",
+            "`touch-forged`",
+            "safe\nforged",
+            "--dangerously-bypass-approvals-and-sandbox",
+        ):
+            with self.subTest(model=model):
+                routing = valid_orchestration()
+                routing["profiles"]["codex-dev-standard"]["model"] = model
+                errors = worker_profiles.validate_orchestration(routing)
+                self.assertTrue(any("safe model ID" in error for error in errors))
+
+    def test_only_safe_permission_modes_are_accepted(self) -> None:
+        for permission in (
+            "danger-full-access",
+            "full-access",
+            "yolo",
+            "bypass",
+            "never",
+        ):
+            with self.subTest(permission=permission):
+                routing = valid_orchestration()
+                routing["profiles"]["codex-dev-standard"][
+                    "permissionMode"
+                ] = permission
+                errors = worker_profiles.validate_orchestration(routing)
+                self.assertTrue(any("read-only/workspace-write" in error for error in errors))
+
+    def test_reasoning_effort_is_required_for_codex_and_null_for_cursor(self) -> None:
+        codex = valid_orchestration()
+        codex["profiles"]["codex-dev-standard"]["reasoningEffort"] = None
+        cursor = valid_orchestration()
+        cursor["profiles"]["cursor-test-standard"]["reasoningEffort"] = "low"
+
+        codex_errors = worker_profiles.validate_orchestration(codex)
+        cursor_errors = worker_profiles.validate_orchestration(cursor)
+
+        self.assertTrue(any("Codex requires" in error for error in codex_errors))
+        self.assertTrue(any("Cursor requires null" in error for error in cursor_errors))
+
+    def test_test_cannot_use_strong_tier(self) -> None:
+        routing = valid_orchestration()
+        profile = routing["profiles"]["cursor-test-standard"]
+        profile["tier"] = "strong"
+        routing["modelAllowlist"]["cursor-agent"]["test"]["strong"] = [
+            "cursor-auto"
+        ]
+
+        errors = worker_profiles.validate_orchestration(routing)
+
+        self.assertTrue(any("Test may only use standard" in error for error in errors))
+        self.assertTrue(any("Test cannot define a strong allowlist" in error for error in errors))
+
+    def test_profile_model_must_match_exact_cli_role_tier_allowlist(self) -> None:
+        routing = valid_orchestration()
+        routing["profiles"]["codex-dev-standard"]["model"] = "other-safe-model"
+
+        errors = worker_profiles.validate_orchestration(routing)
+
+        self.assertTrue(any("is not allowed for its cli/role/tier" in error for error in errors))
+
+    def test_defaults_require_matching_role_and_standard_tier(self) -> None:
+        wrong_role = valid_orchestration()
+        wrong_role["defaults"]["test"] = "codex-dev-standard"
+        strong_default = valid_orchestration()
+        strong_default["defaults"]["developer"] = "codex-dev-strong"
+
+        role_errors = worker_profiles.validate_orchestration(wrong_role)
+        tier_errors = worker_profiles.validate_orchestration(strong_default)
+
+        self.assertTrue(any("profile role must be test" in error for error in role_errors))
+        self.assertTrue(any("default profile must use standard" in error for error in tier_errors))
+
+    def test_developer_upgraded_default_requires_developer_strong(self) -> None:
+        valid = valid_orchestration()
+        wrong_tier = valid_orchestration()
+        wrong_tier["defaults"]["developerUpgraded"] = "codex-dev-standard"
+        wrong_role = valid_orchestration()
+        wrong_role["defaults"]["developerUpgraded"] = "cursor-test-standard"
+
+        self.assertEqual(worker_profiles.validate_orchestration(valid), [])
+        tier_errors = worker_profiles.validate_orchestration(wrong_tier)
+        role_errors = worker_profiles.validate_orchestration(wrong_role)
+        self.assertTrue(any("must use strong tier" in error for error in tier_errors))
+        self.assertTrue(any("profile role must be developer" in error for error in role_errors))
+
+    def test_malformed_scalar_types_return_errors_instead_of_raising(self) -> None:
+        for field in ("role", "cli", "tier", "reasoningEffort", "permissionMode"):
+            with self.subTest(profile_field=field):
+                profile = valid_orchestration()["profiles"]["codex-dev-standard"]
+                profile[field] = []
+                self.assertTrue(worker_profiles.validate_profile(profile))
+
+        routing = valid_orchestration()
+        routing["mode"] = []
+        self.assertTrue(worker_profiles.validate_orchestration(routing))
+
+        receipt = valid_receipt()
+        receipt["profileId"] = []
+        receipt["requested"]["cli"] = []
+        receipt["requested"]["tier"] = []
+        receipt["requested"]["permissionMode"] = []
+        receipt["receiptHash"] = worker_profiles.receipt_hash(receipt)
+        self.assertTrue(worker_profiles.validate_worker_receipt(receipt))
+        self.assertTrue(
+            worker_profiles.validate_worker_receipt(receipt, orchestration=[])
+        )
+
+    def test_orca_requires_defaults_profiles_and_allowed_worktree(self) -> None:
+        routing = valid_orchestration()
+        routing["allowedWorktrees"] = []
+        routing["profiles"] = {}
+        routing["defaults"] = {}
+
+        errors = worker_profiles.validate_orchestration(routing)
+
+        self.assertTrue(any("requires at least one path" in error for error in errors))
+        self.assertTrue(any("Orca mode requires profiles" in error for error in errors))
+        self.assertTrue(any("missing role 'developer'" in error for error in errors))
+        self.assertTrue(any("missing role 'test'" in error for error in errors))
+
+
+class ArgvRendererTests(unittest.TestCase):
+    def test_codex_exact_safe_argv(self) -> None:
+        profile = valid_orchestration()["profiles"]["codex-dev-standard"]
+
+        argv = worker_profiles.render_worker_argv(
+            profile,
+            "/usr/local/bin/codex",
+            "/repo/demo",
+        )
+
+        self.assertEqual(
+            argv,
+            [
+                "/usr/local/bin/codex",
+                "--strict-config",
+                "--model",
+                "gpt-safe-dev",
+                "--config",
+                "model_reasoning_effort=medium",
+                "--sandbox",
+                "workspace-write",
+                "--ask-for-approval",
+                "never",
+                "--cd",
+                "/repo/demo",
+            ],
+        )
+
+    def test_cursor_read_only_exact_safe_argv(self) -> None:
+        profile = valid_orchestration()["profiles"]["cursor-test-standard"]
+
+        argv = worker_profiles.render_worker_argv(
+            profile,
+            "/usr/local/bin/cursor-agent",
+            "/repo/demo",
+        )
+
+        self.assertEqual(
+            argv,
+            [
+                "/usr/local/bin/cursor-agent",
+                "--model",
+                "cursor-auto",
+                "--mode",
+                "plan",
+                "--sandbox",
+                "enabled",
+                "--workspace",
+                "/repo/demo",
+            ],
+        )
+
+    def test_cursor_workspace_write_adds_auto_review_without_yolo(self) -> None:
+        profile = valid_orchestration()["profiles"]["cursor-dev-standard"]
+
+        argv = worker_profiles.render_worker_argv(
+            profile,
+            "/usr/local/bin/cursor-agent",
+            "/repo/demo",
+        )
+
+        self.assertEqual(
+            argv,
+            [
+                "/usr/local/bin/cursor-agent",
+                "--model",
+                "cursor-auto",
+                "--auto-review",
+                "--sandbox",
+                "enabled",
+                "--workspace",
+                "/repo/demo",
+            ],
+        )
+        self.assertNotIn("--yolo", argv)
+        self.assertNotIn("--force", argv)
+
+    def test_renderer_rejects_wrong_executable_or_unsafe_worktree(self) -> None:
+        profile = valid_orchestration()["profiles"]["codex-dev-standard"]
+
+        with self.assertRaises(ValueError):
+            worker_profiles.render_worker_argv(
+                profile,
+                "/tmp/cursor-agent",
+                "/repo/demo",
+            )
+        with self.assertRaises(ValueError):
+            worker_profiles.render_worker_argv(
+                profile,
+                "/usr/local/bin/codex",
+                "/repo/demo/../outside",
+            )
+        for worktree in ("/repo/./demo", "/repo/demo/", "//repo/demo"):
+            with self.subTest(worktree=worktree), self.assertRaises(ValueError):
+                worker_profiles.render_worker_argv(
+                    profile,
+                    "/usr/local/bin/codex",
+                    worktree,
+                )
+
+
+class ReceiptValidationTests(unittest.TestCase):
+    def test_valid_receipt_is_bound_to_profile_and_routing(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+
+        self.assertEqual(
+            worker_profiles.validate_worker_receipt(
+                receipt,
+                orchestration=routing,
+                task_ids={"TASK-001"},
+            ),
+            [],
+        )
+        self.assertEqual(receipt["receiptHash"], worker_profiles.receipt_hash(receipt))
+
+    def test_receipt_rejects_unknown_fields_at_every_strict_level(self) -> None:
+        cases = (
+            ((), "command"),
+            (("createdFor",), "command"),
+            (("worktree",), "command"),
+            (("requested",), "command"),
+            (("binding",), "command"),
+        )
+        for path, field in cases:
+            with self.subTest(path=path):
+                routing = valid_orchestration()
+                receipt = valid_receipt(routing)
+                target = receipt
+                for component in path:
+                    target = target[component]
+                target[field] = "forged"
+                receipt["receiptHash"] = worker_profiles.receipt_hash(receipt)
+
+                errors = worker_profiles.validate_worker_receipt(
+                    receipt,
+                    orchestration=routing,
+                    task_ids={"TASK-001"},
+                )
+
+                self.assertTrue(any("unknown field 'command'" in error for error in errors))
+
+    def test_receipt_rejects_profile_and_exact_argv_drift(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        receipt["requested"]["model"] = "gpt-safe-strong"
+        receipt["requested"]["argv"][3] = "gpt-safe-strong"
+        receipt["requested"]["argvHash"] = worker_profiles.canonical_sha256(
+            receipt["requested"]["argv"]
+        )
+        receipt["receiptHash"] = worker_profiles.receipt_hash(receipt)
+
+        errors = worker_profiles.validate_worker_receipt(
+            receipt,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        self.assertTrue(any("requested.model: does not match profile" in error for error in errors))
+        self.assertTrue(
+            any(
+                "requested.argv: does not match exact renderer" in error
+                for error in errors
+            )
+        )
+
+    def test_receipt_rejects_tampering_without_recomputed_hash(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        receipt["binding"]["handle"] = "forged-handle"
+
+        errors = worker_profiles.validate_worker_receipt(
+            receipt,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        self.assertTrue(any("receiptHash: does not match receipt" in error for error in errors))
+
+    def test_receipt_rejects_out_of_budget_attempt_empty_argv_and_id_drift(self) -> None:
+        routing = valid_orchestration()
+
+        attempt = valid_receipt(routing)
+        attempt["createdFor"]["attemptId"] = "TASK-001-A4"
+        attempt["receiptHash"] = worker_profiles.receipt_hash(attempt)
+        attempt_errors = worker_profiles.validate_worker_receipt(
+            attempt,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        empty_argv = valid_receipt(routing)
+        empty_argv["requested"]["argv"] = []
+        empty_argv["requested"]["argvHash"] = worker_profiles.canonical_sha256([])
+        empty_argv["receiptHash"] = worker_profiles.receipt_hash(empty_argv)
+        argv_errors = worker_profiles.validate_worker_receipt(
+            empty_argv,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        wrong_id = valid_receipt(routing)
+        wrong_id["id"] = "WR-" + "b" * 64
+        wrong_id["receiptHash"] = worker_profiles.receipt_hash(wrong_id)
+        id_errors = worker_profiles.validate_worker_receipt(
+            wrong_id,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        self.assertTrue(any("A1..A3" in error for error in attempt_errors))
+        self.assertTrue(any("at least 2 items" in error for error in argv_errors))
+        self.assertTrue(any("must equal 'WR-' + launchId" in error for error in id_errors))
+
+    def test_receipt_rejects_rehashed_launch_fingerprint_tampering(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        receipt["launchFingerprint"] = worker_profiles.canonical_sha256(
+            {"forged": True}
+        )
+        receipt["receiptHash"] = worker_profiles.receipt_hash(receipt)
+
+        errors = worker_profiles.validate_worker_receipt(
+            receipt,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        self.assertTrue(
+            any(
+                "launchFingerprint: does not match launch facts" in error
+                for error in errors
+            )
+        )
+
+    def test_receipt_slot_is_bounded_and_bound_into_launch_fingerprint(self) -> None:
+        routing = valid_orchestration()
+        invalid = valid_receipt(routing)
+        invalid["slot"] = 0
+        invalid["receiptHash"] = worker_profiles.receipt_hash(invalid)
+        invalid_errors = worker_profiles.validate_worker_receipt(
+            invalid,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        drifted = valid_receipt(routing)
+        drifted["slot"] = 2
+        drifted["receiptHash"] = worker_profiles.receipt_hash(drifted)
+        drifted_errors = worker_profiles.validate_worker_receipt(
+            drifted,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        self.assertTrue(any("slot: must be" in error for error in invalid_errors))
+        self.assertTrue(
+            any(
+                "launchFingerprint: does not match launch facts" in error
+                for error in drifted_errors
+            )
+        )
+
+    def test_receipt_with_non_json_data_returns_errors(self) -> None:
+        receipt = valid_receipt()
+        receipt["requested"]["argv"] = [object()]
+
+        errors = worker_profiles.validate_worker_receipt(receipt)
+
+        self.assertTrue(any("must contain canonical JSON data" in error for error in errors))
+
+    def test_receipt_rejects_wrong_worktree_task_and_binding(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        receipt["worktree"]["path"] = "/repo/other"
+        receipt["binding"]["observedWorktreePath"] = "/repo/elsewhere"
+        receipt["receiptHash"] = worker_profiles.receipt_hash(receipt)
+
+        errors = worker_profiles.validate_worker_receipt(
+            receipt,
+            orchestration=routing,
+            task_ids={"OTHER-TASK"},
+        )
+
+        self.assertTrue(any("unknown task 'TASK-001'" in error for error in errors))
+        self.assertTrue(any("is not in allowedWorktrees" in error for error in errors))
+        self.assertTrue(any("does not match worktree.path" in error for error in errors))
+
+    def test_receipt_requires_safe_environment_and_live_binding(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        receipt["requested"]["environmentPolicy"] = "inherit-all"
+        receipt["binding"]["connected"] = False
+        receipt["binding"]["writable"] = False
+        receipt["receiptHash"] = worker_profiles.receipt_hash(receipt)
+
+        errors = worker_profiles.validate_worker_receipt(
+            receipt,
+            orchestration=routing,
+            task_ids={"TASK-001"},
+        )
+
+        self.assertTrue(any("per-cli-allowlist-v1" in error for error in errors))
+        self.assertTrue(any("binding.connected: must be true" in error for error in errors))
+        self.assertTrue(any("binding.writable: must be true" in error for error in errors))
+
+    def test_receipt_list_rejects_duplicate_receipt_and_launch_ids(self) -> None:
+        routing = valid_orchestration()
+        first = valid_receipt(routing)
+        duplicate = copy.deepcopy(first)
+
+        errors = worker_profiles.validate_worker_receipts(
+            [first, duplicate],
+            routing,
+            task_ids={"TASK-001"},
+        )
+
+        self.assertTrue(any("duplicate receipt ID" in error for error in errors))
+        self.assertTrue(any("duplicate launch ID" in error for error in errors))
+
+    def test_document_requires_top_level_receipts_and_routing(self) -> None:
+        missing = {
+            "version": 1,
+            "project": {"name": "demo"},
+            "tasks": [],
+        }
+
+        errors = worker_profiles.validate_routing_document(missing)
+
+        self.assertEqual(errors, ["project.orchestration: is required"])
+
+    def test_valid_document_passes_and_manual_receipts_fail(self) -> None:
+        routing = valid_orchestration()
+        document = {
+            "version": 1,
+            "project": {"name": "demo", "orchestration": routing},
+            "workerReceipts": [valid_receipt(routing)],
+            "tasks": [{"id": "TASK-001", "title": "demo", "status": "open"}],
+        }
+        self.assertEqual(worker_profiles.validate_routing_document(document), [])
+
+        manual = {
+            "version": 1,
+            "project": {
+                "name": "demo",
+                "orchestration": {
+                    "profileVersion": 1,
+                    "mode": "manual",
+                    "allowedWorktrees": [],
+                    "modelAllowlist": {},
+                    "profiles": {},
+                    "defaults": {},
+                },
+            },
+            "workerReceipts": [valid_receipt(routing)],
+            "tasks": [{"id": "TASK-001", "title": "demo", "status": "open"}],
+        }
+        manual_errors = worker_profiles.validate_routing_document(manual)
+        self.assertTrue(
+            any("manual orchestration requires an empty list" in error for error in manual_errors)
+        )
+
+    def test_dispatch_receipt_allows_two_phase_for_exact_task_attempt_binding(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        role_dispatch = {
+            "profileId": receipt["profileId"],
+            "receiptId": receipt["id"],
+            "attemptId": "TASK-001-A1",
+            "taskId": None,
+            "dispatchId": None,
+        }
+        document = {
+            "version": 1,
+            "project": {"name": "demo", "orchestration": routing},
+            "workerReceipts": [receipt],
+            "tasks": [
+                {
+                    "id": "TASK-001",
+                    "title": "created for",
+                    "status": "dispatched",
+                    "dispatch": {"developer": role_dispatch},
+                },
+            ],
+        }
+
+        self.assertEqual(worker_profiles.validate_routing_document(document), [])
+        role_dispatch["taskId"] = "orca-task-002"
+        role_dispatch["dispatchId"] = "orca-dispatch-002"
+        self.assertEqual(worker_profiles.validate_routing_document(document), [])
+
+    def test_dispatch_rejects_unknown_or_mismatched_receipt(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        role_dispatch = {
+            "profileId": "codex-dev-strong",
+            "receiptId": receipt["id"],
+            "attemptId": "TASK-001-A1",
+            "taskId": None,
+            "dispatchId": None,
+        }
+        document = {
+            "version": 1,
+            "project": {"name": "demo", "orchestration": routing},
+            "workerReceipts": [receipt],
+            "tasks": [
+                {
+                    "id": "TASK-001",
+                    "title": "demo",
+                    "status": "open",
+                    "dispatch": {"developer": role_dispatch},
+                }
+            ],
+        }
+
+        errors = worker_profiles.validate_routing_document(document)
+        self.assertTrue(
+            any("profileId: does not match referenced receipt" in error for error in errors)
+        )
+        role_dispatch["receiptId"] = f"WR-{'b' * 64}"
+        errors = worker_profiles.validate_routing_document(document)
+        self.assertTrue(any("unknown receipt" in error for error in errors))
+
+    def test_dispatch_rejects_cross_task_role_and_attempt_receipts(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        link = {
+            "profileId": receipt["profileId"],
+            "receiptId": receipt["id"],
+            "attemptId": "TASK-001-A1",
+            "taskId": None,
+            "dispatchId": None,
+        }
+        document = {
+            "version": 1,
+            "project": {"name": "demo", "orchestration": routing},
+            "workerReceipts": [receipt],
+            "tasks": [
+                {"id": "TASK-001", "title": "receipt owner", "status": "open"},
+                {
+                    "id": "TASK-002",
+                    "title": "must not reuse receipt",
+                    "status": "dispatched",
+                    "dispatch": {"developer": link},
+                },
+            ],
+        }
+
+        errors = worker_profiles.validate_routing_document(document)
+        self.assertTrue(any("must be current ACK task 'TASK-002'" in error for error in errors))
+        self.assertTrue(any("must belong to current ACK task 'TASK-002'" in error for error in errors))
+
+        document["tasks"][1]["id"] = "TASK-001"
+        link["attemptId"] = "TASK-001-A2"
+        errors = worker_profiles.validate_routing_document(document)
+        self.assertTrue(any("does not match referenced receipt" in error for error in errors))
+
+        link["attemptId"] = "TASK-001-A1"
+        document["tasks"][1]["dispatch"] = {"test": link}
+        errors = worker_profiles.validate_routing_document(document)
+        self.assertTrue(any("referenced receipt role must be test" in error for error in errors))
+
+    def test_dispatch_attempt_presence_tracks_receipt_presence(self) -> None:
+        routing = valid_orchestration()
+        receipt = valid_receipt(routing)
+        link = {
+            "profileId": receipt["profileId"],
+            "receiptId": None,
+            "attemptId": "TASK-001-A1",
+            "taskId": None,
+            "dispatchId": None,
+        }
+        document = {
+            "version": 1,
+            "project": {"name": "demo", "orchestration": routing},
+            "workerReceipts": [receipt],
+            "tasks": [
+                {
+                    "id": "TASK-001",
+                    "title": "demo",
+                    "status": "open",
+                    "dispatch": {"developer": link},
+                }
+            ],
+        }
+
+        errors = worker_profiles.validate_routing_document(document)
+        self.assertTrue(any("must be null when receiptId is null" in error for error in errors))
+
+        link["receiptId"] = receipt["id"]
+        link["attemptId"] = None
+        errors = worker_profiles.validate_routing_document(document)
+        self.assertTrue(any("is required when receiptId is set" in error for error in errors))
+
+    def test_dispatch_requires_receipt_before_paired_runtime_ids(self) -> None:
+        routing = valid_orchestration()
+        document = {
+            "version": 1,
+            "project": {"name": "demo", "orchestration": routing},
+            "workerReceipts": [],
+            "tasks": [
+                {
+                    "id": "TASK-001",
+                    "title": "demo",
+                    "status": "dispatched",
+                    "dispatch": {
+                        "developer": {
+                            "profileId": "codex-dev-standard",
+                            "receiptId": None,
+                            "attemptId": None,
+                            "taskId": "orca-task-001",
+                            "dispatchId": None,
+                        }
+                    },
+                }
+            ],
+        }
+
+        errors = worker_profiles.validate_routing_document(document)
+
+        self.assertTrue(any("must both be null or both be set" in error for error in errors))
+        self.assertTrue(any("required before runtime dispatch IDs" in error for error in errors))
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS_DIR = REPO_ROOT / "skills" / "ack" / "scripts"
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+import validate_knowledge  # noqa: E402
+import validate_delivery  # noqa: E402
+import validate_tasks  # noqa: E402
+from yaml_subset import YamlSubsetError, load_yaml_subset  # noqa: E402
+
+
+class AckYamlSubsetTests(unittest.TestCase):
+    def test_real_templates_and_examples_parse_under_clean_python(self) -> None:
+        script = """
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path('skills/ack/scripts').resolve()))
+from yaml_subset import load_yaml_subset
+paths = (
+    Path('skills/ack/templates/tasks.template.yaml'),
+    Path('skills/ack/examples/tasks.example.yaml'),
+    Path('skills/ack/templates/knowledge.template.yaml'),
+    Path('skills/ack/examples/knowledge.example.yaml'),
+    Path('skills/ack/templates/delivery.template.yaml'),
+    Path('skills/ack/examples/delivery.example.yaml'),
+)
+for path in paths:
+    value = load_yaml_subset(path.read_text(encoding='utf-8'))
+    if not isinstance(value, dict):
+        raise SystemExit(f'{path}: top-level value is not a mapping')
+print('parsed=6')
+"""
+        result = subprocess.run(
+            [sys.executable, "-S", "-c", script],
+            cwd=REPO_ROOT,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(result.stdout.strip(), "parsed=6")
+
+    def test_tasks_validator_runs_without_site_packages(self) -> None:
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-S",
+                str(SCRIPTS_DIR / "validate_tasks.py"),
+                str(REPO_ROOT / "skills" / "ack" / "examples" / "tasks.example.yaml"),
+            ],
+            cwd=REPO_ROOT,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("任务板校验通过", result.stdout)
+
+    def test_delivery_validator_runs_without_site_packages(self) -> None:
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-S",
+                str(SCRIPTS_DIR / "validate_delivery.py"),
+                str(REPO_ROOT / "skills" / "ack" / "templates" / "delivery.template.yaml"),
+            ],
+            cwd=REPO_ROOT,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("交付契约校验通过", result.stdout)
+
+    def test_supported_subset_types_and_block_scalars(self) -> None:
+        document = load_yaml_subset(
+            """
+# comment
+root:
+  list:
+    - null
+    - true
+    - -2
+    - name: 'single quoted'
+      flags: [false, "double quoted", {count: 3}]
+  emptyList: []
+  emptyMap: {}
+  folded: >
+    first line
+    second line
+
+    next paragraph
+  literal: |
+    first line
+    second line
+"""
+        )
+
+        self.assertEqual(document["root"]["list"][:3], [None, True, -2])
+        self.assertEqual(
+            document["root"]["list"][3],
+            {
+                "name": "single quoted",
+                "flags": [False, "double quoted", {"count": 3}],
+            },
+        )
+        self.assertEqual(document["root"]["emptyList"], [])
+        self.assertEqual(document["root"]["emptyMap"], {})
+        self.assertEqual(
+            document["root"]["folded"],
+            "first line second line\nnext paragraph\n",
+        )
+        self.assertEqual(
+            document["root"]["literal"],
+            "first line\nsecond line\n",
+        )
+
+    def test_quoted_mapping_key_supports_yaml_single_quote_escape(self) -> None:
+        self.assertEqual(load_yaml_subset("'owner''s-key': value\n"), {"owner's-key": "value"})
+
+    def test_subset_rejects_duplicate_keys_at_any_depth(self) -> None:
+        invalid_documents = (
+            "name: first\nname: second\n",
+            "outer:\n  name: first\n  name: second\n",
+            "outer: {name: first, name: second}\n",
+        )
+        for document in invalid_documents:
+            with self.subTest(document=document), self.assertRaises(YamlSubsetError):
+                load_yaml_subset(document)
+
+    def test_subset_rejects_unsupported_yaml_instead_of_guessing(self) -> None:
+        invalid_documents = (
+            "root: &node\n  value: 1\ncopy: *node\n",
+            "root: !custom value\n",
+            "root: {<<: {value: 1}}\n",
+            "---\nroot: value\n",
+            "root: >-\n  value\n",
+            "root: 1.25\n",
+            "root:\n\tchild: value\n",
+        )
+        for document in invalid_documents:
+            with self.subTest(document=document), self.assertRaises(YamlSubsetError):
+                load_yaml_subset(document)
+
+
+class AckDocumentLoaderTests(unittest.TestCase):
+    def test_tasks_yaml_loader_rejects_duplicate_keys_with_pyyaml(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            path = Path(temp_dir) / "tasks.yaml"
+            path.write_text("version: 1\nversion: 2\n", encoding="utf-8")
+
+            with self.assertRaises(SystemExit) as raised:
+                validate_tasks.load_document(path)
+
+        self.assertEqual(raised.exception.code, 1)
+
+    def test_knowledge_yaml_loader_rejects_alias_graphs(self) -> None:
+        with self.assertRaises(SystemExit) as raised:
+            validate_knowledge.load_yaml_text(
+                "root: &root\n  child: *root\n",
+                "知识库",
+            )
+
+        self.assertEqual(raised.exception.code, 1)
+
+    def test_tasks_json_loader_rejects_duplicate_keys(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            path = Path(temp_dir) / "tasks.json"
+            path.write_text('{"version": 1, "version": 2}', encoding="utf-8")
+
+            with self.assertRaises(SystemExit) as raised:
+                validate_tasks.load_document(path)
+
+        self.assertEqual(raised.exception.code, 1)
+
+    def test_knowledge_json_loader_rejects_nested_duplicate_keys(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            path = Path(temp_dir) / "knowledge.json"
+            path.write_text(
+                '{"project": {"name": "first", "name": "second"}}',
+                encoding="utf-8",
+            )
+
+            with self.assertRaises(SystemExit) as raised:
+                validate_knowledge.load_yaml(path, "知识库")
+
+        self.assertEqual(raised.exception.code, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from skiff import catalog
+from skiff.catalog import catalog_checkout_path, catalog_repo
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def write_skill(root: Path, name: str) -> Path:
+    skill = root / name
+    skill.mkdir(parents=True)
+    skill.joinpath("SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: >-\n"
+        f"  Test {name} skill.\n---\n\n# {name}\n",
+        encoding="utf-8",
+    )
+    return skill
+
+
+class CatalogCollectionTests(unittest.TestCase):
+    def test_load_catalog_falls_back_to_legacy_registry_file(self) -> None:
+        legacy = self.home / "legacy-registry.yaml"
+        legacy.write_text("legacy:\n  repo: https://example.test/legacy.git\n")
+        with (
+            patch.object(catalog, "CATALOG_FILE", self.home / "missing-catalog.yaml"),
+            patch.object(catalog, "LEGACY_REGISTRY_FILE", legacy),
+        ):
+            self.assertIn("legacy", catalog.load_catalog())
+
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.home = Path(self.temp_dir.name)
+        self.skills_home = self.home / ".skills"
+        (self.skills_home / "skills").mkdir(parents=True)
+
+        self.upstream = self.home / "upstream"
+        self.first = write_skill(self.upstream / "skills", "first-skill")
+        self.second = write_skill(self.upstream / "skills", "second-skill")
+        subprocess.run(
+            ["git", "init", "-b", "main", str(self.upstream)],
+            check=True,
+            capture_output=True,
+        )
+        subprocess.run(["git", "-C", str(self.upstream), "add", "."], check=True)
+        subprocess.run(
+            [
+                "git",
+                "-C",
+                str(self.upstream),
+                "-c",
+                "user.name=Test",
+                "-c",
+                "user.email=test@example.com",
+                "commit",
+                "-m",
+                "initial",
+            ],
+            check=True,
+            capture_output=True,
+        )
+        self.skills_home.joinpath("catalog.yaml").write_text(
+            "test-pack:\n"
+            f"  repo: {self.upstream}\n"
+            "  ref: main\n"
+            "  path: skills\n",
+            encoding="utf-8",
+        )
+
+    def tearDown(self) -> None:
+        self.temp_dir.cleanup()
+
+    def run_skiff(self, *args: str) -> subprocess.CompletedProcess[str]:
+        env = os.environ.copy()
+        env["HOME"] = str(self.home)
+        env["PYTHONPATH"] = str(REPO_ROOT)
+        return subprocess.run(
+            [sys.executable, "-m", "skiff", *args],
+            cwd=REPO_ROOT,
+            env=env,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+    def test_catalog_repo_expands_home_relative_local_path(self) -> None:
+        with patch.dict(os.environ, {"HOME": str(self.home)}):
+            self.assertEqual(
+                catalog_repo({"repo": "~/.skills"}),
+                str(self.skills_home),
+            )
+            self.assertEqual(
+                catalog_checkout_path("skills", {"repo": "~/.skills"}),
+                self.skills_home.resolve(),
+            )
+
+    def test_add_collection_installs_every_discovered_skill(self) -> None:
+        result = self.run_skiff("add", "test-pack", "-g", "-a", "codex")
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        skill_dir = self.home / ".codex" / "skills"
+        self.assertTrue((skill_dir / "first-skill").is_symlink())
+        self.assertTrue((skill_dir / "first-skill" / "SKILL.md").is_file())
+        self.assertTrue((skill_dir / "second-skill").is_symlink())
+        self.assertTrue((skill_dir / "second-skill" / "SKILL.md").is_file())
+        self.assertFalse((skill_dir / "test-pack").exists())
+
+    def test_add_qualified_collection_skill_installs_only_that_skill(self) -> None:
+        result = self.run_skiff("add", "test-pack/second-skill", "-g", "-a", "codex")
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        skill_dir = self.home / ".codex" / "skills"
+        self.assertFalse((skill_dir / "first-skill").exists())
+        self.assertTrue((skill_dir / "second-skill").is_symlink())
+        self.assertTrue((skill_dir / "second-skill" / "SKILL.md").is_file())
+
+    def test_add_collection_with_catalog_source_installs_all(self) -> None:
+        result = self.run_skiff(
+            "add",
+            "test-pack",
+            "--source",
+            "catalog",
+            "-g",
+            "-a",
+            "codex",
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        skill_dir = self.home / ".codex" / "skills"
+        self.assertTrue((skill_dir / "first-skill").is_symlink())
+        self.assertTrue((skill_dir / "second-skill").is_symlink())
+
+    def test_legacy_registry_source_alias_still_installs(self) -> None:
+        result = self.run_skiff(
+            "add",
+            "test-pack",
+            "--source",
+            "registry",
+            "-g",
+            "-a",
+            "codex",
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue(
+            (self.home / ".codex" / "skills" / "first-skill").is_symlink()
+        )
+
+    def test_project_add_records_collection_for_sync(self) -> None:
+        project = self.home / "project"
+        project.mkdir()
+
+        added = self.run_skiff(
+            "add",
+            "test-pack/first-skill",
+            "--project",
+            str(project),
+            "-a",
+            "codex",
+        )
+        link = project / ".agents" / "skills" / "first-skill"
+        link.unlink()
+        shutil.rmtree(self.home / ".local" / "share" / "skills" / "externals")
+        synced = self.run_skiff(
+            "sync",
+            "--project",
+            str(project),
+            "-a",
+            "codex",
+        )
+
+        self.assertEqual(added.returncode, 0, added.stderr)
+        self.assertIn('source: "catalog:test-pack"', project.joinpath(".skills.yaml").read_text())
+        self.assertEqual(synced.returncode, 0, synced.stderr)
+        self.assertTrue(link.is_symlink())
+        self.assertTrue((link / "SKILL.md").is_file())
+
+    def test_collection_preflight_prevents_partial_install(self) -> None:
+        blocked = self.home / ".codex" / "skills" / "second-skill"
+        blocked.mkdir(parents=True)
+
+        result = self.run_skiff("add", "test-pack", "-g", "-a", "codex")
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertFalse((self.home / ".codex" / "skills" / "first-skill").exists())
+        self.assertTrue(blocked.is_dir())
+
+    def test_remove_collection_removes_all_child_links(self) -> None:
+        installed = self.run_skiff("add", "test-pack", "-g", "-a", "codex")
+        removed = self.run_skiff("remove", "test-pack", "-g", "-a", "codex")
+
+        self.assertEqual(installed.returncode, 0, installed.stderr)
+        self.assertEqual(removed.returncode, 0, removed.stderr)
+        skill_dir = self.home / ".codex" / "skills"
+        self.assertFalse((skill_dir / "first-skill").exists())
+        self.assertFalse((skill_dir / "second-skill").exists())
+
+    def test_status_expands_collection_children(self) -> None:
+        installed = self.run_skiff("add", "test-pack", "-g", "-a", "codex")
+        status = self.run_skiff("status", "-a", "codex")
+
+        self.assertEqual(installed.returncode, 0, installed.stderr)
+        self.assertEqual(status.returncode, 0, status.stderr)
+        self.assertIn("[catalog:test-pack] first-skill", status.stdout)
+        self.assertIn("[catalog:test-pack] second-skill", status.stdout)
+        self.assertNotIn("[catalog] test-pack\n  (未 fetch)", status.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from skiff import cli
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+class CreateWorkflowTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.home = Path(self.temp_dir.name)
+        self.skills_home = self.home / ".skills"
+        template = self.skills_home / "skills" / "_template"
+        template.mkdir(parents=True)
+        template.joinpath("SKILL.md").write_text(
+            "---\nname: skill-name\ndescription: >-\n"
+            "  简要描述 skill 做什么、何时触发。Include trigger keywords so agents can match automatically.\n"
+            "---\n\n# Skill 名称\n\n## 步骤\n\n1. 第一步\n",
+            encoding="utf-8",
+        )
+        template.joinpath("README.md").write_text(
+            "# skill-name\n\n"
+            "用一句话告诉使用者这个 skill 能解决什么问题。\n\n"
+            "给出用户可以直接说出的典型请求。\n\n"
+            "给出一条可以直接交给 Agent 的示例请求。\n",
+            encoding="utf-8",
+        )
+        project_skill = self.skills_home / "skills" / "skiff"
+        project_skill.mkdir()
+        project_skill.joinpath("SKILL.md").write_text(
+            "---\nname: skiff\ndescription: >-\n"
+            "  创建和维护自研 skill。用于创建、安装、反馈或更新 skill 时。\n"
+            "---\n\n# skiff\n\n## 步骤\n\n1. 维护 skill。\n",
+            encoding="utf-8",
+        )
+        project_skill.joinpath("README.md").write_text(
+            "# skiff\n\n供人类使用的 skiff 说明。\n",
+            encoding="utf-8",
+        )
+
+    def tearDown(self) -> None:
+        self.temp_dir.cleanup()
+
+    def run_skiff(self, *args: str) -> subprocess.CompletedProcess[str]:
+        env = os.environ.copy()
+        env["HOME"] = str(self.home)
+        env["PYTHONPATH"] = str(REPO_ROOT)
+        return subprocess.run(
+            [sys.executable, "-m", "skiff", *args],
+            cwd=REPO_ROOT,
+            env=env,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+    def test_setup_command_is_not_exposed(self) -> None:
+        help_result = self.run_skiff("--help")
+        setup_result = self.run_skiff("setup", str(self.skills_home))
+
+        self.assertEqual(help_result.returncode, 0, help_result.stderr)
+        self.assertNotIn("setup", help_result.stdout)
+        self.assertNotEqual(setup_result.returncode, 0)
+
+    def test_bootstrap_installs_project_skill_globally_for_all_agents(self) -> None:
+        first = self.run_skiff("bootstrap")
+        second = self.run_skiff("bootstrap")
+
+        self.assertEqual(first.returncode, 0, first.stderr)
+        self.assertEqual(second.returncode, 0, second.stderr)
+        expected = (self.skills_home / "skills" / "skiff").resolve()
+        for relative in (
+            ".cursor/skills/skiff",
+            ".claude/skills/skiff",
+            ".codex/skills/skiff",
+        ):
+            link = self.home / relative
+            self.assertTrue(link.is_symlink(), relative)
+            self.assertEqual(link.resolve(), expected)
+        self.assertIn("cursor", first.stdout)
+        self.assertIn("claude", first.stdout)
+        self.assertIn("codex", first.stdout)
+
+    def test_update_pulls_skills_home(self) -> None:
+        with (
+            patch.object(cli, "SKILLS_HOME", self.skills_home),
+            patch.object(cli, "ensure_skills_home"),
+            patch.object(cli.subprocess, "run") as run,
+        ):
+            cli.cmd_update(argparse.Namespace())
+
+        run.assert_called_once_with(
+            ["git", "-C", str(self.skills_home), "pull"],
+            check=True,
+        )
+
+    def test_create_writes_draft_and_brief_without_registering_owned_skill(self) -> None:
+        project = self.home / "project"
+        project.mkdir()
+
+        result = self.run_skiff(
+            "create",
+            "migration-review",
+            "--idea",
+            "检查数据库迁移",
+            "--from-project",
+            str(project),
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        draft = self.skills_home / ".drafts" / "migration-review"
+        self.assertTrue((draft / "SKILL.md").is_file())
+        self.assertEqual(
+            (draft / "README.md").read_text(encoding="utf-8").splitlines()[0],
+            "# migration-review",
+        )
+        brief = (draft / "brief.yaml").read_text(encoding="utf-8")
+        self.assertIn("idea: 检查数据库迁移", brief)
+        self.assertIn(f"source_project: {project.resolve()}", brief)
+        self.assertFalse((self.skills_home / "skills" / "migration-review").exists())
+        self.assertIn("请完善 skiff 草稿 migration-review", result.stdout)
+
+    def test_check_rejects_template_placeholders(self) -> None:
+        created = self.run_skiff("create", "migration-review", "--idea", "检查数据库迁移")
+        self.assertEqual(created.returncode, 0, created.stderr)
+
+        result = self.run_skiff("check", "migration-review")
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("模板占位", result.stderr)
+
+    def test_finalize_moves_valid_draft_and_removes_brief(self) -> None:
+        created = self.run_skiff("create", "migration-review", "--idea", "检查数据库迁移")
+        self.assertEqual(created.returncode, 0, created.stderr)
+        draft = self.skills_home / ".drafts" / "migration-review"
+        draft.joinpath("SKILL.md").write_text(
+            "---\nname: migration-review\ndescription: >-\n"
+            "  检查数据库迁移文件的安全性。用于用户修改数据库结构、迁移或回滚方案时。\n"
+            "---\n\n# 数据库迁移检查\n\n## 步骤\n\n1. 检查迁移与回滚路径。\n",
+            encoding="utf-8",
+        )
+        draft.joinpath("README.md").write_text(
+            "# migration-review\n\n"
+            "用于检查数据库迁移安全性。\n\n"
+            "## 使用示例\n\n请检查这次数据库迁移。\n",
+            encoding="utf-8",
+        )
+
+        result = self.run_skiff("finalize", "migration-review")
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        final = self.skills_home / "skills" / "migration-review"
+        self.assertTrue((final / "SKILL.md").is_file())
+        self.assertTrue((final / "README.md").is_file())
+        self.assertFalse((final / "brief.yaml").exists())
+        self.assertFalse(draft.exists())
+
+    def test_check_rejects_missing_local_reference(self) -> None:
+        draft = self.skills_home / ".drafts" / "reference-check"
+        draft.mkdir(parents=True)
+        draft.joinpath("SKILL.md").write_text(
+            "---\nname: reference-check\ndescription: >-\n"
+            "  检查本地参考资料。用于用户要求核对参考文档时。\n"
+            "---\n\n# 参考检查\n\n读取 [规范](references/rules.md)。\n",
+            encoding="utf-8",
+        )
+        draft.joinpath("README.md").write_text(
+            "# reference-check\n\n用于检查本地参考资料。\n",
+            encoding="utf-8",
+        )
+
+        result = self.run_skiff("check", "reference-check")
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("引用文件不存在", result.stderr)
+
+    def test_check_rejects_missing_readme(self) -> None:
+        draft = self.skills_home / ".drafts" / "missing-readme"
+        draft.mkdir(parents=True)
+        draft.joinpath("SKILL.md").write_text(
+            "---\nname: missing-readme\ndescription: >-\n"
+            "  检查 skill 是否包含人类使用说明。用于维护 skill 结构时。\n"
+            "---\n\n# README 检查\n\n1. 检查 README。\n",
+            encoding="utf-8",
+        )
+
+        result = self.run_skiff("check", "missing-readme")
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("缺少 README.md", result.stderr)
+
+    def test_finalize_does_not_overwrite_existing_owned_skill(self) -> None:
+        created = self.run_skiff("create", "collision-check", "--idea", "检查名称冲突")
+        self.assertEqual(created.returncode, 0, created.stderr)
+        final = self.skills_home / "skills" / "collision-check"
+        final.mkdir()
+        final.joinpath("marker").write_text("keep", encoding="utf-8")
+
+        result = self.run_skiff("finalize", "collision-check")
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertEqual(final.joinpath("marker").read_text(encoding="utf-8"), "keep")
+        self.assertTrue((self.skills_home / ".drafts" / "collision-check" / "brief.yaml").is_file())
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from skiff.project import normalize_skill_entry
+from skiff.sources import fetch_source
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def write_skill(root: Path, name: str) -> Path:
+    skill = root / name
+    skill.mkdir(parents=True)
+    skill.joinpath("SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: >-\n"
+        f"  测试 {name} skill。\n---\n\n# {name}\n",
+        encoding="utf-8",
+    )
+    return skill
+
+
+class CustomSourceTests(unittest.TestCase):
+    def test_legacy_manifest_sources_normalize_to_new_model(self) -> None:
+        self.assertEqual(
+            normalize_skill_entry({"name": "ack", "source": "owned"})["source"],
+            "builtin",
+        )
+        self.assertEqual(
+            normalize_skill_entry(
+                {"name": "think", "source": "registry", "registry": "waza"}
+            )["source"],
+            "catalog:waza",
+        )
+
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.home = Path(self.temp_dir.name)
+        self.skills_home = self.home / ".skills"
+        (self.skills_home / "skills").mkdir(parents=True)
+        (self.skills_home / "catalog.yaml").write_text("", encoding="utf-8")
+
+    def tearDown(self) -> None:
+        self.temp_dir.cleanup()
+
+    def run_skiff(self, *args: str) -> subprocess.CompletedProcess[str]:
+        env = os.environ.copy()
+        env["HOME"] = str(self.home)
+        env["PYTHONPATH"] = str(REPO_ROOT)
+        return subprocess.run(
+            [sys.executable, "-m", "skiff", *args],
+            cwd=REPO_ROOT,
+            env=env,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+    def test_local_source_lists_and_installs_qualified_skill(self) -> None:
+        company = self.home / "company"
+        expected = write_skill(company / "internal" / "skills", "code-review")
+
+        added = self.run_skiff(
+            "source",
+            "add",
+            "company",
+            "--local",
+            str(company),
+            "--skills-path",
+            "internal/skills",
+        )
+        listed = self.run_skiff("list", "--source", "company")
+        installed = self.run_skiff("add", "company/code-review", "-g", "-a", "codex")
+
+        self.assertEqual(added.returncode, 0, added.stderr)
+        self.assertEqual(listed.returncode, 0, listed.stderr)
+        self.assertIn("code-review", listed.stdout)
+        self.assertEqual(installed.returncode, 0, installed.stderr)
+        link = self.home / ".codex" / "skills" / "code-review"
+        self.assertTrue(link.is_symlink())
+        self.assertEqual(link.resolve(), expected.resolve())
+        config = self.home / ".config" / "skiff" / "config.yaml"
+        self.assertIn("company:", config.read_text(encoding="utf-8"))
+
+    def test_local_source_can_expose_a_single_skill(self) -> None:
+        source = self.home / "single-source"
+        source.mkdir()
+        source.joinpath("SKILL.md").write_text(
+            "---\nname: solo\ndescription: Test single source.\n---\n",
+            encoding="utf-8",
+        )
+        added = self.run_skiff(
+            "source",
+            "add",
+            "solo",
+            "--local",
+            str(source),
+            "--skills-path",
+            ".",
+        )
+        installed = self.run_skiff(
+            "add",
+            "solo",
+            "-g",
+            "-a",
+            "codex",
+        )
+
+        self.assertEqual(added.returncode, 0, added.stderr)
+        self.assertEqual(installed.returncode, 0, installed.stderr)
+        self.assertEqual(
+            (self.home / ".codex" / "skills" / "solo").resolve(),
+            source.resolve(),
+        )
+    def test_project_add_persists_resolved_source_in_manifest(self) -> None:
+        company = self.home / "company"
+        expected = write_skill(company / "skills", "code-review")
+        project = self.home / "project"
+        project.mkdir()
+        added = self.run_skiff("source", "add", "company", "--local", str(company))
+        self.assertEqual(added.returncode, 0, added.stderr)
+
+        result = self.run_skiff(
+            "add",
+            "company/code-review",
+            "--project",
+            str(project),
+            "-a",
+            "codex",
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        manifest = project.joinpath(".skills.yaml").read_text(encoding="utf-8")
+        self.assertIn('name: "code-review"', manifest)
+        self.assertIn("source: company", manifest)
+        self.assertEqual(
+            (project / ".agents" / "skills" / "code-review").resolve(),
+            expected.resolve(),
+        )
+
+    def test_project_add_updates_manifest_when_source_changes(self) -> None:
+        write_skill(self.skills_home / "skills", "code-review")
+        company = self.home / "company"
+        write_skill(company / "skills", "code-review")
+        project = self.home / "project"
+        project.mkdir()
+        project.joinpath(".skills.yaml").write_text(
+            "skills:\n  - code-review\n",
+            encoding="utf-8",
+        )
+        added = self.run_skiff("source", "add", "company", "--local", str(company))
+        self.assertEqual(added.returncode, 0, added.stderr)
+
+        result = self.run_skiff(
+            "add",
+            "company/code-review",
+            "--project",
+            str(project),
+            "-a",
+            "codex",
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        manifest = project.joinpath(".skills.yaml").read_text(encoding="utf-8")
+        self.assertIn("source: company", manifest)
+
+    def test_unqualified_duplicate_requires_explicit_source(self) -> None:
+        write_skill(self.skills_home / "skills", "code-review")
+        company = self.home / "company"
+        write_skill(company / "skills", "code-review")
+        added = self.run_skiff("source", "add", "company", "--local", str(company))
+        self.assertEqual(added.returncode, 0, added.stderr)
+
+        result = self.run_skiff("add", "code-review", "-g", "-a", "codex")
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("builtin/code-review", result.stderr)
+        self.assertIn("company/code-review", result.stderr)
+
+    def test_custom_source_namespace_is_not_shadowed_by_catalog_collection(self) -> None:
+        company = self.home / "company"
+        expected = write_skill(company / "skills", "code-review")
+        catalog_repo = self.home / "catalog-repo"
+        write_skill(catalog_repo / "skills", "other-skill")
+        self.skills_home.joinpath("catalog.yaml").write_text(
+            "company:\n"
+            f"  repo: {catalog_repo}\n"
+            "  ref: main\n"
+            "  path: skills\n",
+            encoding="utf-8",
+        )
+        added = self.run_skiff("source", "add", "company", "--local", str(company))
+
+        result = self.run_skiff(
+            "add",
+            "company/code-review",
+            "-g",
+            "-a",
+            "codex",
+        )
+
+        self.assertEqual(added.returncode, 0, added.stderr)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(
+            (self.home / ".codex" / "skills" / "code-review").resolve(),
+            expected.resolve(),
+        )
+
+    def test_sync_uses_manifest_source(self) -> None:
+        company = self.home / "company"
+        expected = write_skill(company / "skills", "code-review")
+        project = self.home / "project"
+        project.mkdir()
+        project.joinpath(".skills.yaml").write_text(
+            "skills:\n  - name: code-review\n    source: company\n"
+            "targets:\n  - codex\n",
+            encoding="utf-8",
+        )
+        added = self.run_skiff("source", "add", "company", "--local", str(company))
+        self.assertEqual(added.returncode, 0, added.stderr)
+
+        result = self.run_skiff("sync", "--project", str(project), "-a", "codex")
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        link = project / ".agents" / "skills" / "code-review"
+        self.assertEqual(link.resolve(), expected.resolve())
+
+    def test_sync_reports_missing_machine_source(self) -> None:
+        project = self.home / "project"
+        project.mkdir()
+        project.joinpath(".skills.yaml").write_text(
+            "skills:\n  - name: code-review\n    source: company\n",
+            encoding="utf-8",
+        )
+
+        result = self.run_skiff("sync", "--project", str(project), "-a", "codex")
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("本机尚未配置", result.stderr)
+        self.assertIn("skiff source add company", result.stderr)
+
+    def test_git_source_is_cloned_to_default_checkout(self) -> None:
+        upstream = self.home / "upstream"
+        write_skill(upstream / "skills", "release-check")
+        subprocess.run(["git", "init", "-b", "main", str(upstream)], check=True, capture_output=True)
+        subprocess.run(["git", "-C", str(upstream), "add", "."], check=True)
+        subprocess.run(
+            [
+                "git",
+                "-C",
+                str(upstream),
+                "-c",
+                "user.name=Test",
+                "-c",
+                "user.email=test@example.com",
+                "commit",
+                "-m",
+                "initial",
+            ],
+            check=True,
+            capture_output=True,
+        )
+
+        result = self.run_skiff("source", "add", "company", str(upstream))
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        checkout = self.home / ".local" / "share" / "skiff" / "sources" / "company"
+        self.assertTrue((checkout / ".git").is_dir())
+        self.assertTrue((checkout / "skills" / "release-check" / "SKILL.md").is_file())
+
+    def test_git_source_clone_is_shallow(self) -> None:
+        checkout = self.home / "checkout"
+        entry = {
+            "repo": "https://example.test/company-skills.git",
+            "ref": "main",
+            "checkout": str(checkout),
+        }
+
+        with patch("skiff.sources.subprocess.run") as run:
+            fetch_source("company", entry)
+
+        run.assert_called_once_with(
+            [
+                "git",
+                "clone",
+                "--depth",
+                "1",
+                "--branch",
+                "main",
+                "--",
+                "https://example.test/company-skills.git",
+                str(checkout),
+            ],
+            check=True,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+class InstallScriptTests(unittest.TestCase):
+    def test_install_bootstraps_skiff_skill_for_all_agents(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            home = Path(temp)
+            (home / ".skills").symlink_to(REPO_ROOT, target_is_directory=True)
+            env = os.environ.copy()
+            env["HOME"] = str(home)
+
+            result = subprocess.run(
+                ["bash", str(REPO_ROOT / "install.sh")],
+                cwd=REPO_ROOT,
+                env=env,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            for relative in (
+                ".cursor/skills/skiff",
+                ".claude/skills/skiff",
+                ".codex/skills/skiff",
+            ):
+                link = home / relative
+                self.assertTrue(link.is_symlink(), relative)
+                self.assertEqual(link.resolve(), (REPO_ROOT / "skills" / "skiff").resolve())
+            self.assertIn("已全局安装 builtin skiff skill", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+class ProjectSkillContentTests(unittest.TestCase):
+    def test_skiff_skill_documents_project_usage_and_feedback_loop(self) -> None:
+        content = (REPO_ROOT / "skills" / "skiff" / "SKILL.md").read_text(encoding="utf-8")
+
+        for expected in (
+            "skiff add <name>",
+            "问题或优化回流",
+            "实际结果",
+            "期望结果",
+            "skiff check <name>",
+            "~/.skills/skills/<name>/",
+            "第三方 skill",
+            "skiff init ack",
+            "显式调用全局 `/ack` skill",
+        ):
+            self.assertIn(expected, content)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,622 @@
+from __future__ import annotations
+
+import argparse
+import curses
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from skiff import cli
+from skiff import yaml_io
+from skiff.catalog import catalog_repo_path, catalog_skill_path
+from skiff.selector import SkillChoice, filter_choices, fit_to_width, select_skills
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+class SelectorTests(unittest.TestCase):
+    def test_fit_to_width_counts_cjk_as_two_columns(self) -> None:
+        self.assertEqual(fit_to_width("a中文b", 4), "a中")
+        self.assertEqual(fit_to_width("初始化 ACK", 8), "初始化 A")
+
+    def test_manifest_entry_targets_round_trip(self) -> None:
+        data = {
+            "skills": [
+                {
+                    "name": "catalog-one",
+                    "source": "registry",
+                    "targets": ["codex"],
+                }
+            ]
+        }
+
+        self.assertEqual(yaml_io.safe_load(yaml_io.safe_dump(data)), data)
+
+    def test_filter_matches_name_kind_and_description(self) -> None:
+        choices = [
+            SkillChoice("frontend-design", "catalog", "创建界面"),
+            SkillChoice(
+                "discussion-notes",
+                "builtin",
+                "维护讨论笔记",
+                readonly_status="全局: codex",
+            ),
+        ]
+
+        self.assertEqual([c.name for c in filter_choices(choices, "front")], ["frontend-design"])
+        self.assertEqual([c.name for c in filter_choices(choices, "builtin")], ["discussion-notes"])
+        self.assertEqual([c.name for c in filter_choices(choices, "界面")], ["frontend-design"])
+        self.assertEqual([c.name for c in filter_choices(choices, "codex")], ["discussion-notes"])
+
+    def test_selector_preserves_preselected_items(self) -> None:
+        choices = [
+            SkillChoice("already-there", "builtin", installed=True),
+            SkillChoice("new-skill", "catalog"),
+        ]
+        screen = Mock()
+        screen.getmaxyx.return_value = (24, 100)
+        screen.get_wch.return_value = "\n"
+
+        with patch.object(curses, "curs_set"):
+            selected = select_skills(
+                choices,
+                wrapper=lambda draw: draw(screen),
+            )
+
+        self.assertEqual(selected, {"already-there"})
+        rendered = [call.args[2] for call in screen.addnstr.call_args_list]
+        self.assertTrue(any("取消选择不卸载" in line for line in rendered))
+
+    def test_selector_renders_scope_and_readonly_global_status(self) -> None:
+        choices = [
+            SkillChoice(
+                "ack",
+                "builtin",
+                installed=False,
+                readonly_status="全局: cursor,claude,codex",
+            )
+        ]
+        screen = Mock()
+        screen.getmaxyx.return_value = (24, 120)
+        screen.get_wch.return_value = "\n"
+
+        with patch.object(curses, "curs_set"):
+            selected = select_skills(
+                choices,
+                scope_label="项目 /code/app（全局状态只读）",
+                wrapper=lambda draw: draw(screen),
+            )
+
+        rendered = [call.args[2] for call in screen.addnstr.call_args_list]
+        self.assertEqual(selected, set())
+        self.assertTrue(any("安装目标: 项目 /code/app" in line for line in rendered))
+        title = "".join(
+            call.args[2]
+            for call in screen.addnstr.call_args_list
+            if call.args[0] == 3
+        )
+        self.assertIn("[ ] ack", title)
+        self.assertIn("全局: cursor,claude,codex", title)
+        self.assertNotIn("初始化", title)
+
+    def test_selector_renders_description_on_indented_second_line(self) -> None:
+        choices = [
+            SkillChoice(
+                "ack",
+                "builtin",
+                description="初始化、检查并运行 ACK",
+                readonly_status="全局: codex",
+            )
+        ]
+        screen = Mock()
+        screen.getmaxyx.return_value = (24, 100)
+        screen.get_wch.return_value = "\n"
+
+        with patch.object(curses, "curs_set"):
+            select_skills(choices, wrapper=lambda draw: draw(screen))
+
+        title_calls = [
+            call for call in screen.addnstr.call_args_list if call.args[0] == 3
+        ]
+        description_call = next(
+            call for call in screen.addnstr.call_args_list if call.args[0] == 4
+        )
+        self.assertEqual(
+            "".join(call.args[2] for call in title_calls),
+            "[ ] ack  builtin  全局: codex",
+        )
+        self.assertEqual(description_call.args[2], "    初始化、检查并运行 ACK")
+        name_call = next(call for call in title_calls if call.args[2] == "ack")
+        self.assertTrue(name_call.args[4] & curses.A_BOLD)
+        self.assertTrue(description_call.args[4] & curses.A_DIM)
+
+    def test_repository_choice_toggles_all_child_skills(self) -> None:
+        choices = [
+            SkillChoice(
+                "waza",
+                "repository",
+                children=("waza/think", "waza/ui"),
+            ),
+            SkillChoice("waza/think", "catalog:waza", indent=1),
+            SkillChoice("waza/ui", "catalog:waza", indent=1),
+        ]
+        screen = Mock()
+        screen.getmaxyx.return_value = (24, 100)
+        screen.get_wch.side_effect = [" ", "\n"]
+
+        with patch.object(curses, "curs_set"):
+            selected = select_skills(choices, wrapper=lambda draw: draw(screen))
+
+        self.assertEqual(selected, {"waza/think", "waza/ui"})
+
+    def test_repository_choice_renders_partial_selection(self) -> None:
+        choices = [
+            SkillChoice(
+                "waza",
+                "repository",
+                children=("waza/think", "waza/ui"),
+            ),
+            SkillChoice("waza/think", "catalog:waza", installed=True, indent=1),
+            SkillChoice("waza/ui", "catalog:waza", indent=1),
+        ]
+        screen = Mock()
+        screen.getmaxyx.return_value = (24, 100)
+        screen.get_wch.return_value = "\n"
+
+        with patch.object(curses, "curs_set"):
+            select_skills(choices, wrapper=lambda draw: draw(screen))
+
+        first_row = "".join(
+            call.args[2]
+            for call in screen.addnstr.call_args_list
+            if call.args[0] == 3
+        )
+        self.assertIn("[-] waza", first_row)
+
+    def test_shared_repo_path_is_same_for_different_skill_entries(self) -> None:
+        first = {"repo": "https://example.test/skills.git", "ref": "main", "path": "a"}
+        second = {"repo": "https://example.test/skills.git", "ref": "main", "path": "b"}
+
+        self.assertEqual(catalog_repo_path(first), catalog_repo_path(second))
+
+    def test_catalog_skill_path_rejects_checkout_escape(self) -> None:
+        entry = {
+            "repo": "https://example.test/skills.git",
+            "ref": "main",
+            "path": "../../outside",
+        }
+
+        with self.assertRaisesRegex(SystemExit, "超出来源仓库"):
+            catalog_skill_path("unsafe-skill", entry)
+
+    def test_collection_discovery_ignores_symlinked_skill(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            checkout = root / "checkout"
+            collection = checkout / "skills"
+            outside = root / "outside"
+            collection.mkdir(parents=True)
+            outside.mkdir()
+            outside.joinpath("SKILL.md").write_text("---\n", encoding="utf-8")
+            collection.joinpath("escaped").symlink_to(outside, target_is_directory=True)
+            entry = {
+                "repo": "https://example.test/skills.git",
+                "ref": "main",
+                "path": "skills",
+            }
+
+            with patch("skiff.catalog.catalog_checkout_path", return_value=checkout):
+                from skiff.catalog import discover_catalog_skills
+
+                self.assertEqual(discover_catalog_skills("unsafe", entry), {})
+
+    def test_catalog_clone_is_shallow(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            checkout = root / "checkout"
+            skill_root = checkout / "skills"
+            entry = {
+                "repo": "https://example.test/skills.git",
+                "ref": "main",
+                "path": "skills",
+            }
+            with (
+                patch.object(cli, "catalog_skill_path", return_value=skill_root),
+                patch.object(cli, "catalog_checkout_path", return_value=checkout),
+                patch.object(
+                    cli,
+                    "discover_catalog_skills",
+                    side_effect=[{}, {"demo": skill_root / "demo"}],
+                ),
+                patch.object(cli.subprocess, "run") as run,
+            ):
+                cli._ensure_catalog_fetched("demo-pack", entry)
+
+        run.assert_called_once_with(
+            [
+                "git",
+                "clone",
+                "--depth",
+                "1",
+                "--branch",
+                "main",
+                "--",
+                "https://example.test/skills.git",
+                str(checkout),
+            ],
+            check=True,
+        )
+
+
+class SelectCommandTests(unittest.TestCase):
+    def test_non_tty_exits_with_add_guidance(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            home = Path(temp)
+            (home / ".skills" / "skills").mkdir(parents=True)
+            env = os.environ.copy()
+            env["HOME"] = str(home)
+            env["PYTHONPATH"] = str(REPO_ROOT)
+
+            result = subprocess.run(
+                [sys.executable, "-m", "skiff", "select"],
+                cwd=REPO_ROOT,
+                env=env,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("skiff add <name>", result.stderr)
+
+    def test_project_selection_installs_new_and_records_all_selected(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            project = Path(temp)
+            catalog = project / "catalog-one"
+            catalog.mkdir()
+            catalog.joinpath("SKILL.md").write_text("---\n", encoding="utf-8")
+            args = argparse.Namespace(
+                agents=[["codex"]],
+                global_scope=False,
+                project=str(project),
+                yes=False,
+            )
+            stdin = Mock()
+            stdout = Mock()
+            stdin.isatty.return_value = True
+            stdout.isatty.return_value = True
+            installed: list[str] = []
+            selected_choices: list[SkillChoice] = []
+            selected_scope: list[str] = []
+
+            def choose(
+                choices: list[SkillChoice],
+                *,
+                scope_label: str,
+            ) -> set[str]:
+                selected_choices.extend(choices)
+                selected_scope.append(scope_label)
+                return {"builtin-one", "catalog-one"}
+
+            with (
+                patch.object(cli.sys, "stdin", stdin),
+                patch.object(cli.sys, "stdout", stdout),
+                patch.object(cli, "ensure_skills_home"),
+                patch.object(cli, "list_builtin_skills", return_value=["builtin-one"]),
+                patch.object(cli, "skill_description", return_value="builtin"),
+                patch.object(
+                    cli,
+                    "load_catalog",
+                    return_value={
+                        "catalog-one": {
+                            "repo": "https://example.test/skills.git",
+                            "ref": "main",
+                            "path": "catalog-one",
+                        }
+                    },
+                ),
+                patch.object(cli, "_catalog_skill_names", return_value=["catalog-one"]),
+                patch.object(cli, "catalog_skill_path", return_value=catalog),
+                patch.object(cli, "_list_fully_installed_names", return_value=["builtin-one"]),
+                patch.object(
+                    cli,
+                    "_global_installation_note",
+                    return_value="全局: codex",
+                ),
+                patch.object(
+                    cli,
+                    "_is_fully_installed",
+                    side_effect=lambda name, expected, project_root, targets: name == "builtin-one",
+                ),
+                patch.object(
+                    cli,
+                    "select_skills",
+                    side_effect=choose,
+                ),
+                patch.object(
+                    cli,
+                    "_install_skill",
+                    side_effect=lambda name, targets, project_root, **kwargs: installed.append(name),
+                ),
+            ):
+                cli.cmd_select(args)
+
+            manifest = (project / ".skills.yaml").read_text(encoding="utf-8")
+
+        self.assertEqual(installed, ["catalog-one"])
+        self.assertIn("builtin-one", manifest)
+        self.assertIn("source: builtin", manifest)
+        self.assertIn('name: "catalog-one"', manifest)
+        self.assertIn('source: "catalog:catalog-one"', manifest)
+        self.assertIn("targets:", manifest)
+        self.assertIn("codex", manifest)
+        self.assertEqual(
+            [choice.readonly_status for choice in selected_choices],
+            ["全局: codex", "全局: codex"],
+        )
+        self.assertIn("全局状态只读", selected_scope[0])
+
+    def test_global_installation_note_reports_agents_and_source_conflicts(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            expected = root / "expected"
+            other = root / "other"
+            expected.mkdir()
+            other.mkdir()
+            global_dirs = {
+                target: root / target / "skills"
+                for target in ("cursor", "claude", "codex")
+            }
+            for directory in global_dirs.values():
+                directory.mkdir(parents=True)
+            (global_dirs["cursor"] / "ack").symlink_to(expected, target_is_directory=True)
+            (global_dirs["claude"] / "ack").symlink_to(other, target_is_directory=True)
+
+            with patch.object(
+                cli,
+                "agent_skill_dir",
+                side_effect=lambda target, project_root=None: global_dirs[target],
+            ):
+                note = cli._global_installation_note(
+                    "ack",
+                    expected,
+                    ["cursor", "claude", "codex"],
+                )
+
+        self.assertEqual(note, "全局: cursor；全局同名冲突: claude")
+
+    def test_select_rejects_invalid_catalog_name_before_rendering(self) -> None:
+        args = argparse.Namespace(
+            agents=None,
+            global_scope=True,
+            project=None,
+            yes=False,
+        )
+        stdin = Mock()
+        stdout = Mock()
+        stdin.isatty.return_value = True
+        stdout.isatty.return_value = True
+
+        with (
+            patch.object(cli.sys, "stdin", stdin),
+            patch.object(cli.sys, "stdout", stdout),
+            patch.object(cli, "ensure_skills_home"),
+            patch.object(cli, "list_builtin_skills", return_value=[]),
+            patch.object(
+                cli,
+                "load_catalog",
+                return_value={"../../victim": {"repo": "https://example.test/repo.git"}},
+            ),
+            patch.object(cli, "select_skills") as selector,
+        ):
+            with self.assertRaisesRegex(SystemExit, "skill 名称无效"):
+                cli.cmd_select(args)
+
+        selector.assert_not_called()
+
+    def test_select_expands_catalog_collection_choices(self) -> None:
+        args = argparse.Namespace(
+            agents=[["codex"]],
+            global_scope=True,
+            project=None,
+            yes=False,
+        )
+        stdin = Mock()
+        stdout = Mock()
+        stdin.isatty.return_value = True
+        stdout.isatty.return_value = True
+        selected_choices: list[SkillChoice] = []
+        installed: list[tuple[str, str | None]] = []
+
+        def choose(choices: list[SkillChoice], **_: object) -> set[str]:
+            selected_choices.extend(choices)
+            return {"waza/think"}
+
+        with (
+            patch.object(cli.sys, "stdin", stdin),
+            patch.object(cli.sys, "stdout", stdout),
+            patch.object(cli, "ensure_skills_home"),
+            patch.object(cli, "list_builtin_skills", return_value=[]),
+            patch.object(
+                cli,
+                "load_catalog",
+                return_value={
+                    "waza": {
+                        "repo": "https://example.test/waza.git",
+                        "ref": "main",
+                        "path": "skills",
+                    }
+                },
+            ),
+            patch.object(
+                cli,
+                "_catalog_skill_names",
+                return_value=["think", "ui"],
+            ),
+            patch.object(cli, "_list_fully_installed_names", return_value=[]),
+            patch.object(cli, "_is_fully_installed", return_value=False),
+            patch.object(cli, "select_skills", side_effect=choose),
+            patch.object(
+                cli,
+                "_install_skill",
+                side_effect=lambda name, targets, project_root, **kwargs: installed.append(
+                    (name, kwargs.get("source"))
+                ),
+            ),
+        ):
+            cli.cmd_select(args)
+
+        self.assertEqual(
+            [choice.name for choice in selected_choices],
+            ["waza", "waza/think", "waza/ui"],
+        )
+        self.assertEqual(selected_choices[0].children, ("waza/think", "waza/ui"))
+        self.assertEqual([choice.indent for choice in selected_choices[1:]], [1, 1])
+        self.assertEqual(installed, [("think", "catalog:waza")])
+
+    def test_select_expands_custom_collection_choices(self) -> None:
+        args = argparse.Namespace(
+            agents=[["codex"]],
+            global_scope=True,
+            project=None,
+            yes=False,
+        )
+        stdin = Mock()
+        stdout = Mock()
+        stdin.isatty.return_value = True
+        stdout.isatty.return_value = True
+        selected_choices: list[SkillChoice] = []
+        installed: list[tuple[str, str | None]] = []
+
+        def choose(choices: list[SkillChoice], **_: object) -> set[str]:
+            selected_choices.extend(choices)
+            return {"company/review"}
+
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            review = root / "review"
+            release = root / "release"
+            review.mkdir()
+            release.mkdir()
+            with (
+                patch.object(cli.sys, "stdin", stdin),
+                patch.object(cli.sys, "stdout", stdout),
+                patch.object(cli, "ensure_skills_home"),
+                patch.object(cli, "list_builtin_skills", return_value=[]),
+                patch.object(cli, "load_catalog", return_value={}),
+                patch.object(
+                    cli,
+                    "load_sources",
+                    return_value={"company": {"local_path": str(root)}},
+                ),
+                patch.object(cli, "_ensure_source_fetched"),
+                patch.object(
+                    cli,
+                    "discover_source_skills",
+                    return_value={"review": review, "release": release},
+                ),
+                patch.object(cli, "_is_fully_installed", return_value=False),
+                patch.object(cli, "select_skills", side_effect=choose),
+                patch.object(
+                    cli,
+                    "_install_skill",
+                    side_effect=lambda name, targets, project_root, **kwargs: installed.append(
+                        (name, kwargs.get("source"))
+                    ),
+                ),
+            ):
+                cli.cmd_select(args)
+
+        self.assertEqual(
+            [choice.name for choice in selected_choices],
+            ["company", "company/review", "company/release"],
+        )
+        self.assertEqual(
+            selected_choices[0].children,
+            ("company/review", "company/release"),
+        )
+        self.assertEqual(installed, [("review", "company")])
+
+    def test_select_deduplicates_local_catalog_collection_from_builtin(self) -> None:
+        args = argparse.Namespace(
+            agents=[["codex"]],
+            global_scope=True,
+            project=None,
+            yes=False,
+        )
+        stdin = Mock()
+        stdout = Mock()
+        stdin.isatty.return_value = True
+        stdout.isatty.return_value = True
+
+        with tempfile.TemporaryDirectory() as temp:
+            skills_root = Path(temp) / "skills"
+            (skills_root / "ack").mkdir(parents=True)
+            selected_choices: list[SkillChoice] = []
+
+            def choose(choices: list[SkillChoice], **_: object) -> set[str]:
+                selected_choices.extend(choices)
+                return set()
+
+            with (
+                patch.object(cli.sys, "stdin", stdin),
+                patch.object(cli.sys, "stdout", stdout),
+                patch.object(cli, "SKILLS_DIR", skills_root),
+                patch.object(cli, "ensure_skills_home"),
+                patch.object(cli, "list_builtin_skills", return_value=["ack"]),
+                patch.object(cli, "skill_description", return_value="builtin ack"),
+                patch.object(
+                    cli,
+                    "load_catalog",
+                    return_value={
+                        "skills": {
+                            "repo": "~/.skills",
+                            "ref": "main",
+                            "path": "skills",
+                        }
+                    },
+                ),
+                patch.object(cli, "_catalog_skill_names", return_value=["ack"]),
+                patch.object(cli, "catalog_skill_path", return_value=skills_root),
+                patch.object(cli, "_is_fully_installed", return_value=False),
+                patch.object(cli, "select_skills", side_effect=choose),
+            ):
+                cli.cmd_select(args)
+
+        self.assertEqual([choice.name for choice in selected_choices], ["ack"])
+
+    def test_install_rolls_back_earlier_target_when_later_target_fails(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            skill = root / "source"
+            skill.mkdir()
+            skill.joinpath("SKILL.md").write_text("---\\n", encoding="utf-8")
+            links = {
+                "cursor": root / "cursor" / "demo",
+                "claude": root / "claude" / "demo",
+            }
+            links["claude"].mkdir(parents=True)
+
+            with (
+                patch.object(cli, "_ensure_source_fetched"),
+                patch.object(cli, "resolve_skill_source", return_value=(skill, "builtin")),
+                patch.object(
+                    cli,
+                    "agent_skill_dir",
+                    side_effect=lambda target, project_root=None: links[target].parent,
+                ),
+            ):
+                with self.assertRaises(FileExistsError):
+                    cli._install_skill("demo", ["cursor", "claude"])
+
+            self.assertFalse(links["cursor"].exists())
+            self.assertTrue(links["claude"].is_dir())
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,828 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+import skiff.cli
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+class SkillInitTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.home = Path(self.temp_dir.name)
+        self.skills_home = self.home / ".skills"
+        skill = self.skills_home / "skills" / "ack"
+        (skill / "templates").mkdir(parents=True)
+        (skill / "scripts").mkdir()
+        (skill / "SKILL.md").write_text("---\nname: ack\n---\n", encoding="utf-8")
+        (skill / "VERSION").write_text("1.2.3\n", encoding="utf-8")
+        (skill / "templates" / "project.template.md").write_text(
+            "# <project_name>\nversion=<ack_version>\npath=<overlay_file_path>\n",
+            encoding="utf-8",
+        )
+        (skill / "templates" / "tasks.template.yaml").write_text(
+            'updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"\n'
+            'ackVersion: "<接入时的 ack skill 版本>"\n'
+            'project:\n'
+            '  name: "<project_name>"\n'
+            '  repoPath: "<repo_path>"\n'
+            '  devWorktree: "<dev_worktree>"\n',
+            encoding="utf-8",
+        )
+        tasks_template = skill / "templates" / "tasks.template.yaml"
+        tasks_template.write_text(
+            tasks_template.read_text(encoding="utf-8")
+            + '  deliveryFile: "docs/ack/delivery.yaml"\n'
+            + 'deliveryRuns: []\n',
+            encoding="utf-8",
+        )
+        (skill / "templates" / "knowledge.template.yaml").write_text(
+            'updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"\n'
+            'project:\n'
+            '  name: "<project_name>"\n'
+            '  repoPath: "<repo_path>"\n',
+            encoding="utf-8",
+        )
+        (skill / "templates" / "delivery.template.yaml").write_text(
+            'version: 1\n'
+            'updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"\n'
+            'project:\n'
+            '  name: "<project_name>"\n'
+            'enabled: false\n'
+            'defaultProfile: null\n'
+            'entrypoints: {}\n'
+            'artifacts: {}\n'
+            'destinations: {}\n'
+            'environments: {}\n'
+            'profiles: {}\n',
+            encoding="utf-8",
+        )
+        for validator_name in (
+            "validate_tasks.py",
+            "validate_knowledge.py",
+            "validate_delivery.py",
+        ):
+            (skill / "scripts" / validator_name).write_text(
+                "raise SystemExit(0)\n",
+                encoding="utf-8",
+            )
+
+    def tearDown(self) -> None:
+        self.temp_dir.cleanup()
+
+    def run_skiff(self, *args: str) -> subprocess.CompletedProcess[str]:
+        env = os.environ.copy()
+        env["HOME"] = str(self.home)
+        env["PYTHONPATH"] = str(REPO_ROOT)
+        return subprocess.run(
+            [sys.executable, "-m", "skiff", *args],
+            cwd=REPO_ROOT,
+            env=env,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+    def test_init_creates_only_rendered_project_files(self) -> None:
+        project = self.home / "sample-app"
+        project.mkdir()
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        target = project / "docs" / "ack"
+        self.assertFalse((target / "kit").exists())
+        self.assertFalse((target / "framework").exists())
+        project_content = (target / "project.md").read_text(encoding="utf-8")
+        tasks_content = (target / "tasks.yaml").read_text(encoding="utf-8")
+        knowledge_content = (target / "knowledge.yaml").read_text(encoding="utf-8")
+        delivery_content = (target / "delivery.yaml").read_text(encoding="utf-8")
+        self.assertIn("# sample-app", project_content)
+        self.assertIn("version=1.2.3", project_content)
+        self.assertIn(f'repoPath: "{project}"', tasks_content)
+        self.assertIn(f'repoPath: "{project}"', knowledge_content)
+        self.assertIn('name: "sample-app"', delivery_content)
+        self.assertIn("enabled: false", delivery_content)
+        self.assertNotIn("<project_name>", tasks_content)
+        self.assertNotIn("<project_name>", knowledge_content)
+        self.assertNotIn("<project_name>", delivery_content)
+
+    def test_init_refuses_to_overwrite_existing_files(self) -> None:
+        project = self.home / "existing-app"
+        target = project / "docs" / "ack"
+        target.mkdir(parents=True)
+        existing = target / "project.md"
+        existing.write_text("keep me", encoding="utf-8")
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("拒绝覆盖已有路径", result.stderr)
+        self.assertEqual(existing.read_text(encoding="utf-8"), "keep me")
+        self.assertFalse((target / "tasks.yaml").exists())
+        self.assertFalse((target / "knowledge.yaml").exists())
+        self.assertFalse((target / "delivery.yaml").exists())
+
+    def test_init_refuses_to_overwrite_existing_knowledge_file(self) -> None:
+        project = self.home / "existing-knowledge-app"
+        target = project / "docs" / "ack"
+        target.mkdir(parents=True)
+        existing = target / "knowledge.yaml"
+        existing.write_text("keep me", encoding="utf-8")
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("拒绝覆盖已有路径", result.stderr)
+        self.assertEqual(existing.read_text(encoding="utf-8"), "keep me")
+        self.assertFalse((target / "project.md").exists())
+        self.assertFalse((target / "tasks.yaml").exists())
+
+    def test_init_refuses_to_overwrite_existing_delivery_file(self) -> None:
+        project = self.home / "existing-delivery-app"
+        target = project / "docs" / "ack"
+        target.mkdir(parents=True)
+        existing = target / "delivery.yaml"
+        existing.write_text("keep me", encoding="utf-8")
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("拒绝覆盖已有路径", result.stderr)
+        self.assertEqual(existing.read_text(encoding="utf-8"), "keep me")
+        self.assertFalse((target / "project.md").exists())
+        self.assertFalse((target / "tasks.yaml").exists())
+        self.assertFalse((target / "knowledge.yaml").exists())
+
+    def test_init_rejects_symlinked_destination_directories(self) -> None:
+        for symlink_level in ("docs", "ack"):
+            with self.subTest(symlink_level=symlink_level):
+                project = self.home / f"symlink-{symlink_level}-app"
+                outside = self.home / f"symlink-{symlink_level}-outside"
+                project.mkdir()
+                outside.mkdir()
+                if symlink_level == "docs":
+                    (project / "docs").symlink_to(
+                        outside,
+                        target_is_directory=True,
+                    )
+                else:
+                    (project / "docs").mkdir()
+                    (project / "docs" / "ack").symlink_to(
+                        outside,
+                        target_is_directory=True,
+                    )
+
+                result = self.run_skiff(
+                    "init",
+                    "ack",
+                    "--project",
+                    str(project),
+                )
+
+                self.assertNotEqual(result.returncode, 0)
+                self.assertIn("不能是软链接", result.stderr)
+                self.assertFalse((outside / "project.md").exists())
+                self.assertFalse((outside / "tasks.yaml").exists())
+                self.assertFalse((outside / "knowledge.yaml").exists())
+                self.assertFalse((outside / "delivery.yaml").exists())
+
+    def test_init_rejects_path_like_skill_name_before_resolving_targets(self) -> None:
+        project = self.home / "path-traversal-app"
+        outside = self.home / "path-traversal-outside"
+        project.mkdir()
+        outside.mkdir()
+        (project / "skills").symlink_to(outside, target_is_directory=True)
+
+        result = self.run_skiff(
+            "init",
+            "../skills/ack",
+            "--project",
+            str(project),
+        )
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("skill 名称无效", result.stderr)
+        self.assertFalse((outside / "ack").exists())
+
+    def test_atomic_publish_failure_never_exposes_partial_ack_directory(self) -> None:
+        project = self.home / "atomic-publish-app"
+        project.mkdir()
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli,
+                "_rename_directory_noreplace",
+                side_effect=RuntimeError("publish interrupted"),
+            ),
+        ):
+            with self.assertRaisesRegex(RuntimeError, "publish interrupted"):
+                skiff.cli.cmd_init(
+                    SimpleNamespace(name="ack", project=str(project))
+                )
+
+        self.assertFalse((project / "docs" / "ack").exists())
+        docs = project / "docs"
+        if docs.exists():
+            self.assertEqual(list(docs.iterdir()), [])
+
+    def test_atomic_publish_never_replaces_a_raced_destination(self) -> None:
+        project = self.home / "atomic-no-replace-app"
+        project.mkdir()
+        raced_inode: int | None = None
+        real_publish = skiff.cli._rename_directory_noreplace
+
+        def create_destination_then_publish(
+            source_parent_fd: int,
+            source_name: str,
+            destination_parent_fd: int,
+            destination_name: str,
+        ) -> None:
+            nonlocal raced_inode
+            os.mkdir(destination_name, mode=0o711, dir_fd=destination_parent_fd)
+            raced_inode = os.stat(
+                destination_name,
+                dir_fd=destination_parent_fd,
+                follow_symlinks=False,
+            ).st_ino
+            real_publish(
+                source_parent_fd,
+                source_name,
+                destination_parent_fd,
+                destination_name,
+            )
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli,
+                "_rename_directory_noreplace",
+                side_effect=create_destination_then_publish,
+            ),
+        ):
+            with self.assertRaisesRegex(SystemExit, "拒绝覆盖已有路径"):
+                skiff.cli.cmd_init(
+                    SimpleNamespace(name="ack", project=str(project))
+                )
+
+        target = project / "docs" / "ack"
+        self.assertTrue(target.is_dir())
+        self.assertEqual(target.stat().st_ino, raced_inode)
+        self.assertEqual(list(target.iterdir()), [])
+        self.assertEqual(target.stat().st_mode & 0o777, 0o711)
+
+    def test_published_destination_replacement_never_reports_success(self) -> None:
+        project = self.home / "published-destination-app"
+        moved_target = project / "docs" / "ack-moved"
+        project.mkdir()
+        real_publish = skiff.cli._rename_directory_noreplace
+
+        def replace_destination_after_publish(
+            source_parent_fd: int,
+            source_name: str,
+            destination_parent_fd: int,
+            destination_name: str,
+        ) -> None:
+            real_publish(
+                source_parent_fd,
+                source_name,
+                destination_parent_fd,
+                destination_name,
+            )
+            target = project / "docs" / destination_name
+            target.rename(moved_target)
+            target.mkdir()
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli,
+                "_rename_directory_noreplace",
+                side_effect=replace_destination_after_publish,
+            ),
+        ):
+            with self.assertRaisesRegex(SystemExit, "ACK 目录已被替换"):
+                skiff.cli.cmd_init(
+                    SimpleNamespace(name="ack", project=str(project))
+                )
+
+        self.assertEqual(list((project / "docs" / "ack").iterdir()), [])
+        self.assertEqual(
+            sorted(path.name for path in moved_target.iterdir()),
+            ["delivery.yaml", "knowledge.yaml", "project.md", "tasks.yaml"],
+        )
+
+    def test_transaction_container_replacement_cannot_forge_payload(self) -> None:
+        project = self.home / "transaction-source-app"
+        attacker = self.home / "transaction-attacker"
+        project.mkdir()
+        attacker.mkdir()
+        (attacker / "marker").write_text("forged", encoding="utf-8")
+        real_publish = skiff.cli._rename_directory_noreplace
+
+        def replace_outer_transaction_then_publish(
+            source_parent_fd: int,
+            source_name: str,
+            destination_parent_fd: int,
+            destination_name: str,
+        ) -> None:
+            docs = project / "docs"
+            transactions = [
+                path
+                for path in docs.iterdir()
+                if path.name.startswith(".ack-init-")
+            ]
+            self.assertEqual(len(transactions), 1)
+            transaction = transactions[0]
+            saved = docs / f"{transaction.name}.saved"
+            transaction.rename(saved)
+            transaction.symlink_to(attacker, target_is_directory=True)
+            real_publish(
+                source_parent_fd,
+                source_name,
+                destination_parent_fd,
+                destination_name,
+            )
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli,
+                "_rename_directory_noreplace",
+                side_effect=replace_outer_transaction_then_publish,
+            ),
+        ):
+            skiff.cli.cmd_init(
+                SimpleNamespace(name="ack", project=str(project))
+            )
+
+        target = project / "docs" / "ack"
+        self.assertTrue(target.is_dir())
+        self.assertFalse(target.is_symlink())
+        self.assertFalse((target / "marker").exists())
+        self.assertEqual(
+            sorted(path.name for path in target.iterdir()),
+            ["delivery.yaml", "knowledge.yaml", "project.md", "tasks.yaml"],
+        )
+
+    def test_post_publish_fsync_failure_preserves_complete_state(self) -> None:
+        project = self.home / "post-publish-fsync-app"
+        project.mkdir()
+        real_fsync = os.fsync
+        calls = 0
+
+        def fail_directory_fsync_after_publish(file_descriptor: int) -> None:
+            nonlocal calls
+            calls += 1
+            if calls == 8:
+                raise OSError("simulated directory fsync failure")
+            real_fsync(file_descriptor)
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli.os,
+                "fsync",
+                side_effect=fail_directory_fsync_after_publish,
+            ),
+        ):
+            with self.assertRaisesRegex(SystemExit, "已完整发布"):
+                skiff.cli.cmd_init(
+                    SimpleNamespace(name="ack", project=str(project))
+                )
+
+        target = project / "docs" / "ack"
+        self.assertEqual(
+            sorted(path.name for path in target.iterdir()),
+            ["delivery.yaml", "knowledge.yaml", "project.md", "tasks.yaml"],
+        )
+
+    def test_project_root_replacement_aborts_before_publish(self) -> None:
+        project = self.home / "root-replacement-app"
+        moved_project = self.home / "root-replacement-moved"
+        project.mkdir()
+        real_open_docs = skiff.cli._open_or_create_directory_at
+        replaced = False
+
+        def replace_root_then_open_docs(
+            parent_fd: int,
+            name: str,
+        ) -> tuple[int, bool]:
+            nonlocal replaced
+            if not replaced:
+                project.rename(moved_project)
+                project.mkdir()
+                replaced = True
+            return real_open_docs(parent_fd, name)
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli,
+                "_open_or_create_directory_at",
+                side_effect=replace_root_then_open_docs,
+            ),
+        ):
+            with self.assertRaisesRegex(SystemExit, "项目目录已被替换"):
+                skiff.cli.cmd_init(
+                    SimpleNamespace(name="ack", project=str(project))
+                )
+
+        self.assertFalse((project / "docs" / "ack").exists())
+        self.assertFalse((moved_project / "docs" / "ack").exists())
+
+    def test_project_root_replacement_at_publish_never_reports_success(self) -> None:
+        project = self.home / "publish-root-replacement-app"
+        moved_project = self.home / "publish-root-replacement-moved"
+        project.mkdir()
+        real_publish = skiff.cli._rename_directory_noreplace
+
+        def replace_root_then_publish(
+            source_parent_fd: int,
+            source_name: str,
+            destination_parent_fd: int,
+            destination_name: str,
+        ) -> None:
+            project.rename(moved_project)
+            project.mkdir()
+            real_publish(
+                source_parent_fd,
+                source_name,
+                destination_parent_fd,
+                destination_name,
+            )
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli,
+                "_rename_directory_noreplace",
+                side_effect=replace_root_then_publish,
+            ),
+        ):
+            with self.assertRaisesRegex(SystemExit, "ACK 目录已移动或不可访问"):
+                skiff.cli.cmd_init(
+                    SimpleNamespace(name="ack", project=str(project))
+                )
+
+        self.assertFalse((project / "docs" / "ack").exists())
+        target = moved_project / "docs" / "ack"
+        self.assertEqual(
+            sorted(path.name for path in target.iterdir()),
+            ["delivery.yaml", "knowledge.yaml", "project.md", "tasks.yaml"],
+        )
+
+    def test_docs_replacement_aborts_before_publish(self) -> None:
+        project = self.home / "docs-replacement-app"
+        moved_docs = project / "docs-moved"
+        project.mkdir()
+        real_assert_binding = skiff.cli._assert_open_directory_path
+        replaced = False
+
+        def replace_docs_at_publish_check(
+            directory_fd: int,
+            path: Path,
+            *,
+            phase: str,
+            label: str = "项目目录",
+        ) -> None:
+            nonlocal replaced
+            if label == "docs 目录" and phase == "发布" and not replaced:
+                (project / "docs").rename(moved_docs)
+                (project / "docs").mkdir()
+                replaced = True
+            real_assert_binding(
+                directory_fd,
+                path,
+                phase=phase,
+                label=label,
+            )
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli,
+                "_assert_open_directory_path",
+                side_effect=replace_docs_at_publish_check,
+            ),
+        ):
+            with self.assertRaisesRegex(SystemExit, "docs 目录已被替换"):
+                skiff.cli.cmd_init(
+                    SimpleNamespace(name="ack", project=str(project))
+                )
+
+        self.assertFalse((project / "docs" / "ack").exists())
+        self.assertFalse((moved_docs / "ack").exists())
+
+    def test_docs_replacement_at_publish_never_reports_success(self) -> None:
+        project = self.home / "publish-docs-replacement-app"
+        moved_docs = project / "docs-moved"
+        project.mkdir()
+        real_publish = skiff.cli._rename_directory_noreplace
+
+        def replace_docs_then_publish(
+            source_parent_fd: int,
+            source_name: str,
+            destination_parent_fd: int,
+            destination_name: str,
+        ) -> None:
+            (project / "docs").rename(moved_docs)
+            (project / "docs").mkdir()
+            real_publish(
+                source_parent_fd,
+                source_name,
+                destination_parent_fd,
+                destination_name,
+            )
+
+        with (
+            mock.patch.object(skiff.cli, "SKILLS_HOME", self.skills_home),
+            mock.patch.object(
+                skiff.cli,
+                "SKILLS_DIR",
+                self.skills_home / "skills",
+            ),
+            mock.patch.object(skiff.cli, "ensure_skills_home"),
+            mock.patch.object(
+                skiff.cli,
+                "_rename_directory_noreplace",
+                side_effect=replace_docs_then_publish,
+            ),
+        ):
+            with self.assertRaisesRegex(SystemExit, "ACK 目录已移动或不可访问"):
+                skiff.cli.cmd_init(
+                    SimpleNamespace(name="ack", project=str(project))
+                )
+
+        self.assertFalse((project / "docs" / "ack").exists())
+        target = moved_docs / "ack"
+        self.assertEqual(
+            sorted(path.name for path in target.iterdir()),
+            ["delivery.yaml", "knowledge.yaml", "project.md", "tasks.yaml"],
+        )
+
+    def test_ack_init_requires_knowledge_template(self) -> None:
+        project = self.home / "missing-knowledge-template-app"
+        project.mkdir()
+        (
+            self.skills_home
+            / "skills"
+            / "ack"
+            / "templates"
+            / "knowledge.template.yaml"
+        ).unlink()
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("knowledge.template.yaml", result.stderr)
+        self.assertFalse((project / "docs" / "ack").exists())
+
+    def test_ack_init_requires_delivery_template(self) -> None:
+        project = self.home / "missing-delivery-template-app"
+        project.mkdir()
+        (
+            self.skills_home
+            / "skills"
+            / "ack"
+            / "templates"
+            / "delivery.template.yaml"
+        ).unlink()
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("delivery.template.yaml", result.stderr)
+        self.assertFalse((project / "docs" / "ack").exists())
+
+    def test_ack_init_requires_all_validators(self) -> None:
+        for validator_name in (
+            "validate_tasks.py",
+            "validate_knowledge.py",
+            "validate_delivery.py",
+        ):
+            with self.subTest(validator_name=validator_name):
+                project = self.home / f"missing-{validator_name}-app"
+                project.mkdir()
+                validator = (
+                    self.skills_home
+                    / "skills"
+                    / "ack"
+                    / "scripts"
+                    / validator_name
+                )
+                original = validator.read_text(encoding="utf-8")
+                validator.unlink()
+                try:
+                    result = self.run_skiff(
+                        "init",
+                        "ack",
+                        "--project",
+                        str(project),
+                    )
+                finally:
+                    validator.write_text(original, encoding="utf-8")
+
+                self.assertNotEqual(result.returncode, 0)
+                self.assertIn("缺少初始化校验器", result.stderr)
+                self.assertIn(validator_name, result.stderr)
+                self.assertFalse((project / "docs" / "ack").exists())
+
+    def test_validator_failure_leaves_no_partial_initialization(self) -> None:
+        project = self.home / "invalid-knowledge-app"
+        project.mkdir()
+        validator = (
+            self.skills_home / "skills" / "ack" / "scripts" / "validate_knowledge.py"
+        )
+        validator.write_text("raise SystemExit(1)\n", encoding="utf-8")
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertNotIn("Traceback", result.stderr)
+        self.assertIn("初始化知识库校验失败", result.stderr)
+        self.assertFalse((project / "docs" / "ack").exists())
+
+    def test_delivery_validator_failure_leaves_no_partial_initialization(self) -> None:
+        project = self.home / "invalid-delivery-app"
+        project.mkdir()
+        validator = (
+            self.skills_home / "skills" / "ack" / "scripts" / "validate_delivery.py"
+        )
+        validator.write_text("raise SystemExit(1)\n", encoding="utf-8")
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertNotIn("Traceback", result.stderr)
+        self.assertIn("初始化交付契约校验失败", result.stderr)
+        self.assertFalse((project / "docs" / "ack").exists())
+
+    def test_validator_cannot_replace_staged_bytes_before_install(self) -> None:
+        project = self.home / "mutated-staging-app"
+        project.mkdir()
+        validator = (
+            self.skills_home / "skills" / "ack" / "scripts" / "validate_knowledge.py"
+        )
+        validator.write_text(
+            "import sys\n"
+            "from pathlib import Path\n"
+            "Path(sys.argv[1]).write_text('forged: true\\n', encoding='utf-8')\n",
+            encoding="utf-8",
+        )
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("临时文件在校验期间发生变化", result.stderr)
+        self.assertFalse((project / "docs" / "ack").exists())
+
+    def test_ack_init_validates_mirrored_staging_root(self) -> None:
+        project = self.home / "staged-knowledge-app"
+        project.mkdir()
+        validator = (
+            self.skills_home / "skills" / "ack" / "scripts" / "validate_knowledge.py"
+        )
+        validator.write_text(
+            "import sys\n"
+            "from pathlib import Path\n"
+            "required = ['--tasks', '--project-root']\n"
+            "if any(item not in sys.argv for item in required):\n"
+            "    raise SystemExit(3)\n"
+            "root = Path(sys.argv[sys.argv.index('--project-root') + 1])\n"
+            "knowledge = Path(sys.argv[1])\n"
+            "tasks = Path(sys.argv[sys.argv.index('--tasks') + 1])\n"
+            "expected = root / 'docs' / 'ack'\n"
+            "raise SystemExit(0 if knowledge.parent == expected and "
+            "tasks.parent == expected else 4)\n",
+            encoding="utf-8",
+        )
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue((project / "docs" / "ack" / "knowledge.yaml").is_file())
+
+    def test_ack_delivery_init_validates_mirrored_staging_root(self) -> None:
+        project = self.home / "staged-delivery-app"
+        project.mkdir()
+        validator = (
+            self.skills_home / "skills" / "ack" / "scripts" / "validate_delivery.py"
+        )
+        validator.write_text(
+            "import sys\n"
+            "from pathlib import Path\n"
+            "required = ['--tasks', '--project-root']\n"
+            "if any(item not in sys.argv for item in required):\n"
+            "    raise SystemExit(3)\n"
+            "root = Path(sys.argv[sys.argv.index('--project-root') + 1])\n"
+            "delivery = Path(sys.argv[1])\n"
+            "tasks = Path(sys.argv[sys.argv.index('--tasks') + 1])\n"
+            "expected = root / 'docs' / 'ack'\n"
+            "raise SystemExit(0 if delivery.parent == expected and "
+            "tasks.parent == expected else 4)\n",
+            encoding="utf-8",
+        )
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue((project / "docs" / "ack" / "delivery.yaml").is_file())
+
+    def test_non_ack_init_still_requires_only_project_and_tasks_templates(self) -> None:
+        skill = self.skills_home / "skills" / "plain"
+        (skill / "templates").mkdir(parents=True)
+        (skill / "SKILL.md").write_text("---\nname: plain\n---\n", encoding="utf-8")
+        (skill / "templates" / "project.template.md").write_text(
+            "# <project_name>\n", encoding="utf-8"
+        )
+        (skill / "templates" / "tasks.template.yaml").write_text(
+            'project: "<project_name>"\n', encoding="utf-8"
+        )
+        project = self.home / "plain-app"
+        project.mkdir()
+
+        result = self.run_skiff("init", "plain", "--project", str(project))
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        target = project / "docs" / "plain"
+        self.assertTrue((target / "project.md").is_file())
+        self.assertTrue((target / "tasks.yaml").is_file())
+        self.assertFalse((target / "knowledge.yaml").exists())
+        self.assertFalse((target / "delivery.yaml").exists())
+
+    def test_init_rejects_missing_project_directory(self) -> None:
+        project = self.home / "missing-app"
+
+        result = self.run_skiff("init", "ack", "--project", str(project))
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("项目目录不存在", result.stderr)
+        self.assertFalse(project.exists())
+
+    def test_legacy_kit_command_is_not_exposed(self) -> None:
+        result = self.run_skiff("kit", "init", "ack")
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("invalid choice", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()
Author	SHA1	Message	Date
laily	e7efea28b4	feat(ack): add one-off delivery routing	2026-08-01 15:25:15 +08:00
laily	5b0e41199d	Merge pull request 'feat(ack): add project delivery workflow' (#4 ) from add-extro-info into main Reviewed-on: laily/.skills#4	2026-08-01 14:24:32 +08:00
laily	2c3d91c75c	feat(ack): add project delivery workflow	2026-08-01 12:35:42 +08:00
laily	f08edb6452	Merge pull request 'feat: add manage-release skill' (#3 ) from release into main Reviewed-on: laily/.skills#3	2026-08-01 10:19:39 +08:00
laily	d7997091bd	feat: add manage-release skill	2026-07-31 23:58:47 +08:00
laily	ae3bce7b5d	feat(ack): add structured worker model routing	2026-07-31 23:34:13 +08:00
laily	ee66dbe9ce	feat(ack): add project knowledge guardrails	2026-07-31 21:09:36 +08:00
laily	7d1994cf93	refactor: unify skill source model	2026-07-30 12:11:25 +08:00
laily	076d87e303	refactor: fold ack kit into skill	2026-07-30 11:54:02 +08:00
laily	e308d6a04c	feat: add reusable deb upload script	2026-07-30 10:19:28 +08:00
laily	e667f58bf1	add README guidance to skill workflow	2026-07-29 21:08:04 +08:00
laily	262c138bee	feat: add shallow fetch and grouped skill selection	2026-07-29 10:57:53 +08:00
laily	18ebb70911	feat: add self-update and improve skill selector	2026-07-29 10:29:48 +08:00
laily	afbdde157f	feat: add explicit ack workflow skill	2026-07-28 17:08:33 +08:00
laily	5f90758e22	feat: add kit project initializer	2026-07-28 16:41:41 +08:00
laily	983183d5b3	feat: support registry collections and docker publishing	2026-07-27 23:25:46 +08:00
laily	b78126830b	merge: custom skill sources # Conflicts: # skiff/README.md # skiff/cli.py # skiff/project.py	2026-07-27 18:11:31 +08:00
laily	3411e54b13	feat: support custom skill sources	2026-07-27 18:09:13 +08:00
laily	b9963b66de	feat: add interactive skill selector	2026-07-27 18:07:39 +08:00
laily	86cd1fa36d	feat: add skill draft workflow	2026-07-27 14:03:19 +08:00
laily	8b82539f6f	fix: 复用 agent	2026-07-15 01:29:56 +08:00
laily	b3765ecad6	feat(ack): enforce worker launch policy	2026-07-12 17:19:46 +08:00
laily	ae05845ee7	docs(ack): add Codex model routing	2026-07-12 14:53:50 +08:00
laily	af823e867f	feat: add init-new-project	2026-07-07 09:50:04 +08:00
laily	61ef55c514	feat: modify ack	2026-07-07 09:44:55 +08:00
laily	d11f90fd66	feat(ack): worker 模型固定与 worktree 决策说明 (v0.6.2)	2026-07-07 01:45:55 +08:00
laily	f33992a0aa	feat: rename	2026-07-07 01:33:48 +08:00
laily	6bd03c2f6d	feat:	2026-07-07 00:53:54 +08:00
laily	d7a74578dc	refactor(agent-collaboration-kit): split stable core from project overrides - Reorganize flat files into core/ templates/ examples/ scripts/ with VERSION - Deduplicate: single-source state machine, three-round policy, acceptance signals - Abstract orchestration in closed-loop.md with manual mode; move Orca commands to orca-adapter.md - Add tasks.schema.json + validate_tasks.py (jsonschema or builtin rules, no hard deps) - Add filled examples, concurrency write rule, kitVersion tracking; unify to Chinese Co-authored-by: Cursor <cursoragent@cursor.com>	2026-07-06 10:01:09 +08:00
laily	58de2650c2	docs: separate agent collaboration kit from skills Co-authored-by: Cursor <cursoragent@cursor.com>	2026-07-06 09:32:50 +08:00
laily	c4c68572c3	feat: add agent-collaboration-kit	2026-07-06 09:24:22 +08:00
laily	f1ed320991	feat(skiff): align CLI with Vercel skills and fix entry symlink Replace install/uninstall with add/remove, add publish for git ops in ~/.skills, and resolve bin/skiff symlinks so commands work from any cwd. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-07-04 12:11:53 +08:00
laily	9a3285fba6	Merge pull request 'feat: add skiff' (#2 ) from feat/discussion-notes into main Reviewed-on: laily/.skills#2	2026-07-04 10:52:53 +08:00
laily	af0efc7870	Merge pull request 'feat: add discussion-notes skill' (#1 ) from feat/discussion-notes into main Reviewed-on: laily/.skills#1	2026-07-03 00:36:22 +08:00