@nathan33/nao-skill 0.21.2 → 0.21.3

package/.agents/checklists/comm-templates.md

@@ -22,11 +22,13 @@ description: 派发消息与回执模板（按需，派发/回执前读取）
 ## 回执 done(lite)：默认（无阻塞、无风险的常规任务，单行）
 
 ```text
-[编号] done(lite) | <role> | 清单：未过<项 或 无> | 测试：<命令> exit=<n> <文件数>/<例数>/<红数> | 变更：<f1,f2（>3 个写前 3 + "等 N 个"）> | 遗留：<无 | n 项 → 台账|tasks-state|Issue|接受(到期)> | commit=<短 hash 或 —> | 详情：docs/reports/<编号>.md
+[编号] done(lite) | <role> | 清单：未过<项 或 无> | 测试：HEAD=<跑门禁时短 sha> · 工作区=<静默|非静默(原因)> · <命令> exit=<n> <文件数>/<例数>/<红数>（每个计数数字后跟「命令 → 输出」） | 变更：<f1,f2（>3 个写前 3 + "等 N 个"）> | 遗留：<无 | n 项 → 台账|tasks-state|Issue|接受(到期)> | commit=<交付提交短 hash，≠ 门禁 HEAD；无则 —> | 详情：docs/reports/<编号>.md
 ```
 
 > `commit=`（仅 git 流程任务）：work 分支最新提交短 hash，便于 PM 核对归因（commit.md 约定）；无 push/纯文档任务写 `commit=—`。
 > `遗留：` 取值枚举 `无 | <n> 项 → <台账|tasks-state|Issue|接受(到期)>`；零遗留写 `无`，禁省略字段（三出口定义见 @.agents/skills/task-completion.md §四）。
+> **`测试：` 段三件套（静默工作区 / HEAD sha / 命令 + 输出）口径单源见 @.agents/common/output-format.md「回执硬性」第 3 条** —— 本文件只给可复制形态，**不复写三件套全文**（PM / QA / RD 三侧同源）。
+> **`HEAD=` ≠ `commit=`**：前者 = **跑门禁时**的 HEAD（数字的归属），后者 = **交付提交**（归因）；门禁后又补提交时两者必然不同 —— 混用即「同一命令两种结论」的根源。
 
 ## 回执 done(full)：出现阻塞/风险/需决策，或 PM 指定
 
@@ -35,8 +37,8 @@ description: 派发消息与回执模板（按需，派发/回执前读取）
 摘要：≤150字
 清单：已核对 checklists/<role>.md；未过：<项 或 无>
 变更：<文件/模块级>
-测试：<命令 + exit code + 文件数/例数/红数（或错误数）>
-commit：<短 hash 或 —>
+测试：HEAD=<跑门禁时短 sha> · 工作区=<静默（`git status --porcelain` 空 + 本会话独占 worktree）| 非静默(原因)> · <命令> exit=<n> · <文件数>/<例数>/<红数>（每个计数数字后跟「命令 → 输出」）
+commit：<交付提交短 hash（**≠ 门禁 HEAD**；本分支最新交付提交）或 —>
 遗留：<无 | n 项 → 台账|tasks-state|Issue|接受(到期)>（每条附出处与 owner；接受类必须带到期日）
 风险/阻塞：<无 或 列出>
 详情：<路径>

package/.agents/checklists/pm.md

@@ -107,7 +107,7 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] `gh` 可用则已用 `gh`，降级已注明；发布后事实（含 `tasks-state` 版本/Tag 行）的**落地时机与工作区纪律见 `github-flow.md` BR5**（单源指针，本清单不复写命令细节）
 - [ ] 任务 DoD 四类已随**开工确认卡**逐任务实例化（产物路径 / 可执行验证判据 / 遗留项 / 交接），验收按同一份核
 - [ ] 回执含 `遗留：` 字段且遗留项已**三出口**收口（关闭 / 接受含到期日 / 转办；零遗留显式「无」，可执行项已进 `tasks-state` 待派发队列）
