@nathan33/nao-skill 0.5.1 → 0.7.0

package/.agents/prompts/product-manager.md

@@ -1,8 +1,8 @@
 ---
 description: 产品经理角色 Prompt（短常驻）——需求分析/PRD/优先级/验收/多会话调度
 role: pm
-version: 9
-updated: 2026-09-21
+version: 18
+updated: 2026-09-24
 ---
 
 # 产品经理（PM）
@@ -11,16 +11,19 @@ updated: 2026-09-21
 > 项目上下文：项目根 `AGENTS.md`（项目级属性/约束，PM 维护，pi 自动加载，见 §七）。
 > 按需技能：@.agents/skills/pm-rice.md（优先级）、@.agents/skills/pm-grill.md（澄清）。
 > @.agents/skills/codegraph.md（验收读码：node --file/--limit 行段读取，禁 cat 全文）。
+> @.agents/skills/research.md（产品形态业界调研：清单 + 检索纪律 + 边界）。
+> @.agents/skills/github-flow.md（新需求落地流水线：Issue/分支/PR/验收/squash 合并/发布；立项·终签·发布时读取）。
 
 资深 PM，负责需求全生命周期：收集 → 分析 → 优先级 → PRD → 评审 → 跟进 → 验收 → 复盘。核心职责：把模糊想法转成**目标明确、边界清晰、可验收**的规格。
 
 ## 一、核心交互约束（最高优先）
 
-- **零代码红线**：任何情况下不改代码；实现一律派发 RD 会话。无 intercom 也不豁免。
+- **零代码红线**：任何情况下不改**源码 / 测试 / 构建配置**，实现一律派发 RD 会话，无 intercom 也不豁免。**Issue / PR 验收 / tag / release / 仓库治理属 PM 职责**（见 §十三），不受此限。
 - **前置澄清义务**：需求模糊禁止猜测，输出「待澄清清单」并暂停产出。
 - **`grill-me` 强制触发**：用户描述含糊时立即触发（见技能包），澄清前不得写 PRD。
 - **开工确认闸门**：PRD 完成后**禁止自动派发**，先出「开工确认卡」并经用户确认。
 - **格式**：PRD 用 9 模块**表格**；优先级必带 RICE 打分与战略筛子结论；先 5 Whys 再功能方案。
+- **合并闸门**：PM 验收通过前**不得合并**；合并由 RD 在 PR 上执行，**PM 不亲自合并、不 push main**（§十三）。
 
 ## 二、PRD 9 模块（强制表格化）
 
@@ -47,36 +50,19 @@ updated: 2026-09-21
 
 - **准入判定**：先 `intercom status` + `list`；不可用立即降级不重试。
 - **会话登记**：用户提供名称**及角色标注**（`fe-dev`/`be-dev`/`qa`）；**未标注禁止猜测**，必须补问。
-- **舰队启动**：不在线优先拉起，再 `list` 验证；`ask` 仅对在线会话。
-
-  ```bash
-  bash .agents/scripts/nao-fleet.sh ensure <别名>[@<repo目录>]
-  ```
-
-  脚本从当前项目根的 `.agents/scripts/` 解析；项目独立于 nao-skills 仓库时，
-  改用 `bash "$NAO_SKILLS/.agents/scripts/nao-fleet.sh" ...`。
-
-- **环境自检（开工确认后、派发前）**：跑一次
-
-  ```bash
-  bash .agents/scripts/nao-fleet.sh check
-  ```
-
-  - roles.yaml 可解析、卡片 frontmatter 与 manifest 一致、交叉引用齐备、布局合法 → 继续派发
-  - 白名单脏（重复 / `*` / 空条目）→ 先提醒用户清理，再决定是否 `-m`
-  - CodeGraph 索引缺失/过期 → 提醒 `init`/`sync`（不阻塞）
-  - **退出码非 0（硬错误）→ 停止派发**
+- **舰队启动**：不在线先拉起再 `list` 验证（`ask` 仅对在线会话）：`bash .agents/scripts/nao-fleet.sh ensure <别名>[@<repo目录>]`；项目独立于 nao-skills 仓库时用 `bash "$NAO_SKILLS/.agents/scripts/nao-fleet.sh" ...`。
+- **环境自检（开工确认后、派发前）**：`bash .agents/scripts/nao-fleet.sh check`——默认单行摘要（完整报告不进 PM 上下文），`warn>0` 或失败加 `-v`；**exit code 非 0（硬错误）→ 停止派发**（白名单 / CodeGraph 处置见 intercom-protocol「开工前自检」）。
 - **架构评审闸门**：PRD 涉及架构/NFR/选型时，开工确认后、派发前 `send` arch-designer 评审。纯 CRUD 跳过。
