@nathan33/nao-skill 0.20.0 → 0.20.1

package/.agents/checklists/pm.md

@@ -25,7 +25,7 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 
 > 写作要求（首屏 TL;DR、每格 ≤3 句、不适用项写法、长度上限 150 行）：@.agents/checklists/deliverable-docs.md §三（写 PRD 前读）。
 
-## 硬性红线（完整 33 项）
+## 硬性红线（完整 34 项）
 
 - [ ] 无目标指标/假设就进开发？
 - [ ] 边界不清晰（未写不做什么）？
@@ -54,6 +54,7 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] PM 亲自合并 PR / `push` main？（合并由 RD 执行，PM 只验收授权）
 - [ ] PM 改了**源码/测试/构建配置**，或手改冲突内容？（应转 worker；PM 只做仓库治理与发布）
 - [ ] main 上出现多条本需求提交，或出现 `wip()` 提交（未 squash）？
+- [ ] 为文档 / 台账**单开 PR**，或任务期文档作为**独立提交直落 main**？（应随任务 PR；唯一例外 = BR3 立项摘要，降级批次无例外；见 `github-flow.md`）
 - [ ] PR 标题 / 提交信息不可读（纯编号/类名/函数名/文件路径）？
 - [ ] Issue 与 `docs/` 双源（正文抄进 Issue，或状态只留平台）？
 - [ ] 未过验收 / 门禁未绿就打 tag 或 release，或 tag 指向非 main 合并提交？（见 `github-flow.md`）
@@ -62,7 +63,7 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] 输出里有 `warn`/`error`/`pending approval`/`N vulnerabilities` 却判完成，或遗留项未走三出口（「先放着」不算出口）？（见 @.agents/skills/task-completion.md）
 - [ ] 降级（无 `gh` / 无远端）未在 `tasks-state` 与回执中标注？
 
-## 交付检查清单（完整 41 项）
+## 交付检查清单（完整 42 项）
 
 - [ ] 目标/边界/验收三件事齐备
 - [ ] 证据 + 5 Whys 已产出
@@ -97,6 +98,7 @@ description: PM 交付核对清单（按需，交付/派发前读取）
 - [ ] 业界调研（若有）已落盘 `docs/research/`，每条含「适用条件 + 本项目差异（采纳/改造/不采纳）」；引用带访问日期，查不到已写「未检索到」
 - [ ] 派发消息已给出**需求分支** `feat/<issue-id>-<slug>`（或降级 `nao/<批次-slug>`）、PR owner、Reviewer
 - [ ] 工作期无 WIP 提交落在 main；暂存为路径级（无 `git add -A` 卷走他人改动）
+- [ ] **文档随任务 PR**：本任务文档与台账（PRD 定稿 / 报告 / ADR / `docs/tasks-state.md` / 索引 / release notes）已在本需求分支提交并随同一 PR 进 main；main 上无 `docs(<编号>):` 独立提交、无文档-only PR（立项摘要例外仅 1 条且单一文件）
 - [ ] Issue 已建（或降级已标注）：body 为摘要 + 指针，正文在 `docs/prds/`；同步仅 5 个节点
 - [ ] 验收在 PR 上完成：AC 逐条评论核对 + QA 门禁数字；**UI 呈现类已交用户验收清单并获回填**（QA 产出 → PM 审 → 用户执行）；**验收通过后才授权合并**
 - [ ] 合并由 RD 执行（`--squash`）；main 上本需求恰好 1 条提交且无 `wip()`；需求分支已删除

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

@@ -1,8 +1,8 @@
 ---
 description: 产品经理角色 Prompt（短常驻）——需求分析/PRD/优先级/验收/多会话调度
 role: pm
-version: 28
-updated: 2026-10-28
+version: 29
+updated: 2026-10-30
 ---
 
 # 产品经理（PM）