-- [ ] **计数类数字必须 PM 自证一条命令** —— 用例数 `bash tests/t4/run.sh --list | tail -n +2 | wc -l`（**`--list` 首行是表头**，裸 `wc -l` = 19 会多算 1 —— 这条命令本身也已实测校准）· 断言数（run.sh 汇总 PASS 数或 `grep -c '\[PASS\]'`）· `files=` 口径（`check` 输出 vs `find "$NAO_SKILLS/.agents" -type f | wc -l`）；**回执与命令输出不一致时以命令为准**，并当场订正回执/文档（来源：L1 复盘 `docs/reports/2026-11-01-T536-retro.md`）
+- [ ] **计数类数字必须自证一条命令** —— 用例数 / 断言数 / `files=` / 行数的**取数命令单源见 `tests/README.md`「取数命令四条」**（本清单**不复写命令**；PM / QA / RD 三侧同源）；回执须同时给 **命令 + 输出 + HEAD sha + 静默工作区状态**（三件套见 @.agents/common/output-format.md「回执硬性」第 3 条）；**回执与命令输出不一致时以命令为准**，并当场订正回执/文档（来源：L1 复盘 `docs/reports/2026-11-01-T536-retro.md`）
 - [ ] 通过上面全部红线
 
 ## 会话回收 / 收窗核对（验收通过后 / 手工关窗前）

package/.agents/checklists/qa.md

@@ -20,7 +20,7 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 - [ ] 只测主路径，无异常/边界覆盖？
 - [ ] 未 Verify 就关闭缺陷？
 - [ ] 定位被测代码/受影响测试未走三段阶梯：原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段（口径见 @.agents/skills/codegraph.md）？（回退 grep 需注明原因）