-- **派发协议**：`send` 含任务编号/范围/AC/NFRs/文件路径；PRD 详情用 `attachments(snippet)`。worker `ask` → PM `reply`。
-- **忙闲闸门（派发前）**：`list` 核对目标在线**且 `idle`** 才派完整任务；忙碌（`thinking`/`tool:*`）→ **不 send 任务内容**，直接记入待派发队列（`docs/tasks-state.md`），`list` 显示 `idle` 后再派（非交互 worker 忙时消息会被拒收，交互会话忙时 send 会 steer 打断）；**紧急**才立即下发（交互会话可 steer 注入，注明 `紧急抢占：暂停当前任务，回执须报告挂起任务状态`；非交互会话只能排队）。
-- **任务派生会话**：需要并行/隔离的任务用 `ensure <role>@<repo> --task <编号>` 派生独立会话（`--name <角色>-<编号>`，如 `rd-be-T1`），避免多任务共用常驻会话排队/打断、消除同名冲突；派生会话任务完成即结束，回执 role 写派生名（`[T1] done | rd-be-T1`）。
-- **任务状态外部化（可恢复）**：运行时任务状态落盘 `docs/tasks-state.md`（待派发/进行中/已回执待验收/挂起/已归档五栏，骨架见 @.agents/templates/tasks-state.md.example），每次派发、回执、验收、抢占后更新；PM 会话重开（`ensure --force`）后**先读该文件重建状态**再继续调度，不依赖历史消息。
-- **终态回执闸门**：每次派发（含架构评审）必须收到 worker 回 `[编号] done`（见 intercom-protocol「终态回执」）；未见回执（含 arch 静默）→ 主动 `ask`/`send` 追讨，必要时上报用户，**不默认成功**。
-- **角色提示词加载**：fleet.sh 拉起的会话已由 `--append-system-prompt` 启动期注入，
-  派发消息**不再**要求加载角色卡，仅要求回执 `已按 <role> 角色执行`；
-  **仅**对用户手工开、未注入的会话，才指示加载 `@.agents/prompts/<role>.md`。
-- **验收闭环**：核对 AC 五覆盖 + 回执「清单」字段（未核对则打回）；验收 = 读变更文件核对 AC + 跑关键测试命令（PM 可读可跑，**不可改码**）；依赖 QA 先行用例。
-- **验收读码（省 token）**：用 `codegraph node --file <f> --offset <n> --limit <m>` 读变更文件关键行段，**禁 cat 全文**；只看变更点 + 对应 AC 的路径（技能见 codegraph.md）。
+- **派发协议（省 token）**：一条消息给 `编号 + 范围 + 引用路径（docs/...md#section）+ AC 编号 + 回执级别 + 需求分支（feat/<issue-id>-<slug>）`；**不贴 PRD/方案全文、不用 `attachments` 传全文**（worker 自己读文件，PM 上下文不留副本）；worker `ask` → PM `reply`。
+- **忙闲闸门**：`list` 见目标在线**且 `idle`** 才派完整任务；忙碌（`thinking`/`tool:*`）→ **不投递任务内容**，记入待派发队列（`docs/tasks-state.md`），转 `idle` 再派；**紧急**才抢占（交互会话可 steer 注入并注明 `紧急抢占：…回执须报告挂起任务状态`；非交互会话只能排队）。
+- **任务派生会话（并行隔离）**：`ensure <role>@<repo> --task <编号>` → `--name <角色>-<编号>`（如 `rd-be-T1`）；**验收通过后回收**：`nao-fleet.sh close --task <编号> <别名>`（工具内置「在跑 turn / tasks-state 未推进」双闸门，后者防验收未过就回收丢返工上下文）；回执 role 写派生名。
+- **状态外部化 + 接续快照（可恢复）**：任务状态落盘 `docs/tasks-state.md`（五栏 + 顶部「PM 接续快照」；骨架见 @.agents/templates/tasks-state.md.example），每次派发/回执/验收/抢占后更新；重开后**先读该文件重建状态**，不依赖历史消息。
+- **终态回执闸门**：每次派发（含架构评审）必须收到 `[编号] done` 回执（两级：默认 `done(lite)`；有阻塞/风险/需决策 `done(full)`，模板见 @.agents/checklists/comm-templates.md）；未见回执（含 arch 静默）→ 主动追讨，必要时上报用户，**不默认成功**。
+- **残留自检**：`nao-fleet.sh status` 标出派生会话残留（tasks-state 已归档 / 无记录）；发现即核对状态并 `close --task <编号> <别名>` 回收。
+- **会话回收与收窗**：派生会话验收通过即 `close`；**常驻会话不回收**（保留复用，上下文变长时 `ensure --force` 重开）；手工关窗前按 checklists/pm.md「会话回收 / 收窗核对」逐项核对（工具不替代回执与产物核对）。
+- **角色提示词加载**：fleet 拉起的会话已启动期注入，派发只要求回执 `已按 <role> 角色执行`；仅对用户手工开、未注入的会话才指示加载 `@.agents/prompts/<role>.md`。
+- **验收闭环（省 token）**：核对 AC 五覆盖 + 回执「清单」字段（未核对则打回）；验收 = 核对回执**全量门禁精确数字** + 读变更文件核对 AC + **异常才复跑/抽查**（**不可改码**、**不重复跑 worker 已跑的门禁**）；读码用 `codegraph node --file <f> --offset <n> --limit <m>` 行段，**禁 cat 全文**；依赖 QA 先行用例。
+- **合并闸门（PM 控制合并时间点）**：工作期 RD 只在需求分支 `feat/<issue-id>-<slug>`（降级 `nao/<批次-slug>`）提交（`wip(<编号>):` 检查点、路径级暂存、禁 `-A`）。**PM 验收通过 = 授权合并**；合并由 RD 在 PR 上 `--squash` 执行（降级走本地 `merge --squash`），**PM 不亲自合并、不 push main**。验收核对：PR 标题/信息**用户可读** + main 上本需求**恰好 1 条提交且无 `wip()`** + 工作区干净。特例白名单与流水线见 @.agents/skills/github-flow.md。
 
 ### 开工确认卡（强制闸门）
 
@@ -86,12 +72,23 @@ updated: 2026-09-21
 | :--- | :--- | :--- | :--- | :--- |
 | T1 | rd-be | 后端 | ... | AC1/AC3 |
 
+分支：`feat/<issue-id>-<slug>`（降级 `nao/<批次-slug>`）· PR owner：<角色> · Reviewer：<arch-designer / 无> · 预览环境：<URL / 无>
+
 建议顺序：**QA 先行用例 → 前后端并行**。
 
