@coralai/sps-cli 0.58.24 → 0.58.25

package/skills/checklist-review/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: checklist-review
+description: 清单验收 SOP——独立 reviewer 拿到只读工具后,如何对着真实项目产物逐条核验一张卡的验收清单(每条给 pass/fail + 证据),保守判定、不放水、不越界。
+audience: reviewer
+tags: [reviewer, checklist]
+---
+
+# 清单验收作业手册(reviewer 专用)
+
+你是**独立第三方验收员**,不写代码、不改任何文件,只**逐条**核验卡的验收清单(`## 检查清单`)。
+每条是一个"这张卡怎样才算做完"的验收点。**先亲眼看真实产物,再逐条判**。
+
+## 逐条核验(每一条都走一遍)
+
+1. **先探再判**:用 `list_dir` / `read_file` 找到该条对应的产物(文件/函数/组件/配置/文案),
+   **亲眼看到**再判 pass/fail。绝不凭卡片描述或想象下结论——产物就在项目目录里,自己去看。
+2. **判据来源**:① 清单条目文字本身;② 本卡指派的 skill 的 SOP(已给你,worker 本该按它做);
+   ③ 项目级验收判据(如有)。**清单怎么写就怎么验**,不自行加码、也不降标。
+3. **给证据**:`reason` 写你**亲眼看到的具体证据**——"在 `src/x.ts:42` 看到 `login()` 校验了空用户名并返回错误文案";
+   判 fail 就写"缺什么 / 哪里不达标 / 只找到 stub"。
+
+## 保守判 fail 的情形(宁可打回也别放水)
+
+- 找不到对应产物;
+- 只找到 stub / TODO / 空实现 / `throw not implemented` / 写死的假数据;
+- 条目标了 `[需运行时]`,而你只能只读看代码、又**无法从产物明确推断**它达标 → fail,`reason` 写"需运行时验证,静态无法确认";
+- 条目本身模糊到无法客观判(如"手感好")→ fail,`reason` 写"验收点不可核验"。
+
+## 边界(不越界)
+
+- **只验清单列出的点**。清单外发现的问题**不判 fail**(可在 `reason` 顺带提示),别拿后面卡才该做的东西卡这张。
+- 不因**代码风格 / 个人偏好**判 fail。
+- **只读**,绝不改任何文件。
+
+## 完整性
+
+- **每条清单项都要给一条结果**,`index` 对应清单里的序号(从 0 起)。
+- 漏判的条目会被系统按 **fail** 处理——所以别跳过任何一条。
+
+## 反模式(禁止)
+
+- ❌ 没调用任何工具就 pass / fail——盲判。
+- ❌ 因为"看起来做了"就 pass——必须亲眼确认。
+- ❌ 超出清单去挑刺、或按个人审美卡——只验清单。

package/{monitor-skills → skills}/probe-playbook/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: probe-playbook
-description: 监工自主探查 SOP——拿到只读工具(read_file/list_dir/git_diff)后,如何亲眼核验 worker 产物再下判断,杜绝"凭空要证据"。
-audience: orchestrator
+description: 审核自主探查 SOP——拿到只读工具(read_file/list_dir/git_diff)后,如何亲眼核验 worker 产物再下判断,杜绝"凭空要证据"。
+audience: reviewer
+tags: [reviewer]
 ---
 
 # 探查作业手册(监工专用)

package/skills/sps-pipeline/SKILL.md

@@ -52,14 +52,19 @@ Re-run safe: `sps setup --force` keeps existing values as defaults.
 Open `sps console` → `/projects/new` → fill form → submit. Form provides:
 - Project name + repo path
 - Git toggle (worker commits + pushes? off for non-code projects)
+- **清单验收 toggle**: 开启 → conf 写 `SPS_REVIEW="on"`,每卡完成后独立 reviewer 按检查清单逐条验收
 - **Wiki toggle** (v0.51+): scaffolds `wiki/` + writes `WIKI_ENABLED=true` to conf
 - Merge branch, max workers, ACK timeout, Matrix room
 
 ### Option B — Interactive CLI
 ```bash
-sps project init <name>      # asks the same questions on tty
+sps project init <name>      # asks the same questions on tty(含「启用清单验收? (y/N)」一问)
 ```
 
+> **⭐ 建项目时务必确认「要不要开清单验收」**:开了(`SPS_REVIEW=on`)才会在每卡完成后派独立 agent
+> 按卡内 `## 检查清单` 逐条审核(不过自动插修正卡)。你(对话 agent)通过 `create_project` 建项目前,
+> **必须先问用户要不要开**,再据答传 `enableReview`。见第 5 节「验收清单」的写法规范。
+
 ### What gets created
 
 ```
@@ -219,11 +224,50 @@ Stop hook reads this to detect which card the worker just finished.
 sps card add <project> "Title" "Description"
 sps card add <project> "T" "D" --skill python,backend
 
+# 带验收清单（审核点）—— 见下方「验收清单」小节
+sps card add <project> "实现登录" "描述…" --checklist "点1;点2;点3"
+
+# 插队 / 修正卡 —— 建 Backlog + 优先跑（PRIORITY），排到其它排队卡之前
+sps card insert <project> "先修这个" "描述…"
+
 # 想暂存（让用户审核 / 自己稍后拖派发）
 sps card add <project> "Title" "Description" --draft
                                   # → 卡进 Planning，等手动拖到 Backlog
 ```
 