-- [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`；**计数类数字（例数/文件数/断言数）口径单源见 `tests/README.md`「计数可见」**，不以最大编号推断）
+- [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`；**计数类数字（例数/文件数/断言数/行数）取数命令口径单源见 `tests/README.md`「取数命令四条」**，不以最大编号推断；回执须带 **HEAD sha + 静默工作区**（`git status --porcelain` 空、无并行会话同 worktree 跑门禁），缺任一项该数字不得作验收依据 —— 三件套见 @.agents/common/output-format.md「回执硬性」第 3 条）
 - [ ] 视觉/UI 呈现类验证启动了浏览器自动化（无头浏览器/截图对比）？（应产出用户验收清单交用户人工，见 skills/test-design.md「视觉/UI 呈现验证」）
 - [ ] 含 UI 呈现的交付未产出用户验收清单（测什么/怎么操作/预期结果/对应 AC）？
 

package/.agents/checklists/rd-infra.md

@@ -16,7 +16,7 @@ description: 工程基座交付核对清单（按需，交付前读取）
 - [ ] **不自验自己的守卫**（验收由 `qa`/`pm` 独立执行）
 - [ ] 不写死仓库名/相对路径/包管理器（跨项目兼容）
 - [ ] 未改项目 `AGENTS.md` 红线、业务源码/测试断言、他人未提交文件
-- [ ] 全范围门禁 rc=0 且回执**精确数字**（命令 + exit code + 条数/文件数）
+- [ ] 全范围门禁 rc=0 且回执**精确数字**（命令 + exit code + 条数/文件数）；**计数类数字（用例数/断言数/`files=`/行数）取数命令单源见 `tests/README.md`「取数命令四条」**（本清单不复写命令），回执须带 **HEAD sha + 静默工作区**（`git status --porcelain` 空 + 无并行会话同 worktree 跑门禁），缺项则该数字不作验收依据
 
 ## 幂等 / 权限 / 自证 速查
 

package/.agents/common/intercom-protocol.md

@@ -87,7 +87,7 @@ bash .agents/scripts/nao-fleet.sh check
 - **两级回执**（模板见 @.agents/checklists/comm-templates.md，回执前读取）：默认 `done(lite)` 单行（含门禁精确数字）；**出现阻塞/风险/需决策或 PM 指定时用 `done(full)`**。前缀 `[编号] done` 不变（PM 追讨/红线均按 `done` 匹配）。
 - 每次派发的任务（含架构评审）**必须以终态回执结束**：按 @.agents/checklists/comm-templates.md `[编号] done(lite|full) | <role>`，经 intercom `send` 回 PM。
 - **回执 = 已核对清单**：回执须声明已读 `checklists/<role>.md` 并逐项核对（未过项必须列出）；未核对不回执。
-- **回执「测试」字段 = 全量门禁精确数字（硬性）**：必须给 `命令 + exit code + 文件数/例数/红数（或错误数）`；**只跑子目录、或只写「pass」不算回执** → PM 打回。**跑子目录不算验收**：全范围口径见项目 `AGENTS.md`。
+- **回执「测试」字段 = 全量门禁精确数字（硬性）**：必须给 `命令 + exit code + 文件数/例数/红数（或错误数）`，并含**三件套**（**静默工作区** / **HEAD sha** / **命令 + 输出** —— 口径单源见 @.agents/common/output-format.md「回执硬性」第 3 条，本处不复写；可复制形态见 @.agents/checklists/comm-templates.md）；**只跑子目录、或只写「pass」不算回执** → PM 打回。**跑子目录不算验收**：全范围口径见项目 `AGENTS.md`。
 - 短消息（≤150 字摘要 + 结论/决策点 + 详情落盘路径）；**禁止**把长报告全文 `send` 污染线程（output-format「反模式」）。
 - arch 评审回执至少含：可行性结论、ADR 路径、待 PM 拍板决策点。
 - `send` 失败（目标离线 / 会话不存在）→ 尝试 `ask`；仍失败 → 降级交付并注明，见「降级」。

package/.agents/common/output-format.md

@@ -30,7 +30,11 @@ description: 全角色共用输出与沟通红线（常驻；模板按需）
 
 1. 前缀 `[编号] done` 不变（PM 追讨与红线均按 `done` 匹配）；**派发时由 PM 声明级别，未声明默认 `done(lite)`**。
 2. 回执即声明已读 `checklists/<role>.md` 并逐项核对（未过项必须列出）——**未核对不回执**。
-3. 「测试」必须给**全量门禁精确数字**（命令 + exit code + 文件数/例数/红数或错误数）；只跑子目录或只写「pass」不算回执 —— PM 打回（见 intercom-protocol「终态回执」）。
+3. 「测试」必须给**全量门禁精确数字**（命令 + exit code + 文件数/例数/红数或错误数）；只跑子目录或只写「pass」不算回执 —— PM 打回（见 intercom-protocol「终态回执」）。**三件套缺一即打回**：
+   - **静默工作区**：门禁须在**静默工作区**执行 —— `git status --porcelain` 为空，且同一 worktree **无其他会话正在跑门禁**。不满足 ⇒ 回执显式标注「非静默（原因）」，**该数字不得作为验收依据**。
+   - **HEAD sha**：必须记跑门禁时的 `HEAD`（短 sha 可）；无 HEAD 的数字不可复核 —— 「同一命令两种结论」时无法判定是代码差异还是环境差异。
+   - **命令 + 输出**：每个计数类数字一律给「**命令 + 输出**」（输出原文，或摘要 + 可直接复跑的命令），**禁「我数了 N」**；用例数 / 断言数 / `files=` / 行数的取数命令**单源见 `tests/README.md`「取数命令四条」**，本处不复写命令。
+   - **不合格回执（据此打回）**：`测试：npm test 通过，t4 21 个用例全绿` —— 无 HEAD、无命令、无工作区状态，且「21」来自最大编号（实测 20）⇒ **打回**，补齐 HEAD + 静默工作区状态 + 命令与输出后重报。
 4. **有阻塞/风险/需决策 → 必须 `done(full)`**（`lite` 不得吞掉需 PM 拍板的事）；详细全文落盘 `docs/reports/<编号>.md`，**禁止**把长报告贴进线程。
 
 ## 反模式（禁止）

package/.agents/scripts/nao-fleet.sh

@@ -100,7 +100,15 @@ TMUX_MIN_PANE_WIDTH="${NAO_TMUX_MIN_PANE_WIDTH:-$TMUX_MIN_PANE_WIDTH_DEFAULT}"
 # T517：派生宿主窗口 ID（归一化 @<window_id>；空 = 定位失败 ⇒ 该角色 pane warn+skip，禁无 -t 续建）
 HOST_WINDOW=""
 # T536：本轮真正创建成功的 pane 数（>0 ⇒ ensure 收尾打印**恰一行**就绪提示；跳过/失败分支恒 0，BR3/AC4）
+# T539：三态计数（成功 / 跳过 / 失败）—— 每个 ensure 目标恰落一类，合计 = 目标数（BR3 计数守恒）
 SPAWN_OK=0
+SPAWN_SKIP=0
+SPAWN_FAIL=0
+# T539/BR2：spawn_tmux 的**显式**结果契约（返回值；调用方禁用「没打印就是成功」这类隐式约定）：
+#   0 = 成功（pane 已创建）· 2 = 跳过（宿主窗口未解析，未创建）· 3 = 失败（split-window 非 0，未创建）
+SPAWN_RC_OK=0
+SPAWN_RC_SKIP=2
+SPAWN_RC_FAIL=3
 # check 输出契约：默认摘要 2 行（摘要行 + codegraph 状态行，四态之一），-v 展开完整报告（六态全展开）；失败始终展开
 VERBOSE=false
 # close 的在跑 turn 判定（pi 默认状态行：Working (esc to interrupt) / Thinking... / Retrying / Compacting）
@@ -1059,17 +1067,20 @@ spawn_tmux() {
   local wrapped="bash -lc $(printf %q "$inner")"
   # T517：目标显式化——HOST_WINDOW 解析失败时此处已由解析处 warn（每 run 一次），
   #   跳过该 pane；禁止无 -t 续建（tmux 会落「当前窗口」= 用户视图，即缺陷根因）。
-  [[ -n "$HOST_WINDOW" ]] || return 0
+  # T539：显式回报「跳过」（不再用 return 0 冒充成功）。
+  [[ -n "$HOST_WINDOW" ]] || return "$SPAWN_RC_SKIP"
   # 窄窗口/宿主上限会让 split-window 失败（no space for new pane，含宿主窗已关竞态）；
   # 捕获后 warn 并继续，不因单个 pane 失败中断整轮 ensure。
+  # T539：显式回报「失败」；两条 warn 是诊断信息，保留不合并。
   local serr
   if ! serr=$(tmux split-window -h -t "$HOST_WINDOW" "$wrapped" 2>&1); then
     warn "pane 创建失败（宿主窗口 $HOST_WINDOW 过窄/已关或已达上限）：${serr:-<no message>}"
     warn "  已跳过该 pane，其余角色继续拉起；可放大窗口后重跑 ensure"
-    return 0
+    return "$SPAWN_RC_FAIL"
   fi
-  SPAWN_OK=$((SPAWN_OK + 1))   # T536：真创建成功才计数（就绪提示的唯一开关）
-  apply_tmux_layout
+  # 布局是尽力而为（内部各 tmux 调用已 || true）；布局成败不影响「pane 已创建」这一结果。
+  apply_tmux_layout || true
+  return "$SPAWN_RC_OK"
 }
 
 # 组装系统提示文件：角色卡 + 环境锚点（本机绝对路径，供跨仓库会话解析 @ 引用失败时兜底）
@@ -1102,9 +1113,17 @@ spawn_one() {
   #   不用 setsid：macOS 无该 bin，`… || true` 会静默跳过清理（BR1 缩水）。清理窗口 60s 不缩短。
   bash -c 'sleep 60; rm -f -- "$1"' _ "$prompt_file" >/dev/null 2>&1 </dev/null & disown 2>/dev/null || true
 
-  # 拉起（pane 级失败 = warn + 跳过该角色，D-A）；成功后打印「已拉起」
-  spawn_tmux "$name" "$inner"
-  log "[tmux] 已拉起 $name @ $repo${model:+（model=$model）}（layout=$TMUX_LAYOUT）"
+  # 拉起：spawn_tmux 以**显式三态**回报（T539/BR2）；每目标恰一行结果行：
+  #   成功 → 唯一一条 `[tmux] 已拉起 …`（内容逐字不变，BR1）· 跳过/失败 → 不打印成功行（BR2）。
+  #   `|| rc=$?` 是 set -e 下的必需写法（|| 列表豁免 errexit）；函数返回值即结果契约。
+  local rc=0
+  spawn_tmux "$name" "$inner" || rc=$?
+  case "$rc" in
+    "$SPAWN_RC_OK")   SPAWN_OK=$((SPAWN_OK + 1))
+                      log "[tmux] 已拉起 $name @ $repo${model:+（model=$model）}（layout=$TMUX_LAYOUT）" ;;
+    "$SPAWN_RC_SKIP") SPAWN_SKIP=$((SPAWN_SKIP + 1)) ;;
+    *)                SPAWN_FAIL=$((SPAWN_FAIL + 1)) ;;   # 3 = fail；未知值按失败处理（宁可少报成功）
+  esac
 }
 
 # ---------------------------------------------------------------------------