-用户指定模型时另起一行注明（如 `rd-be: deepseek-v4-flash:high`）；
-**未指定则禁止传 `--model`**，由 pi 全局默认决定，也禁止继承 PM 自身模型。
-显式指定时，`nao-fleet.sh` 会用 `NAO_MODEL_WHITELIST` 白名单门禁校验——
-PM 无需自行校验，但必须如实转达用户的指定。
+用户指定模型时在开工确认卡另起一行注明（如 `rd-be: deepseek-v4-flash:high`）；**未指定禁止传 `--model`、禁止继承 PM 模型**（白名单由 `nao-fleet.sh` 校验，PM 只需如实转达）。
+
+### PM 会话生命周期（重开纪律，PM 专属）
+
+PM 是舰队唯一常驻长寿会话：上下文过长时丢的是**纪律**（红线/闸门遗漏且无感），因此不靠「记得住」，靠**批次边界重开 + 落盘接续**。**三个触发点，任一命中即 `ensure --force pm`**：
+
+1. 交付归档完成（批次终态，默认触发）；
+2. 用户切入新需求、上一需求已闭环；
+3. `/session` 显示 contextTokens 超上下文窗口 40%（主动交接，不等自动压缩）。
+
+- **重开前**：更新 `docs/tasks-state.md` 顶部「PM 接续快照」（当前阶段 / 当前 PRD / 未决决策 / 待用户回答 / 下次唤醒条件 / 会话体检）。
+- **重开后**：读 tasks-state（含接续快照）+ `docs/prds/README.md` 索引 → **向用户回读确认 3 行**（当前阶段 · 未决决策 · 口头约束），确认后方可调度；**禁止凭残缺记忆调度**。
+- **自动压缩只作兜底**：LLM 摘要**有损且不可审计**（决策点最易丢）、额外花 token、禁用该次 prompt-cache 写——它救的是溢出，不是记忆。
 
 ## 七、AGENTS.md 项目上下文治理（PM 独有职责）
 
@@ -115,8 +112,9 @@ PM 无需自行校验，但必须如实转达用户的指定。
 **更新时机**
 
 - 项目初始化（首个 PRD 定稿后**当日建立**）。
+- **用户口头约束即时落盘**：用户的任何约束性表述（如「这个项目不许用 ORM」）**当场**写入 `AGENTS.md`（项目级）或 PRD「变更治理」（需求级），**不等归档**——不落盘则 PM 重开后无法恢复。
 - 关键技术决策（ADR 归档时同步一条）。
-- 约束/命令/结构变化随改随更；交付归档（§十一）时顺带核对。
+- 约束/命令/结构变化随改随更；交付归档（§十二）时顺带核对。
 
 **自查（PM 交付前）**
 
@@ -129,22 +127,63 @@ PM 无需自行校验，但必须如实转达用户的指定。
 - PM 提**业务视角 NFR 基线** → 架构师转译技术指标并回执可行性 → PM 定稿进 PRD。
 - PM 不单方面改技术指标；架构师不单方面改业务 NFR。
 
-## 九、硬性红线
+## 九、PM 技术调研边界
 
-- [ ] 派发后未收终态回执就默认成功？（应追讨）
-- [ ] 未经用户开工确认就派发？（§一）
+> 依据：TASK-23 越界调研真实案例——PM 亲自读仓储实现 / sweep 机制 / 服务端 Go 源码 / 限流桶与排序语义，据此形成**错误前提**（误判服务端字段不可用），用户在错误前提下多做一轮选择，最终由 arch 以更硬理由拉回。**越界调研的实际成本 = 无效决策轮次。**
+
+- **PM 可自做（简略调研）**：① 粗略分析任务设计的**技术深度**（供范围划分与派发，不下结论）；② UI/文案/样式/交互的**落点确认**（组件在哪、有无可复用件、i18n 键、插槽/属性支持）；③ 读 `docs/prds` / `docs/adr` / `docs/tasks-state.md` 等**决策留痕**；④ 判断任务编号与范围划分；⑤ **产品形态业界调研**（同类功能有哪些功能点 / 属性 / 组织结构 / 视图 / 协作 / 生命周期；清单与检索纪律见 @.agents/skills/research.md）——只作**参考**，不得据此下技术结论。
+- **必须转角色（任一命中即转，PM 不自行下结论）**：
+  1. 出现「哪个方案更好」的**取舍**；
+  2. 需读 `packages/domain-*` / `packages/infrastructure` / 服务端 / 构建配置 / 同步链；
+  3. 结论会**改变 PRD 范围或 AC**；
+  4. 影响面跨 **>1 个包或 >1 个端**；
+  5. 涉及性能量级、限流、契约字段语义、枚举/排序语义；
+  6. 任何以外部文章/竞品做法为依据的**技术结论**（该用哪个方案/库/中间件）。
+- **转发对象**：技术选型与影响面 → `arch-designer`；验收策略与用例 → `qa`；实现细节 → `rd-fe` / `rd-be`。
+- **判定口径**：不确定是否越界时**按越界处理**（转角色），不以「省一轮」为由自行下结论。
 
-> 完整红线（16 项）与交付检查清单（15 项）：**交付/派发前**读取 @.agents/checklists/pm.md 逐项核对。
+## 十、硬性红线
 
-## 十、交付检查清单
+- [ ] 派发后未收终态回执就默认成功？（应追讨）
+- [ ] 未经用户开工确认就派发？（§一）
+- [ ] PM 以「亲自探查技术实现」替代转角色、并据此形成 PRD 前提？（§九 技术调研边界）
+- [ ] 派发消息贴了 PRD/方案全文、或用 `attachments` 传全文？（应给引用路径，worker 自己读文件）
+- [ ] 跨批次未重开会话、未更新接续快照？（长上下文丢红线/闸门；见 §六 生命周期）
+- [ ] 用外部调研（文章/竞品/开源实现）替代 arch 技术取舍，或把外部做法写成既定技术前提？（§九 + @.agents/skills/research.md）
+- [ ] PM 改源码/测试/构建配置，或手改冲突内容？（应转 worker；PM 只做仓库治理与发布）
+- [ ] PM 亲自合并 PR / `push` main？（合并由 RD 执行，PM 只验收授权；§十三）
+- [ ] 未过验收 / 门禁未绿就打 tag 或 release，或 tag 指向非 main 合并提交？（§十三）
+- [ ] main 上出现多条本需求提交或 `wip()` 提交（未 squash）？提交 / PR 标题不可读（纯编号/类名/路径）？
+- [ ] Issue 与 `docs/` 双源（正文抄进 Issue / 状态只留平台）？（§十三）
+- [ ] `git push --force` 到 main/共享分支（未经用户明确授权并指明分支）？
+- [ ] release notes 不可读（纯编号/类名/路径），或未落盘 `docs/releases/`？
+- [ ] 降级（无 `gh` / 无远端）未在 `tasks-state` 与回执中标注？
+
+> 完整红线（32 项）与交付检查清单（34 项）：**交付/派发前**读取 @.agents/checklists/pm.md 逐项核对。
+
+## 十一、交付检查清单
 
 完整清单见 @.agents/checklists/pm.md（交付前逐项核对，汇报只报未过项）。
 
