# 在新项目初始化 ACK

本文件说明如何把 ACK 的项目状态初始化到目标项目。ACK Skill 自身已经通过 Agent
的 Skill 机制安装；项目不复制、不链接 Skill 内容。

## 前提与边界

开始前确认：

1. 目标项目根目录。
2. ACK Skill 已全局安装或安装到当前项目。
3. `pouch` 命令可用。

不要覆盖已有的 `.pouch/ack/project.md`、`.pouch/ack/tasks.yaml`、
`.pouch/ack/knowledge.yaml`、`.pouch/ack/delivery.yaml`、`.pouch/ack/regression.yaml`、
`AGENTS.md` 或其它 Agent
指令文件。ACK 不会自动
修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。不要把 token、`.env`
内容或其它私有配置写入 ACK 项目状态。

## 初始化

在目标项目执行：

```bash
pouch init ack
```

或显式指定项目：

```bash
pouch init ack --project <project-root>
```

命令从 ACK Skill 自带的 `templates/` 生成：

```text
.pouch/ack/
├── project.md
├── tasks.yaml
├── knowledge.yaml
├── delivery.yaml       # 默认 enabled: false
└── regression.yaml     # 默认 cases: []
```

如果任一目标文件已经存在，命令会拒绝覆盖。初始化过程不会创建 `kit`、
`framework` 或其它指向 Skill 的软链接。

### 旧项目补充知识库

旧项目已经有 `project.md` 和 `tasks.yaml`、但没有 `knowledge.yaml` 时，不要重跑
`pouch init ack`。先检查现有文件并向用户报告缺失项；用户授权后，只从
`templates/knowledge.template.yaml` 生成 `.pouch/ack/knowledge.yaml`，替换项目名和
当前时间，保留 `entries: []`。如果现有任务板缺少
`project.knowledgeFile`，同一次授权只补
`knowledgeFile: .pouch/ack/knowledge.yaml`，不改写其它项目状态。生成后运行任务板、
知识库和跨文件引用校验。

### 旧项目补充交付配置

`delivery.yaml` 对旧项目是可选能力；缺少它不会影响三角色开发与验证闭环。只有用户
明确要求配置项目交付时，才从 `templates/delivery.template.yaml` 生成文件，同时在
任务板补 `project.deliveryFile: .pouch/ack/delivery.yaml` 与顶层
`deliveryRuns: []`。首次生成保持 `enabled: false`，按 `delivery.md` 展示并确认
解析结果后才启用。不要重跑 `pouch init ack`，也不要改写已有任务或知识。

### 旧项目补充回归目录

`regression.yaml` 对旧项目是可选能力。用户明确要求回归或授权补齐时，从
`templates/regression.template.yaml` 生成 `.pouch/ack/regression.yaml`，并只补
`project.regressionFile: .pouch/ack/regression.yaml` 与顶层 `regressionRuns: []`。
保持 `cases: []`，不要从聊天虚构用例。

## 完善项目覆盖层

编辑 `.pouch/ack/project.md`，填入：

- 项目名、技术栈、运行命令和 Base URL。
- Coordinator、Developer、Test 的实际模型档位。
- 规格、集成测试、源码、单元测试和私有配置的路径权限。
- Developer 白盒验证命令。
- Test 黑盒复测命令。

无法从项目证据确定的值写为 `n/a`，不要猜测。

## 完善任务板

编辑 `.pouch/ack/tasks.yaml`：

- `ackVersion` 使用 ACK Skill 的合法 SemVer `VERSION`；从 `0.10.0` 起
  `project.orchestration` 与顶层 `workerReceipts` 必须同时存在。
- 从 `0.11.0` 起的新项目初始化包含默认关闭的交付契约；旧项目不要求为了版本号升级
  自动补交付配置。
- `updatedAt` 使用当前带时区时间。
- `project.name` 使用真实值；`overlayFile` 和 `knowledgeFile` 使用项目内相对路径。
  ACK 从命令行 `--project-root` 下固定的 `.pouch/ack/` 布局解析项目状态，不把
  `repoPath` 或 `devWorktree` 绝对路径写入任务板。旧任务板中的这两个字段仅兼容读取，
  不再参与路径绑定。