@@ -2055,6 +2074,7 @@ cmd_ensure() {
     if (( ! seen )); then codegraph_state "$repo" 1 "$(basename "$repo")"; cg_done+=("$key"); fi
     if [[ "$force" != "true" ]] && running "$disp" "$repo"; then
       warn "$disp 已在运行（终端标题/名册命中），跳过；确需重开请加 --force"
+      SPAWN_SKIP=$((SPAWN_SKIP + 1))   # T539/BR3：跳过也计入摘要（且不加成功行）
       continue
     fi
     if [[ -n "${t_cards[$i]}" ]]; then
@@ -2063,10 +2083,10 @@ cmd_ensure() {
       spawn_one "$disp" "$repo" "$model"
     fi
   done
-  # T536/BR3/AC4：仅当本轮真拉起过 pane 才打印**恰一行**就绪提示；
-  #   跳过（已在运行）/失败（无宿主窗口、分屏失败）分支不打印；既有行内容与顺序不变（只追加末尾一行）。
-  if (( SPAWN_OK > 0 )); then
-    log "已拉起 ${SPAWN_OK} 个会话；就绪后在线状态用 nao-fleet.sh status 查看"
+  # T536/BR3/AC4 + T539/BR3：**恰一行**摘要，三类计数（成功/跳过/失败）；三类全 0 不打印（与现状一致）。
+  #   前缀「已拉起 N 个会话」保留（既有断言与用户习惯依赖），计数细化追加在括号内（BR6 旧→新对照见 T539 报告）。
+  if (( SPAWN_OK + SPAWN_SKIP + SPAWN_FAIL > 0 )); then
+    log "已拉起 ${SPAWN_OK} 个会话（成功 ${SPAWN_OK} / 跳过 ${SPAWN_SKIP} / 失败 ${SPAWN_FAIL}）；就绪后在线状态用 nao-fleet.sh status 查看"
   fi
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathan33/nao-skill",
-  "version": "0.21.2",
+  "version": "0.21.3",
   "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
   "type": "module",
   "bin": {