-## 十一、交付归档
+## 十二、交付归档
 
 - 时机：PRD 完成且交付闭环后**当日**归档。
 - 落盘：`docs/prds/YYYY-MM-DD-<主题>.md`。
-- 内容：背景(5 Whys 摘要) → 目标指标与埋点 → 9 模块要点 → 决策留痕(RICE/取舍/回滚) → 派发记录 → 验收结果 → 变更记录 → 遗留项。
+- 内容：背景(5 Whys 摘要) → 目标指标与埋点 → 9 模块要点 → 决策留痕(RICE/取舍/回滚) → 参考来源(`docs/research/` 路径) → 派发记录（含需求分支、PR 编号、main 合并 commit hash） → 验收结果 → 变更记录 → 遗留项。
 - 首次归档创建 `docs/prds/README.md` 索引（日期 | 主题 | 交付 | 终签状态）。
+- 归档同时：更新 `docs/tasks-state.md` 接续快照；「派发记录」末行记**会话体检**（`contextTokens / 压缩次数 / cacheRead 占比`，取自 `/session`）；随后按 §六「PM 会话生命周期」重开 PM 会话（归档 = 批次终态）。
+
+## 十三、Issue / PR / 发布与仓库治理（PM 独有职责）
+
+PM 负责 **Issue 立项与同步、PR 验收与评论、Tag Release、仓库治理文件**；**合并由 RD 在 PR 上执行，PM 不亲自合并、不 push main**。
+
+- **Issue（入口 + 摘要）**：**PRD 定稿后、开工确认卡前**建 Issue（TL;DR / AC 编号 / 优先级 / `docs/prds` 指针）——分支名需要 issue-id；**正文留 `docs/`**，Issue 不抄正文（避免双源）。同步时机仅 **5 个节点**：立项 / 派发 / 验收通过 / 合并 / 发布。
+- **PR**：PM 在 PR 评论核 AC；**验收通过 = 授权合并**；不点合并按钮。Reviewer 与 PR owner 在开工确认卡指定。
+- **发布（优先 `gh`）**：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 仍可用）→ `gh release create <tag> --notes-file docs/releases/<version>.md`；不可用降级 `git tag -a` + `git push origin <tag>`。**不自动 `gh auth login`**。
+- **版本号**：SemVer（feat→MINOR / fix→PATCH / 破坏性→MAJOR）；tag 必须指向 **main 的合并提交**。
+- **仓库治理**：分支策略、`.github/` 模板（含 PR 模板）、README、`.gitignore` 属 PM；**不改源码/测试/构建配置**；冲突需改源码 → 转 worker。
+- **回滚**：已 push 的 tag 不删（改发下一个 PATCH），除非用户明确要求。
+
+细则（八阶段、分支/PR 规范、离线降级、发布、hotfix）：@.agents/skills/github-flow.md（立项 / 终签 / 发布时读取）。
 
 **沟通规范**：中文；先方案后细节；关键决策附理由；交付前跑检查清单（只报未过项）。

package/.agents/prompts/test-engineer.md

@@ -1,8 +1,8 @@
 ---
 description: 测试工程师角色 Prompt（短常驻）——策略/用例/缺陷/质量保障
 role: qa
-version: 7
-updated: 2026-09-21
+version: 11
+updated: 2026-09-24
 ---
 
 # 测试工程师（QA）
@@ -12,7 +12,8 @@ updated: 2026-09-21
 > 按需技能：
 > @.agents/skills/test-design.md（用例设计、缺陷管理、性能安全、DDD 分层对齐）。
 > @.agents/skills/codegraph.md（`affected` 找受影响测试，替代手动追踪）。
-> @.agents/skills/commit.md（仅在执行 git commit 前读取）。
+> @.agents/skills/commit.md（提交时机/需求分支/可读信息；仅在执行 git commit 前读取）。
+> @.agents/skills/github-flow.md（PR 验证评论 / 验收与合并时序）。
 
 资深测试工程师，负责质量保障全流程：计划、用例设计、评审、执行、缺陷管理、回归、报告。职责：以**可追溯、可执行、可量化**的覆盖交付质量结论。
 
@@ -61,6 +62,7 @@ DDD 分层对齐（简）：
 - **业务规则 → 领域测试**：状态流转、不变量对应 domain 单测；发现规则散落组件/Service 时提示研发收敛。
 - **评审参与**：需求评审确认可测性（数据口径/埋点/边界）。
 - **缺陷闭环联动**：指派明确、信息完整，避免"环境问题/数据问题"推诿。
+- **PR 验证**：在 PR 评论贴**全量门禁精确数字**（命令 + exit code + 文件数/例数/红数）与预览环境结论；**PM 验收通过前不得以"测试已过"为由催促合并**（合并由 RD 在 PM 授权后执行）。
 
 ## 六、硬性红线
 
@@ -68,11 +70,15 @@ DDD 分层对齐（简）：
 - [ ] 未经用户确认就执行测试？
 - [ ] 未 Verify 就关闭缺陷？
 - [ ] 定位被测代码/受影响测试未用 `codegraph node/affected`？（回退 grep 需注明原因）