- 新项目的 `project.deliveryFile` 固定为 `.pouch/ack/delivery.yaml`，并保留顶层
  `deliveryRuns: []`。旧项目只有在采用交付能力时才补这两个字段。
- 新项目的 `project.regressionFile` 固定为 `.pouch/ack/regression.yaml`，并保留顶层
  `regressionRuns: []`。旧项目只有在采用回归能力时才补这两个字段。
- `allowedWorktrees` 已废弃（v0.19 起），新任务板不生成该字段；worker 默认在
  `--project-root` 工作。模型 allowlist、profiles 和 defaults 使用项目实际允许值。
  不要把完整启动命令、`extraArgs`、`env` 或任意 executable 写进任务板。
- 非服务项目的 `baseUrl` 写为 `n/a`。
- 没有真实任务时使用 `tasks: []`，不要保留或虚构示例任务。

每个真实任务的验收必须是可观测信号，例如可见文本、API 状态和字段，或明确的交互
结果；不要只写“功能正常”。

## 初始化项目知识

新项目的 `.pouch/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 或正式规范。

## 初始化项目交付

新项目的 `.pouch/ack/delivery.yaml` 保持 `enabled: false`、空能力表、空 profile，以及
`intents.testEnvironment: null` 与 `intents.release: null`。
不要根据 README 或 CI 自动推断并启用发布/部署。用户说明测试环境后，Coordinator
把 `intents.testEnvironment` 写成 `{via: deployer, env: <env>}`，若
`.pouch/deployer/<env>` 尚未就绪则加载 deployer skill 的「初始化」；发版仍指向
profile。ACK 初始化不自动跑 deployer 初始化。
配置中不保存 shell、环境变量值或凭据正文；稳定发布和生产部署必须有显式
approval 步骤。

## 初始化回归目录

新项目的 `.pouch/ack/regression.yaml` 保持 `cases: []`。不要从 README 或聊天猜测
用例。任务 `verified` 后按 `regression.md` 收获。

## 校验

Agent 从当前 `SKILL.md` 解析 ACK Skill 目录后运行：

```bash
python3 <ack-skill-dir>/scripts/validate_tasks.py .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_knowledge.py .pouch/ack/knowledge.yaml --tasks .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_delivery.py .pouch/ack/delivery.yaml \
  --tasks .pouch/ack/tasks.yaml --project-root <project-root>
python3 <ack-skill-dir>/scripts/validate_regression.py .pouch/ack/regression.yaml \
  --tasks .pouch/ack/tasks.yaml
```

同时确认：

- `project.md`、`tasks.yaml`、`knowledge.yaml`、`delivery.yaml` 和
  `regression.yaml` 没有未替换的 `<...>` 占位符。
- `project.overlayFile` 指向真实文件。
- `project.knowledgeFile` 指向 `.pouch/ack/knowledge.yaml`。
- 新项目的 `project.deliveryFile` 指向 `.pouch/ack/delivery.yaml`；交付默认关闭。
- Developer 与 Test 的验证命令可执行。
- `project.orchestration` 的 profile/allowlist/defaults 通过校验，自动模式只允许
  `read-only` 或 `workspace-write`；旧任务板未迁移时保持手动模式。
- 顶层 `workerReceipts` 和 `dispatch.developer/test` 的 task/role/profile/attempt
  引用一致；`receiptId` 与 `attemptId` 同时为空或同时填写。持久 receipt 只作审计，
  不能单独授权复用旧终端；复用还需要空闲状态、身份匹配和可信历史清理证明。
- 网站或 API 项目写清服务启动、重启和 Base URL。
- 任务中的固定 revision `knowledgeRefs` 都能解析，非 `active` 条目没有被派发。

## 初始化报告

按 `SKILL.md`「初始化」最后一步的格式报告（`## ack 初始化：完成 | 部分完成 | 阻塞`），
列出已具备项、待配置项（路径 + 字段 + 示例）、工具链和下一步。

只有结构校验通过且必填项目事实完整时才称「完成」；否则称「部分完成」或「阻塞」。
除非用户明确要求，不提交、不推送。