feat(ack): shard task records for merge-safe workspaces

skills/ack/SKILL.md

@@ -8,12 +8,14 @@ description: >-
 
 # ACK 项目协作入口
 
-项目只在 `.pouch/ack/` 保存 `project.md`、`tasks.yaml`、`knowledge.yaml`、
+项目只在 `.pouch/ack/` 保存 `project.md`、`tasks.yaml`、`task-records/`、`knowledge.yaml`、
 `delivery.yaml`、`regression.yaml`，以及可选的 `agents.yaml` 角色启动覆盖配置。
 不要复制 Skill 内容，不要修改项目的 `AGENTS.md`、
 `CLAUDE.md`。
 
-固定状态文件为 `.pouch/ack/project.md`、`.pouch/ack/tasks.yaml`、
+固定配置文件为 `.pouch/ack/project.md`、`.pouch/ack/tasks.yaml`；任务执行记录从
+`.pouch/ack/task-records/` 追加读取。旧项目没有 `taskStore` 时仍兼容直接读取
+`tasks.yaml`。固定状态文件为 `.pouch/ack/project.md`、`.pouch/ack/tasks.yaml`、
 `.pouch/ack/knowledge.yaml`、`.pouch/ack/delivery.yaml` 和
 `.pouch/ack/regression.yaml`。
 
@@ -38,7 +40,10 @@ description: >-
 - `agents.yaml` 是可选的临时角色启动覆盖；存在时优先于 `tasks.yaml.project.orchestration`，不存在时回退到任务板配置。
 - `agents.yaml` 只能描述结构化 CLI、模型、reasoning effort 和权限，不能保存 command、argv、shell 或环境变量；Pi 的默认模型用 `cli: pi`、`model: null` 表示。
 - 不把完整 `tasks.yaml` / `knowledge.yaml` / `regression.yaml` 注入上下文；用对应 `select_*.py`。写回前跑完整校验。
-- 只有 Coordinator 写任务板、知识库、回归目录、`deliveryRuns` 和 `regressionRuns`。`delivery.yaml` 只在「交付配置维护」中改。见 [roles-and-permissions.md](references/roles-and-permissions.md)。
+- 新项目不要把任务状态、worker receipt 或运行历史回写到 `tasks.yaml`；每次状态变化写入
+  `task-records/<recordId>.yaml`，记录必须包含 `taskId`、`parents` 和完整 `task` 快照。
+  同一任务出现多个 head 时停止并创建显式合并记录，禁止按时间静默覆盖。
+- 只有 Coordinator 写任务记录、知识库、回归目录、`deliveryRuns` 和 `regressionRuns`。`delivery.yaml` 只在「交付配置维护」中改。见 [roles-and-permissions.md](references/roles-and-permissions.md)。
 - 知识检查只经 `run_verification.py` 的 registry ID；不把知识正文拼成 shell。
 - 自动 worker 禁止 full-access、bypass、关闭 sandbox、Grok `--yolo` / bypassPermissions。OMP `--approval-mode yolo` 只用于 OMP 审批（workspace-write → yolo，read-only → always-ask），禁止 `--auto-approve`，不适用于其它 backend。
 - 无清理证明不复用 worker；无密钥 `receiptHash` 或 Orca live metadata 不能授权复用。当前 Orca 走 fresh。只复用同轮、空闲且完成清理历史消息的 worker；无法确认清理成功时创建 fresh worker。`indeterminate` / `reconcile required` 不直接重试。
@@ -61,9 +66,19 @@ python3 <ack-skill-dir>/scripts/validate_regression.py .pouch/ack/regression.yam
 
 # 仅在存在临时角色配置时运行
 python3 <ack-skill-dir>/scripts/validate_agents.py .pouch/ack/agents.yaml
+
 ```
 
 4. 检查上述文件是否仍有 `<...>` 占位符；没有真实任务时使用 `tasks: []`。结构校验通过且必填项目事实完整才称「完成」。除非用户明确要求，不提交、不推送。
+   旧项目迁移前先预览 `python3 <ack-skill-dir>/scripts/migrate_tasks.py .pouch/ack/tasks.yaml`，确认后再加 `--apply`。
+
+追加任务状态时使用完整快照 JSON，不修改已有记录：
+
+```bash
+python3 <ack-skill-dir>/scripts/record_task.py .pouch/ack/tasks.yaml \
+  --task-id <task-id> --task-json <task-snapshot.json> \
+  --parent <previous-record-id> --kind task.snapshot
+```
 
 ```text
 ## ack 初始化：完成 | 部分完成 | 阻塞