+- [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
+- [ ] 造数/探针类测试**回滚不完整**（漏表 ⇒ 孤儿数据）或**未做收尾孤儿扫描**？
 
-> 完整红线（10 项）与交付检查清单（10 项）：**交付前**读取 @.agents/checklists/qa.md 逐项核对。
+> 完整红线（10 项）与交付检查清单（16 项）：**交付前**读取 @.agents/checklists/qa.md 逐项核对。
 
 ## 七、交付检查清单
 
+- [ ] 造数/探针类测试：回滚清单覆盖**全部业务表**（无外键时无级联兜底）+ 收尾跑**通用孤儿扫描**并附**逐表数字**（口径见 @.agents/checklists/qa.md）
+
 完整清单见 @.agents/checklists/qa.md（交付前逐项核对，汇报只报未过项）。
 
 ---

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

@@ -3,12 +3,15 @@
 # nao-fleet.sh — 按角色一键拉起 pi 会话窗口（nao 团队工具箱）
 #
 # 用法
-#   nao-fleet.sh check [--strict]                 静态体检：roles.yaml/角色卡/交叉引用/白名单/布局
+#   nao-fleet.sh check [--strict] [-v]            静态体检：roles.yaml/缩进/EOL/角色卡/交叉引用/PR 模板/白名单/布局
+#                                                 默认单行摘要（含 warn 计数）；-v 展开完整报告；失败始终展开
 #   nao-fleet.sh status                           角色会话在线状态（权威名单见 intercom list）
 #   nao-fleet.sh ensure <别名>[@<repo>] [更多...]  拉起角色窗口（默认工作区=roles.yaml workspace）
 #   nao-fleet.sh ensure -m <model> <别名>...       显式指定模型（须命中白名单）
 #   nao-fleet.sh ensure --task <编号> <别名>[@<repo>]   任务派生会话：--name <别名>-<编号>（并行隔离，避免同名冲突）
 #   nao-fleet.sh ensure --force <别名>...          忽略"已在运行"判重
+#   nao-fleet.sh close <别名|会话名> [--task <编号>] [--force]
+#                                                 回收已完成会话（闸门：在跑 turn / tasks-state 未推进 → 拒绝，--force 跳过）
 #
 # 角色别名 → 角色卡：见 .agents/roles.yaml（单一事实来源）
 #   当前：pm / arch-designer(arch) / rd-fe / rd-be / qa
@@ -16,9 +19,11 @@
 # 环境变量
 #   NAO_TERMINAL=ghostty|ptyxis|tmux|screen   强制宿主
 #   NAO_TMUX_LAYOUT=main-row2|grid            tmux 布局（默认 main-row2）
-#   NAO_TMUX_MAIN_WIDTH=<10..90>              main-row2 主 pane 宽度百分比（默认 50）
+#   NAO_TMUX_MAIN_WIDTH=<10..90>              main-row2 主 pane 宽度百分比（默认 35）
 #   NAO_SKILLS=<dir>                          角色卡根目录（默认 <脚本>/../..）
 #   NAO_MODEL_WHITELIST=<glob,...>            -m 白名单（默认空=不校验，支持 glob）
+#   NAO_CLOSE_BUSY_PATTERN=<ERE>             close 的在跑 turn 判定正则（默认内置 pi 状态行标记）
+#   NAO_TASKS_STATE=<path>                   任务状态文件（默认 docs/tasks-state.md，供残留检测/回收闸门）
 #
 # tmux 宿主行为
 #   - 已在 tmux 内（$TMUX 存在）：当前窗口分屏拉起，不新建窗口。
@@ -42,7 +47,15 @@ ROLE_ORDER=()
 declare -A ROLE_CARDS ROLE_WS ALIAS_ROLE
 MODEL_WHITELIST="${NAO_MODEL_WHITELIST:-}"
 TMUX_LAYOUT="${NAO_TMUX_LAYOUT:-main-row2}"
-TMUX_MAIN_WIDTH="${NAO_TMUX_MAIN_WIDTH:-50}"
+# main-row2 主 pane 宽度百分比：默认值与非法值回退共用同一常量（防三处漂移）
+TMUX_MAIN_WIDTH_DEFAULT=35
+TMUX_MAIN_WIDTH="${NAO_TMUX_MAIN_WIDTH:-$TMUX_MAIN_WIDTH_DEFAULT}"
+# check 输出契约：默认单行摘要（省 PM 上下文），-v 展开完整报告；失败始终展开
+VERBOSE=false
+# close 的在跑 turn 判定（pi 默认状态行：Working (esc to interrupt) / Thinking... / Retrying / Compacting）
+CLOSE_BUSY_PATTERN="${NAO_CLOSE_BUSY_PATTERN:-Working \(|Thinking\.\.\.|to interrupt|to cancel|Retrying \(|Compacting|Summarizing branch}"
+# 任务状态文件（相对当前目录；供残留检测与回收闸门）
+TASKS_STATE="${NAO_TASKS_STATE:-docs/tasks-state.md}"
 
 log()  { printf '\033[1;32m[fleet]\033[0m %s\n' "$*"; }
 warn() { printf '\033[1;33m[fleet]\033[0m %s\n' "$*" >&2; }
@@ -135,6 +148,43 @@ check_cross_refs() {
   return $rc
 }
 
+# .agents/** 文本文件 EOL 契约：必须全为 LF（出现 CR 即 fail，列出文件）
+# 排除 .nao-obsolete/（update 的旧版备份，EOL 不作为契约）
+check_eol() {
+  local rc=0 n=0 f
+  local -a bad=()
+  while IFS= read -r -d '' f; do
+    n=$((n + 1))
+    grep -Iq $'\r' "$f" && bad+=("${f#"$SKILLS_DIR"/}")
+  done < <(find "$SKILLS_DIR/.agents" -type f ! -path '*/.nao-obsolete/*' -print0)
+  if (( ${#bad[@]} == 0 )); then
+    printf '  ✓ %d 个文本文件全 LF\n' "$n"
+  else
+    rc=1
+    printf '  ✗ %d/%d 个文件含 CR（须转 LF；CRLF 会破坏 fleet/awk 解析）:\n' "${#bad[@]}" "$n"
+    printf '      %s\n' "${bad[@]}"
+  fi
+  return $rc
+}
+
+# roles.yaml 缩进契约：角色 id 2 空格 / 字段 4 空格 / 禁 Tab（与 load_manifest 解析器同契约，独立报行号）
+check_roles_indent() {
+  awk '
+    BEGIN { in_roles=0; cur=0; bad=0 }
+    /^[[:space:]]*$/ { next }
+    /^[[:space:]]*#/ { next }
+    /\t/ { printf "  ✗ 行 %d: 含 Tab（禁止 Tab 缩进）\n", FNR; bad=1; next }
+    !in_roles {
+      if ($0 ~ /^roles:[[:space:]]*$/) { in_roles=1; next }
+      printf "  ✗ 行 %d: 顶层仅允许 roles:（得到: %s）\n", FNR, $0; bad=1; next
+    }
+    $0 ~ /^  [^ ][^:]*:[[:space:]]*$/ { cur=1; next }
+    cur && $0 ~ /^    [a-z_]+:[[:space:]]/ { next }
+    { printf "  ✗ 行 %d: 缩进/位置非法（角色 id 须 2 空格、字段须 4 空格且挂在角色下）: %s\n", FNR, $0; bad=1 }
+    END { exit (bad ? 1 : 0) }
+  ' "$MANIFEST"
+}
+
 # CodeGraph 索引健康（ensure 拉起前 / check 用；缺失或过期仅 warn，不阻塞）
 check_codegraph() {
   local repo="$1" name st
@@ -173,7 +223,55 @@ detect_host() {
   echo screen
 }
 
-running() { pgrep -f -- "pi[[:space:]].*--name $1([[:space:]]|$)" >/dev/null 2>&1; }
+# 该会话名对应的真实 pi 进程 PID（过滤 shell/tmux 等误匹配，避免误命中宿主命令行、误杀包装进程）
+pi_pids_for() {
+  local pid comm
+  pgrep -f -- "pi[[:space:]].*--name $1([[:space:]]|$)" 2>/dev/null | while IFS= read -r pid; do
+    comm="$(ps -o comm= -p "$pid" 2>/dev/null | tr -d ' ')"
+    case "$comm" in
+      bash|sh|dash|zsh|fish|tmux|screen|sudo|env) continue ;;
+    esac
+    printf '%s\n' "$pid"
+  done
+}
+
+running() { [[ -n "$(pi_pids_for "$1")" ]]; }
+
+# 定位会话所在 tmux pane（靠启动命令里的 --name；边界避免 rd-be 误命中 rd-be-T1）
+find_pane_for() {
+  command -v tmux >/dev/null 2>&1 || return 0
+  tmux list-panes -a -F '#{pane_id} #{pane_start_command}' 2>/dev/null \
+    | awk -v n="$1" '$0 ~ ("--name[ =]" n "([^A-Za-z0-9_-]|$)") { print $1; exit }'
+}
+
+# 该 pane 末 3 行是否显示在跑 turn（启发式：状态行标记；回执/产物以 PM 核对清单为准）
+pane_busy() {
+  local pane="$1" tail3
+  tail3="$(tmux capture-pane -p -t "$pane" 2>/dev/null | grep -v '^[[:space:]]*$' | tail -3)"
+  [[ -n "$tail3" ]] || return 1
+  grep -qE "$CLOSE_BUSY_PATTERN" <<< "$tail3"
+}
+
+# 任务在 tasks-state 的归处：active（进行态）/ closed（已验收·已归档）/ absent（无记录）/ nofile
+task_state_class() {
+  local id="$1"
+  [[ -f "$TASKS_STATE" ]] || { echo nofile; return; }
+  awk -v id="$id" '
+    /^## / { sec=$0; sub(/^##[[:space:]]*/, "", sec); next }
+    {
+      n=split($0, cells, "|")
+      for (i=1;i<=n;i++) {
+        c=cells[i]; gsub(/^[[:space:]]+|[[:space:]]+$/, "", c)
+        if (c==id) { hit=sec; break }
+      }
+    }
+    END {
+      if (hit=="") { print "absent"; exit }
+      if (hit ~ /已验收|已归档/) { print "closed"; exit }
+      print "active"
+    }
+  ' "$TASKS_STATE"
+}
 
 # 白名单命中返回 0，否则返回 1；未设白名单=放行
 check_model() {
@@ -296,7 +394,7 @@ apply_tmux_layout() {
   (( ${#pane_ids[@]} >= 1 )) || return 0
 
   local pct="$TMUX_MAIN_WIDTH"
-  [[ "$pct" =~ ^[0-9]+$ ]] || pct=50
+  [[ "$pct" =~ ^[0-9]+$ ]] || pct="$TMUX_MAIN_WIDTH_DEFAULT"
   (( pct < 10 )) && pct=10
   (( pct > 90 )) && pct=90
 
@@ -375,7 +473,20 @@ cmd_check() {
     else printf '  ✗ 缺失: %s\n' "$d"; rc=1; fi
   done
 
+  echo "== 文本契约（roles.yaml 缩进 2/4 · .agents/** EOL 全 LF）=="
+  if [[ -f "$MANIFEST" ]]; then
+    if check_roles_indent; then
+      printf '  ✓ roles.yaml 缩进契约（角色 id 2 空格 / 字段 4 空格 / 无 Tab）\n'
+    else
+      rc=1
+    fi
+  else
+    printf '  ✗ roles.yaml 缺失: %s\n' "$MANIFEST"; rc=1
+  fi
+  check_eol || rc=1
+
   echo "== 角色清单 roles.yaml =="
+  load_manifest
   printf '  ✓ 解析成功，%d 个角色: %s\n' "${#ROLE_ORDER[@]}" "${ROLE_ORDER[*]}"
 
   echo "== 常驻角色卡（阈值 ${CARD_MAX_LINES} 行，frontmatter 校验）=="
@@ -424,6 +535,33 @@ cmd_check() {
     else printf '  ✗ %s 缺失\n' "$f"; rc=1; fi
   done
 
+  echo "== PR 模板（GitHub Flow）=="
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo '  · 非 git 仓库（跳过）'
+  else
+    local remote_url prtpl="" cand
+    remote_url="$(git config --get remote.origin.url 2>/dev/null || true)"
+    if [[ -z "$remote_url" ]]; then
+      echo '  · 无 remote.origin（跳过）'
+    elif [[ "$remote_url" != *github.com* ]]; then
+      echo '  · 远端非 GitHub（跳过；PR 模板不适用）'
+    else
+      shopt -s nullglob
+      for cand in .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md \
+                  .github/PULL_REQUEST_TEMPLATE \
+                  pull_request_template.md PULL_REQUEST_TEMPLATE.md \
+                  docs/pull_request_template.md docs/PULL_REQUEST_TEMPLATE.md; do
+        [[ -e "$cand" ]] && { prtpl="$cand"; break; }
+      done
+      shopt -u nullglob
+      if [[ -n "$prtpl" ]]; then
+        printf '  ✓ PR 模板已就位：%s\n' "$prtpl"
+      else
+        echo '  ! 未找到 PR 模板（GitHub 远端）：PM 立项时从 .agents/templates/github/pull_request_template.md.example 复制为 .github/pull_request_template.md（见 skills/github-flow.md）'
+      fi
+    fi
+  fi
+
   echo "== 按需技能 =="
   if [[ -d "$SKILLS_SUB" ]]; then
     shopt -s nullglob
@@ -453,6 +591,18 @@ cmd_check() {
     echo '  · codegraph 未安装（回退 grep 属预期行为）'
   fi
 
+  echo "== pi 插件（业界调研能力）=="
+  local piset="$HOME/.pi/agent/settings.json"
+  if [[ -f "$piset" ]]; then
+    if grep -q 'pi-web-access' "$piset" 2>/dev/null; then
+      echo '  · pi-web-access ✓ 已装（PM/arch 业界调研可用）'
+    else
+      echo '  ! pi-web-access 未装（业界调研不可用；nao-skill plugins install web-access）'
+    fi
+  else
+    echo "  · 未找到 $piset（跳过插件检测）"
+  fi
+
   echo "== 模型白名单 =="
   if [[ -z "$MODEL_WHITELIST" ]]; then
     echo "  （未设置 NAO_MODEL_WHITELIST，-m 不校验）"
@@ -498,7 +648,7 @@ cmd_check() {
     if [[ "$TMUX_MAIN_WIDTH" =~ ^[0-9]+$ ]] && (( TMUX_MAIN_WIDTH >= 10 && TMUX_MAIN_WIDTH <= 90 )); then
       printf '  ✓ NAO_TMUX_MAIN_WIDTH=%-3s%% 合法\n' "$TMUX_MAIN_WIDTH"
     else
-      printf '  ! NAO_TMUX_MAIN_WIDTH=%-3s  非法（10..90），运行时会回退 50\n' "$TMUX_MAIN_WIDTH"
+      printf '  ! NAO_TMUX_MAIN_WIDTH=%-3s  非法（10..90）：越界夹取到 10/90，非数字回退 %s\n' "$TMUX_MAIN_WIDTH" "$TMUX_MAIN_WIDTH_DEFAULT"
     fi
   fi
 
@@ -507,7 +657,7 @@ cmd_check() {
     rc=1
   fi
 
-  exit $rc
+  return $rc
 }
 
 # ---------------------------------------------------------------------------
@@ -522,11 +672,89 @@ cmd_status() {
     fi
   done
   echo "== 任务派生会话（--task 拉起，如 rd-be-T1）=="
-  local found=0 line
+  local found=0 line dname role id cls tag
   while IFS= read -r line; do
-    [[ -n "$line" ]] && { printf '  · %s\n' "$line"; found=1; }
+    [[ -n "$line" ]] || continue
+    dname="$(awk '{for(i=1;i<=NF;i++) if($i=="--name") {print $(i+1); exit}}' <<< "$line")"
+    [[ -n "$dname" ]] || continue
+    id=""; tag=""
+    for role in "${ROLE_ORDER[@]}"; do [[ "$dname" == "$role-"* ]] && { id="${dname#"$role"-}"; break; }; done
+    if [[ -n "$id" ]]; then
+      cls="$(task_state_class "$id")"
+      case "$cls" in
+        closed) tag="  ! 残留（$id 已归档）→ close --task $id ${dname%-*}" ;;
+        absent) tag="  ! 残留（tasks-state 无 $id 记录）→ 核对后 close --task $id ${dname%-*}" ;;
+        active) tag="  · $id 进行态" ;;
+      esac
+    fi
+    printf '  · %s%s\n' "$dname" "$tag"
+    found=1
   done < <(pgrep -af "pi[[:space:]].*--name (pm|arch-designer|rd-fe|rd-be|qa)-[A-Za-z0-9_-]+" 2>/dev/null | head -10)
   (( found )) || echo '  （无）'
+  [[ -f "$TASKS_STATE" ]] || echo "  （$TASKS_STATE 不存在，残留判定已跳过）"
+}
+
+# ---------------------------------------------------------------------------
+# 回收已完成会话：闸门（tasks-state 已推进 + 无在跑 turn）+ 落地（pane/会话/screen/进程）
+cmd_close() {
+  local force="$1" task="$2" target="$3"
+  [[ -n "$target" ]] || die "close 需要目标：角色别名或派生会话名（如 rd-be / rd-be-T1）"
+  local name repo cls bus pane pids r ok
+  if [[ -n "$task" ]]; then
+    resolve_role "$target"
+    name="${NAME}-${task}"
+    repo="${ROLE_WS[$NAME]:-$PWD}"
+    # 闸门①：tasks-state 未推进 → 拒绝（验收未过需原会话返工，回收会丢上下文）
+    cls="$(task_state_class "$task")"
+    if [[ "$cls" == "active" && "$force" != true ]]; then
+      warn "拒绝回收 $name：tasks-state 中 $task 仍在进行态（未验收/未归档）"
+      warn "  先把 $task 移入「已验收/已归档」再回收（或 --force：将丢失打回返工所需上下文）"
+      return 1
+    fi
+    [[ "$cls" == "absent" ]] && warn "tasks-state 无 $task 记录（仅按会话名回收）"
+    [[ "$cls" == "nofile" ]] && log "未启用 $TASKS_STATE（跳过状态闸门）"
+  elif [[ -n "${ALIAS_ROLE[$target]:-}" ]]; then
+    name="${ALIAS_ROLE[$target]}"; repo="${ROLE_WS[$name]:-$PWD}"
+    warn "常驻会话 $name：任务闭环后应 ensure --force 重开，而非回收（仅在本批不再需要该角色时回收）"
+  else
+    name="$target"
+    [[ "$name" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*$ ]] || die "非法会话名: $name"
+    # 非别名的目标必须是 <已知角色>-<编号>，否则视为拼错（防静默 no-op）
+    ok=0
+    for r in "${ROLE_ORDER[@]}"; do [[ "$name" == "$r-"* ]] && ok=1; done
+    (( ok )) || die "未知角色或派生会话名: $name（可用: ${ROLE_ORDER[*]}；派生名形如 rd-be-T1）"
+    repo="$PWD"
+  fi
+
+  running "$name" || { log "$name 未运行（无需回收）"; return 0; }
+
+  # 闸门②：在跑 turn（tmux 可判；非 tmux 宿主无法判 → 需 --force）
+  pane="$(find_pane_for "$name")"
+  if [[ -n "$pane" ]]; then
+    pane_busy "$pane" && bus="tmux pane $pane 末行显示在跑 turn"
+  else
+    bus="非 tmux 宿主，无法确认是否在跑 turn"
+  fi
+  if [[ -n "$bus" && "$force" != true ]]; then
+    warn "拒绝回收 $name：$bus"
+    warn "  等它停；回执与产物核对见 checklists/pm.md「会话回收 / 收窗核对」（或 --force 强制）"
+    return 1
+  fi
+
+  if [[ -n "$pane" ]] && tmux kill-pane -t "$pane" 2>/dev/null; then
+    log "已回收 $name（tmux pane $pane）@ $repo"; return 0
+  fi
+  if command -v tmux >/dev/null 2>&1 && tmux has-session -t "nao-$name" 2>/dev/null && tmux kill-session -t "nao-$name" 2>/dev/null; then
+    log "已回收 $name（tmux 会话 nao-$name）@ $repo"; return 0
+  fi
+  if command -v screen >/dev/null 2>&1 && screen -ls 2>/dev/null | grep -q "nao-$name" && screen -S "nao-$name" -X quit 2>/dev/null; then
+    log "已回收 $name（screen 会话 nao-$name）@ $repo"; return 0
+  fi
+  pids="$(pi_pids_for "$name" | tr '\n' ' ')"
+  if [[ -n "$pids" ]] && kill $pids 2>/dev/null; then
+    log "已回收 $name（结束进程: $pids）@ $repo"; return 0
+  fi
+  warn "未找到 $name 的 pane/会话/进程（可能刚好退出）"; return 1
 }
 
 # ---------------------------------------------------------------------------
@@ -568,11 +796,12 @@ usage() {
 }
 
 # ---- 入口 ----
-CMD=""; FORCE=false; STRICT=false; MODEL=""; TARGETS=()
+CMD=""; FORCE=false; STRICT=false; MODEL=""; TASK=""; TARGETS=()
 while [[ $# -gt 0 ]]; do
   case "$1" in
     check)  CMD="check";  shift ;;
     status) CMD="status"; shift ;;
+    close)  CMD="close";  shift ;;
     ensure) CMD="ensure"; shift ;;
     -m|--model)
       MODEL="${2:-}"
@@ -582,18 +811,45 @@ while [[ $# -gt 0 ]]; do
     --force)  FORCE=true;  shift ;;
     --task)   TASK="${2:-}"; [[ -n "$TASK" ]] || die "--task 需要任务编号（如 T1）"; [[ "$TASK" =~ ^[A-Za-z0-9_-]+$ ]] || die "--task 非法: $TASK（仅字母/数字/-/_）"; shift 2 ;;
     --strict) STRICT=true; shift ;;
+    -v|--verbose) VERBOSE=true; shift ;;
     -h|--help) usage ;;
     *) TARGETS+=("$1"); shift ;;
   esac
 done
 
 case "$CMD" in
-  check|ensure|status) load_manifest ;;
+  check)  : ;;   # cmd_check 自行先做文本契约体检，再 load_manifest（缩进违例时也能先出报告）
+  ensure|status|close) load_manifest ;;
 esac
 
 case "$CMD" in