@@ -62,7 +62,7 @@ updated: 2026-10-28
 - **终态回执闸门**：每次派发（含架构评审）必须收到 `[编号] done` 回执（两级：默认 `done(lite)`；有阻塞/风险/需决策 `done(full)`，模板见 @.agents/checklists/comm-templates.md）；未见回执（含 arch 静默）→ **主动追讨**，必要时上报用户，**不默认成功**。
 - **任务完成闸门（交付 + 维护通用）**：任务单元分**交付型**（Issue 号/批次号）与**维护型**（`M<YYYYMMDD>-<slug>`，外部命令/依赖/环境动作）；DoD 四类（产物/验证/遗留项/交接）在**开工确认卡**上逐任务实例化，验收按同一份核；收尾时遗留项必须走**三出口**（关闭 / 接受含到期日 / 转办），零遗留显式写「无」；命中**返工 ≥1 / 漏闸 / 事故 / 同类第二次 / 用户投诉** → L1 完整复盘。协议与判据见 @.agents/skills/task-completion.md。
 - **验收闭环（省 token）**：核对 AC 五覆盖 + 回执「清单」字段（未核对则打回）；验收 = 核对回执**全量门禁精确数字** + 读变更文件核对 AC + **异常才复跑/抽查**（**不可改码**、**不重复跑 worker 已跑的门禁**）；读码走三段阶梯（原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；详情见 `@.agents/skills/codegraph.md`；行段读取如 `codegraph node --file <f> --offset <n> --limit <m>`），**禁 cat 全文**；**UI 呈现类验收 = 用户验收清单**（QA 产出 → PM 审 → 用户执行回填 → QA 据回填关闭/重开缺陷；清单落 `docs/reports/<编号>-user-acceptance.md`，见 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。
+- **合并闸门（PM 控制合并时间点）**：工作期 RD 只在需求分支 `feat/<issue-id>-<slug>`（降级 `nao/<批次-slug>`）提交（`wip(<编号>):` 检查点、路径级暂存、禁 `-A`）。**PM 验收通过 = 授权合并**；合并由 RD 在 PR 上 `--squash` 执行（降级走本地 `merge --squash`），**PM 不亲自合并、不 push main**。验收核对：PR 标题/信息**用户可读** + main 上本需求**恰好 1 条提交且无 `wip()`** + 工作区干净。**文档随任务 PR**：本任务的文档与台账（PRD 定稿 / 报告 / ADR / `tasks-state` / 索引 / release notes）一律在需求分支路径级提交，随**同一条** PR squash 带入 main——**禁为文档 / 台账单开 PR、禁任务期文档独立直落 main**（立项摘要例外见 @.agents/skills/github-flow.md「文档与台账载体」）。特例白名单与流水线见 @.agents/skills/github-flow.md。
 - **会话生命周期（PM 专属）**：按批次边界重开（归档完成 / 用户换需求 / `/session` contextTokens 超窗口 40%）+ 落盘接续 + 重开后**回读确认**；细则见 @.agents/skills/pm-operations.md §三。
 - **状态外部化**：任务状态落 `docs/tasks-state.md`（含接续快照），每次派发/回执/验收后更新；重开先读它。
 - **回收与残留**：派生会话验收通过即 `close --task <编号> <别名>`；常驻会话不回收，需重开时 `ensure --force`；`status` 残留即核对回收。
@@ -98,13 +98,14 @@ updated: 2026-10-28
 - [ ] PM 亲自合并 PR / `push` main？（合并由 RD 执行，PM 只验收授权；§十三）
 - [ ] 未过验收 / 门禁未绿就打 tag 或 release，或 tag 指向非 main 合并提交？（§十三）
 - [ ] main 上出现多条本需求提交或 `wip()` 提交（未 squash）？提交 / PR 标题不可读（纯编号/类名/路径）？
+- [ ] 为文档 / 台账单开 PR，或任务期文档作为独立提交直落 main？（应随任务 PR；例外仅 BR3 立项摘要，见 @.agents/skills/github-flow.md）
 - [ ] Issue 与 `docs/` 双源（正文抄进 Issue / 状态只留平台）？（§十三）
 - [ ] `git push --force` 到 main/共享分支（未经用户明确授权并指明分支）？
 - [ ] release notes 不可读（纯编号/类名/路径），或未落盘 `docs/releases/`？
 - [ ] 输出里有 `warn`/`error`/`pending approval`/`N vulnerabilities` 却判完成？（`exit 0` ≠ 完成，见 @.agents/skills/task-completion.md §三）
 - [ ] 降级（无 `gh` / 无远端）未在 `tasks-state` 与回执中标注？
 
-> 完整红线（33 项）与交付检查清单（41 项）：**交付/派发前**读取 @.agents/checklists/pm.md 逐项核对。
+> 完整红线（34 项）与交付检查清单（42 项）：**交付/派发前**读取 @.agents/checklists/pm.md 逐项核对。
 
 ## 十一、交付检查清单
 