+### 验收清单（审核点）—— 建卡时写，决定这张卡「怎样算做完」
+
+**这是建卡 agent 的一等职责。** 开了 `SPS_REVIEW=on` 的项目：卡带 `## 检查清单` = **开审核**（per-card 开关，无清单就不审）。worker 干完后，一个**独立第三方 reviewer**（OpenAI 角色，去相关盲点）会**对着真实项目产物逐条核验**这份清单：
+
+- **全过** → 卡留 Done。
+- **有不过** → 自动 `card insert` 一张**修正卡**（优先跑、无清单）让下一轮 worker 先修；本卡照常 Done。
+- **修正卡无清单 → 不再触发审核** → 不会无限打回（结构性终止）。
+
+所以清单 = 这张卡的**验收标准**，由**你（建卡的 agent）在建卡时写**：
+
+```bash
+sps card add <project> "实现登录" "描述…" --checklist "点1;点2;点3"
+#                                         分隔符：;  ／  ；  ／  换行
+```
+
+**怎么写好每一条**（reviewer 只读代码、不跑程序、看真实文件——写得能被**静态核验**才有用）：
+
+1. **一条一件事**，能明确判过/不过。别把多件事塞一条。
+2. **落到可核验的产物**：某文件/函数/组件存在、实现了某行为、某配置/文案就位；尽量给「去哪看」。
+3. **客观判据**：pass 标准写死（「有 X 且做到 Y」），不用「够好/合理/流畅/好玩」这类主观词。
+4. **运行时项给静态替身或标注**：真跑才知道的（手感/动画/音效），写成代码层可验的替身（「受伤时 `hp -= dmg` 且 UI 绑定 hp」），或标 `[需运行时]`（reviewer 会保守判 fail）。
+5. **数量克制**：3–7 条，覆盖「这卡算做完」的关键面，不穷举、不凑数。
+6. **与卡的 skill 对齐**：卡指定了 skill（SOP）时，验收点体现该 SOP 的硬要求（reviewer 也会加载同一 SOP 对照）。
+7. **用户可见 > 内部实现**（纯重构卡除外）。
+
+| ❌ 空泛（reviewer 没法判） | ✅ 可核验 |
+|---|---|
+| 登录功能好用 | `login()` 对空用户名/密码返回明确错误文案（非崩溃/非静默） |
+| 游戏好玩 | `[需运行时]` 点开始进入战斗；静态替身：`StartButton.onClick` 绑定 `scene.load('battle')` |
+| 性能好 | 长列表用虚拟滚动（`react-window`），一次渲染项数 ≤ 可视区 |
+
+> 清单写空泛 = 审核白做。**这一步的质量决定整条审核链的价值**——宁可少写几条可验的，也别堆一堆没法判的。
+
 ### View
 
 ```bash
@@ -248,6 +292,8 @@ sps reset <p> --all                # full reset incl. Done
 | Label | Meaning | Who sets |
 |---|---|---|
 | `AI-PIPELINE` | "SPS pipeline 卡" 的标记（v0.51.9+ 不再触发任何自动行为，仅识别） | `sps card add` 自动加 |
+| `PRIORITY` | 插队 —— 抢卡时排到同队列其它卡之前 | `sps card insert` / reviewer 插修正卡 |
+| `REVIEWED` | 该卡验收清单已被 reviewer 审过（幂等，不重审） | ReviewEngine（`SPS_REVIEW=on`） |
 | `STARTED-<stage>` | ACK signal — Claude received the prompt | UserPromptSubmit hook |
 | `COMPLETED-<stage>` | Worker finished a stage | Stop hook |
 | `CLAIMED` | StageEngine reserved a worker slot | Engine |
@@ -377,6 +423,7 @@ Live at `~/.coral/projects/<name>/conf` (shell `export VAR="value"` syntax).
 | `WORKER_ACK_TIMEOUT_S` | `300` | Wait for STARTED-<stage> label after dispatch (5min, raised in v0.50.24) |
 | `WORKER_ACK_MAX_RETRIES` | `1` | ACK timeout retry count |
 | `MONITOR_AUTO_QA` | `true` | Auto-advance to QA on stale runtime |
+| `SPS_REVIEW` | unset (off) | `on` 开清单验收：卡带 `## 检查清单` → worker 完成后独立 reviewer 逐条审 → 全过留 Done / 有不过自动插修正卡。见第 5 节「验收清单」 |
 | `CONFLICT_DEFAULT` | `serial` | Fallback for cards without `conflict:` label |
 | `MATRIX_ROOM_ID` | — | Project-level Matrix override |
 | `WORKTREE_DIR` | `~/.coral/worktrees/<p>` | Worker scratch space |

package/{monitor-skills → skills}/visual-rubric/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: visual-rubric
-description: 监工视觉评分卡——按"当前任务该看到什么"分阶段评判游戏截图,避免对早期框架任务强求"实战可玩"导致死循环。
-audience: orchestrator
+description: 审核视觉评分卡——按"当前任务该看到什么"分阶段评判游戏截图,避免对早期框架任务强求"实战可玩"导致死循环。
+audience: reviewer
+tags: [reviewer, visual]
 ---
 
 # 视觉评分卡(游戏类,截图评审专用)