-  check)  cmd_check "$STRICT" ;;
+  check)
+    # 默认单行摘要（派发前自检只需 exit code + 计数；完整报告 30+ 行不进 PM 上下文）；-v 或失败时展开
+    # 子 shell 隔离：cmd_check 内部 die/exit 不得吞掉报告（计数从报告解析，不靠子 shell 内变量）
+    REPFILE="$(mktemp)"
+    set +e
+    ( cmd_check "$STRICT" ) >"$REPFILE" 2>&1
+    CHECK_RC=$?
+    set -e
+    if (( CHECK_RC == 0 )) && ! $VERBOSE; then
+      WARNS="$(grep -c '^  !' "$REPFILE" || true)"
+      ROLES_N="$(grep -oE '解析成功，[0-9]+ 个角色' "$REPFILE" | grep -oE '[0-9]+' | head -1 || true)"
+      FILES_N="$(grep -oE '[0-9]+ 个文本文件全 LF' "$REPFILE" | grep -oE '^[0-9]+' | head -1 || true)"
+      if (( WARNS > 0 )); then
+        printf 'check: OK · roles=%s · files=%s · layout=%s · warn=%d（-v 看详情）\n' \
+          "${ROLES_N:-?}" "${FILES_N:-?}" "$TMUX_LAYOUT" "$WARNS"
+      else
+        printf 'check: OK · roles=%s · files=%s · layout=%s\n' \
+          "${ROLES_N:-?}" "${FILES_N:-?}" "$TMUX_LAYOUT"
+      fi
+    else
+      cat "$REPFILE"
+    fi
+    rm -f "$REPFILE"
+    exit $CHECK_RC
+    ;;
   status) cmd_status ;;
+  close)  cmd_close "$FORCE" "$TASK" "${TARGETS[0]:-}" ;;
   ensure) cmd_ensure "$FORCE" "$MODEL" "$TASK" "${TARGETS[@]}" ;;
   *) usage ;;
 esac