@@ -120,7 +121,7 @@ PRD 完成且交付闭环后**当日**落 `docs/prds/YYYY-MM-DD-<主题>.md`（
 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 在开工确认卡指定。
+- **PR**：PM 在 PR 评论核 AC；**验收通过 = 授权合并**；不点合并按钮。Reviewer 与 PR owner 在开工确认卡指定。**文档随任务 PR**：台账（`docs/tasks-state.md`）/ PRD 定稿 / 报告 / ADR / release notes 均在本任务 PR 内路径级提交，**不为文档单开 PR、不把任务期文档独立提交到 main**（立项摘要例外仅限 BR3 三条件，降级批次无此例外）。
 - **发布（优先 `gh`）**：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 仍可用）→ `gh release create <tag> --title "vX.Y.Z" --notes-file docs/releases/<version>.md`（**标题口径（强约束）：@.agents/common/release-notes.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。

package/.agents/skills/github-flow.md

@@ -14,19 +14,33 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 - **短生命周期分支**：一个需求一条分支，存活 ≤ 一个批次；跨天过长就拆需求。
 - **边界对齐**：一个批次 ≡ 一个需求 ≡ 一个父 Issue ≡ 一条分支 ≡ 一个 PR（前后端分离则每仓库一条）。
 - **合并权在 RD，闸门在 PM**：PM **验收通过前不得合并**；合并由 RD 在 PR 上执行，**PM 不亲自合并**。
+- **一个任务 PR = 全量改动**：实现 / 测试 / 文档（PRD 定稿 · 验收报告 · ADR · `tasks-state` 台账 · 报告 · 索引 · release notes）同属**一条** PR；**文档不单开 PR、不独立落 main**（唯一例外 = 立项摘要，细则见「文档与台账载体（一任务一 PR）」）。
 
 ## 八阶段
 
 | # | 阶段 | 主责 | 动作 | 产出 |
 | :--- | :--- | :--- | :--- | :--- |
-| 1 | 立项 | PM | 建 Issue（用户故事 / AC / 优先级 / 里程碑）+ PRD 正文落 `docs/prds` | 可追踪 Issue |
-| 2 | 拆分排期 | PM | 拆任务、定 PR owner / Reviewer / 分支名 | 开工确认卡 |
-| 3 | 起分支 | RD | 从 main 拉 `feat/<issue-id>-<slug>`，开 **Draft PR** | Draft PR + CI |
-| 4 | 开发提交 | RD | 小步 `wip(<编号>):` 提交，push 触发 CI | 增量代码 + CI 结果 |
-| 5 | 评审测试 | RD / QA / Reviewer | 填 PR 模板、QA 跑全量门禁、预览环境验证 | Review 通过 |
-| 6 | 验收合并 | PM → RD | PM 逐条核 AC 并在 PR 评论；**通过后由 RD squash 合并、删分支** | main 上 1 条提交 |
-| 7 | 发布 | PM | 版本号 + tag + Release notes（优先 `gh`） | Release 记录 |
-| 8 | 复盘 | PM | 监控指标、关 Issue、归档 PRD | 复盘 + 归档 |
+| 1 | 立项 | PM | 建 Issue（用户故事 / AC / 优先级 / 里程碑）+ PRD 正文落 `docs/prds` | 可追踪 Issue + **PRD 定稿（随本 PR）** |
+| 2 | 拆分排期 | PM | 拆任务、定 PR owner / Reviewer / 分支名 | 开工确认卡 + **`docs/tasks-state.md` 登记（随本 PR）** |
+| 3 | 起分支 | RD | 从 main 拉 `feat/<issue-id>-<slug>`，开 **Draft PR** | Draft PR + CI（+ 立项摘要，唯一例外） |
+| 4 | 开发提交 | RD | 小步 `wip(<编号>):` 提交，push 触发 CI | 增量代码 + CI 结果 + 阶段文档（ADR / 报告，**随本 PR**） |
+| 5 | 评审测试 | RD / QA / Reviewer | 填 PR 模板、QA 跑全量门禁、预览环境验证 | Review 通过 + QA 报告 / 用户验收清单（`docs/reports/`，**随本 PR**） |
+| 6 | 验收合并 | PM → RD | PM 逐条核 AC 并在 PR 评论；**通过后由 RD squash 合并、删分支** | main 上 1 条提交（**含该任务全部文档改动**） |
+| 7 | 发布 | PM | 版本号 + tag + Release notes（优先 `gh`） | Release 记录 + notes 落 `docs/releases/`，批间收尾事实随发布提交带走 |
+| 8 | 复盘 | PM | 监控指标、关 Issue、归档 PRD | 复盘 + 归档（随发布提交或**下一任务 PR**） |
+
+## 文档与台账载体（一任务一 PR）
+
+**一个任务 PR = 该任务全量改动**（BR1）：文档与台账不另立载体，`docs/` 改动一律随该任务的 PR 进 main。
+
+- **BR1 全量（一 PR 含全部改动）**：任务 PR 必须包含该任务**全部文件改动** —— 实现 / 测试 / PRD 定稿 / 验收报告 / ADR / `docs/tasks-state.md` / `docs/reports/*-followups.md` / `docs/prds/README.md` 索引 / `docs/releases/<v>.md`。验收读 PR diff 即见文档变化；回滚 `git revert` 单条即整需求。
+- **BR2 禁令**：① 禁止为文档 / 台账**单开 PR**；② 禁止任务期文档作为**独立提交直落 main**（唯一例外见 BR3）。发布提交（阶段 7）承载批间收尾事实，不计入本禁令。
+- **BR3 立项例外（三条件同时满足才可用）**：① **仅用于**建 Issue / 定分支名所需的最小摘要；② 内容上限 = **最小摘要三要素**（TL;DR + AC 编号 + PRD 路径指针），正文仍留 `docs/`，**禁抄正文**；③ **单条** `docs(<编号>):` 提交、只含该摘要文件、**不与其它改动混提**。**降级批次（无 Issue）无此例外**。
+- **BR4 谁提交**：PM 在需求分支做**路径级**提交（`git add <具体路径>`，`docs(<编号>):` 前缀，**禁 `-A`**、禁 push main）；RD 最终 squash 时一并带入。同 worktree 并行时，提交方**只暂存自己的路径**。
+- **BR5 批间收尾**：合并后产生的事实（npm 核验结果 / Release 标题核验 / 角色卡广播登记 / 会话交接快照）随**发布提交一次带走**；发布提交之后才产生的事实，登记进**下一个任务 PR** 或下一次发布提交，**不得单独提交 main**。
+- **BR6 可读性不变**：PR 标题与 `gh pr merge --squash --subject` 仍须用户可读（禁纯编号 / 类名 / 路径）；文档改动不降低该要求。
+- **自查三条（可执行）**：main 上本任务提交数（`git log --oneline main | grep -c '(<编号>)'`）· 本 PR diff 是否含 `docs/` 路径（`git diff --name-only main...HEAD | grep '^docs/'`）· 工作区干净（`git status --porcelain` 为空）。
+- **验证接缝**：文本口径由一次性只读探针核（如 `docs/reports/<日期>-*-probe.sh`），不进 `tests/`。
 
 ## 分支与提交
 
@@ -69,6 +83,7 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 | 分支 | `feat/<issue-id>-<slug>` | `nao/<批次-slug>` |
 | 评审 | PR + CI + 预览环境 | 本地全量门禁 + PM 读 diff |
 | 合并 | PR squash merge | PM 验收通过后，RD 本地 `git merge --squash feat/… && git commit` + 删分支 |
+| 文档载体 | 随任务 PR（PR diff 含 `docs/`） | 同样在本地分支提交并由 `merge --squash` 带入 main，**不另开文档提交** |
 | 发布 | `gh release create` | `git tag -a` + notes 落 `docs/releases/` |
 
 降级须在 `tasks-state` 与回执中标注「降级」。
@@ -77,6 +92,7 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 
 - [ ] 未过 PM 验收就合并 PR，或直推 main？
 - [ ] main 上出现多条本需求提交，或出现 `wip()` 提交（未 squash）？
+- [ ] 为文档 / 台账**单开 PR**，或任务期文档作为**独立提交直落 main**（立项摘要例外见 BR3）？
 - [ ] PM 亲自执行合并 / `push` main？
 - [ ] Issue 与 `docs/` 双源（正文抄进 Issue，或状态只留平台）？
 - [ ] 未过验收 / 门禁未绿就打 tag，或 tag 指向非 main 提交？

package/package.json

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