@nathan33/nao-skill 0.17.0 → 0.17.3

package/.agents/checklists/deliverable-docs.md

@@ -49,15 +49,18 @@ description: 交付文档写作规范（PRD/ADR/报告/调研：简洁、可读
 - 推演细节（RICE 打分过程、5 Whys 展开、同类产品调研明细）落 `docs/research/` 或附录，**正文只留结论 + 指针**
 - **⛔ PRD 正文不使用表格** ⇒ 改用**有序 / 无序列表 + 加粗字段名**（如 `- **版本**：1.12.3`）。最常被误写成表格的三处：**需求清单（用户故事 / 条目）· 验收标准（AC）· 范围 / 非范围**。
 
-## 四、ADR（≤60 行）
+## 四、ADR（≤60 行，按 `wc -l` 全文）
 
 ```text
-背景(≤5 行) → 决策(1–3 句) → 理由(四步法要点，每点一行) → 对照模式表(模式/适用条件/代价/不采纳理由)
-→ 参考来源(链接 + 访问日期) → 后果与风险 → 相关指针
+背景(≤5 行) → 决策(1–3 句) → 理由(四步法要点，每点一行) → 对照模式清单(模式/适用条件/代价/不采纳理由)
+→ [后果与风险] → [限制与已知边界] → [相关指针] → 参考来源(链接 + 访问日期，恒末节)
 ```
 
-- 方案细节、压测数据、对比实验**不写进 ADR**：另存文件并在「相关指针」给路径。
-- 模板见 @.agents/skills/arch-patterns.md。
+- **必写 5 节**：`## 背景` / `## 决策` / `## 理由` / `## 对照过的备选模式` / `## 参考来源`；**可选 3 节**：`## 后果与风险` / `## 限制与已知边界` / `## 相关指针`。标题逐字、不编号、顺序固定（`参考来源` 恒为末节）。
+- **头部恰 4 字段**：`状态` / `更新` / `Owner` / `指针`；`出具日` = 文件名日期前缀（不单设字段），`落地版本` = `状态` 值（不单设字段）。
+- **状态值域 4 值**：`提议` / `已接受（待落地）` / `已接受（已落地 vX.Y.Z）` / `已废弃（被 <yyyy-mm-dd-slug> 取代）`（本仓 ADR 无编号，禁 `ADR-N` 写法）。
+- **禁写 / 下沉清单**（写进正文即违规，一律另存 `docs/reports/<编号>-arch-review.md`）：实施闸门 / 接线清单 / 交接实现 / 判定式全文 / 用例集。**边界优先于上限**：超长先下沉，不放宽 60 行。
+- 骨架唯一载体（单源）：@.agents/templates/adr.md.example；模式对照法见 @.agents/skills/arch-patterns.md；索引骨架见 @.agents/templates/adr-index.md.example。
 
 ## 五、测试报告（≤80 行）
 

package/.agents/common/release-notes.md

@@ -20,6 +20,8 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
    - 只写内部机制（改了哪个函数 / 状态）不合格；要写**用户会看到什么、能做什么、不能做什么**。
    - 例：_点过之后按钮会变「已撤销」且不可再点_（✅）—— 而非「按钮加 `aria-disabled`」（⛔）。
 4. **口径与落盘一致**：`docs/releases/<version>.md` 是权威落盘；`gh release create --notes-file <该文件>` 与之一同源，禁止两处各写各的。
+5. **Release 标题 = 裸版本号 `vX.Y.Z`**（仅版本号，可带预发布后缀如 `-beta.1`；不得含描述性文本 / `—`、`·`、`：` 副题 / 编号 / 日期）。
+   - 标题**不用构思**：一句话概括等描述性内容**一律置于正文首段「本次更新」**（见 §二.1）；`--title` 只写 `<tag>` 本身。
 
 ## 二、建议结构（顺序固定，用不上的段可省）
 
@@ -49,6 +51,7 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
 - [ ] 结构完整（一句话 → 变化 → 技术细节）；内部信息集中在「技术细节」段。
 - [ ] 正文**未使用表格**（改用有序 / 无序列表；见 @.agents/checklists/deliverable-docs.md）。
 - [ ] `docs/releases/<version>.md` 与 GitHub Release 正文同源。
+- [ ] Release 标题是**裸 `vX.Y.Z`**（无描述性文本 / 副题；见 §一.5）。
 
 ## 五、红线
 
@@ -56,3 +59,4 @@ description: 发版说明写作规范（面向用户、说人话；写 / 验收
 - [ ] 正文里直接出现编号 / 哈希 / 类名 / 属性名 / 测试例数？
 - [ ] 没有面向用户的「本次更新」段，或它不在最前？
 - [ ] 盘上 release notes 与 Release 正文两处不一致？
+- [ ] Release 标题带了描述性文本 / 分隔副题（应为裸 `vX.Y.Z`）？

package/.agents/prompts/architecture-designer.md

@@ -1,8 +1,8 @@
 ---
 description: 资深系统架构师角色 Prompt（短常驻）——架构设计/技术选型/评审/ADR
 role: arch-designer
-version: 11
-updated: 2026-10-13
+version: 12
+updated: 2026-10-14
 ---
 
 # 架构设计师
@@ -85,8 +85,10 @@ PRD 摘要/路径、范围与非范围、NFR 基线（缺失必须索要）、
 ## 十一、归档（ADR）
 
 - 落盘 `docs/adr/YYYY-MM-DD-<简短主题>.md`（日期取评审终签日）。
+- 骨架唯一载体（单源）：@.agents/templates/adr.md.example（必写 5 节 + 可选 3 节，`参考来源` 恒为末节）；字段口径与禁写边界见 @.agents/checklists/deliverable-docs.md §四。
 - ADR 必含：`参考来源`（链接 + 访问日期）与 `对照过的备选模式`（含不采纳理由）；无外部来源则写「未检索到」。
-- 首次归档创建 `docs/adr/README.md` 索引（日期 | 主题 | 决策 | 状态）。
+- 实施类内容（闸门 / 清单 / 实现细节 / 用例集）下沉 `docs/reports/<编号>-arch-review.md`，ADR 正文不含。
+- 首次归档创建 `docs/adr/README.md` 索引：骨架见 @.agents/templates/adr-index.md.example（日期 | 主题 | 决策 | 状态，决策列 ≤20 字）。
 
 ## 十二、硬性红线
 

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

@@ -1,7 +1,7 @@
 ---
 description: 产品经理角色 Prompt（短常驻）——需求分析/PRD/优先级/验收/多会话调度
 role: pm
-version: 24
+version: 25
 updated: 2026-10-14
 ---
 
@@ -118,7 +118,7 @@ PM 负责 **Issue 立项与同步、PR 验收与评论、Tag Release、仓库治
 
 - **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> --title "<用户可读标题>" --notes-file docs/releases/<version>.md`；不可用降级 `git tag -a` + `git push origin <tag>`。**不自动 `gh auth login`**。
+- **发布（优先 `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。
 - **回滚**：已 push 的 tag 不删（改发下一个 PATCH），除非用户明确要求。

package/.agents/skills/arch-patterns.md

@@ -41,21 +41,10 @@ graph TD
 
 ## ADR 模板
 
-```md
-# ADR-<编号>: <标题>
-- 日期：YYYY-MM-DD
-- 状态：提议 / 已接受 / 已废弃
-- 背景：<问题与约束>
-- 决策：<选择了什么>
-- 理由：<对照四步法分析>
-- 对照过的备选模式：<模式 → 不采纳原因（含"维持现状"基线）>
-- 参考来源：<[标题](链接) · 访问 YYYY-MM-DD；无则写"未检索到">
-- 备选方案：<列表 + 否决理由>
-- 后果：<正面 / 负面 / 风险>
-- 相关：<PRD / 关联 ADR / docs/research 路径>
-```
-
-> 长度上限 60 行、骨架与必写/可省/禁写见 @.agents/checklists/deliverable-docs.md §四。
+- **骨架唯一载体（单源）**：@.agents/templates/adr.md.example —— 复制后按「必写 5 节 + 可选 3 节」填空（标题逐字、顺序固定，`参考来源` 恒为末节）。
+- **模式对照法**：写入前先做上面对照四步法，把 ≥2 个候选的「不采纳理由」写进 `## 对照过的备选模式`（含「维持现状」基线）。
+- **字段口径与边界**：状态值域 4 值 / 头部 4 字段 / ≤60 行 / 禁写下沉清单，见 @.agents/checklists/deliverable-docs.md §四。
+- **索引登记**：每篇 ADR 在 `docs/adr/README.md` 追加一行（决策列 ≤20 字），索引骨架见 @.agents/templates/adr-index.md.example。
 
 ## 误区
 

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

@@ -53,7 +53,7 @@ PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合
 
 - 版本号：SemVer，PM 按批次范围定（feat→MINOR / fix→PATCH / 破坏性→MAJOR）；项目 `AGENTS.md` 有约定则从之。
 - 门禁：AC 全过 + 验收闭环 + main 门禁全绿 + 工作区干净 + PR 已合并。
-- **优先 `gh`**：`gh release create <tag> --title "<用户可读标题>" --notes-file docs/releases/<version>.md`。
+- **优先 `gh`**：`gh release create <tag> --title "vX.Y.Z" --notes-file docs/releases/<version>.md`（**标题口径（强约束）：@.agents/common/release-notes.md** —— 标题仅裸版本号，描述进正文首段）。
 - 探测：`gh auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 **仍可用**，可 `gh api user` 复核）；**不自动 `gh auth login`**（涉用户凭证）。
 - release notes 落盘 `docs/releases/<version>.md`（**写作规范（强约束）：@.agents/common/release-notes.md** —— 面向用户「本次更新」置顶、内部编号 / 文件名 / 属性名一律下沉「技术细节」、正文不用表格；骨架见 @.agents/templates/release-notes.md.example）。
 - 回滚：未 push → `git tag -d`；已 push → **不删远端 tag**，改发下一个 PATCH 修正（用户明确要求才删）。

package/.agents/templates/adr-index.md.example

@@ -0,0 +1,11 @@
+<!-- ADR 索引骨架单源（T520）：复制为 docs/adr/README.md 后逐行追加；决策单元格 ≤20 字（短结论，细节留在各 ADR 正文）。 -->
+
+# ADR 索引（架构决策记录）
+
+> 约定见 @.agents/prompts/architecture-designer.md §十一：落盘 `docs/adr/YYYY-MM-DD-<简短主题>.md`（日期取评审终签日）；
+> 每篇必含 `参考来源`（链接 + 访问日期）与 `对照过的备选模式`（含不采纳理由）。
+> 本文件是**索引**，不是条款出处；机制条款以 `.agents/` 为准（单一事实来源）。
+
+| 日期 | 主题 | 决策 | 状态 |
+| :--- | :--- | :--- | :--- |
+| YYYY-MM-DD | [<简短主题>](YYYY-MM-DD-<slug>.md) | <≤20 字短结论> | <状态值域其一> |

package/.agents/templates/adr.md.example

@@ -0,0 +1,45 @@
+<!-- ADR 骨架单源（T520）：复制为 docs/adr/YYYY-MM-DD-<简短主题>.md 后逐节填空；日期取评审终签日。
+     规范口径 @.agents/checklists/deliverable-docs.md §四 · 模式对照 @.agents/skills/arch-patterns.md · 索引登记 @.agents/templates/adr-index.md.example。 -->
+
+<!-- 禁写下沉清单（一律另存）：实施闸门 · 接线清单 · 交接实现 · 判定式全文 · 用例集。 -->
+
+# ADR：<简短主题>
+
+- 状态：提议 / 已接受（待落地） / 已接受（已落地 vX.Y.Z） / 已废弃（被 <yyyy-mm-dd-slug> 取代）
+- 更新：YYYY-MM-DD
+- Owner：<角色>
+- 指针：<上游 PRD / 评审报告 / 关联 ADR 相对路径>
+
+## 背景
+
+- <问题、约束、触发原因；≤5 行>
+
+## 决策
+
+<选择了什么；1–3 句>
+
+## 理由
+
+1. <业务匹配 / 成熟度 / 团队能力 / 成本 四步法要点，每点一行>
+
+## 对照过的备选模式
+
+1. **<候选模式（含「维持现状」基线）>** —— 适用：<条件>；代价：<代价>；<采纳 / 不采纳理由>。
+
+<!-- 可选节：按需保留，顺序固定；参考来源恒为末节。 -->
+
+## 后果与风险
+
+- <正面 / 负面 / 风险>
+
+## 限制与已知边界
+
+- <适用范围边界 / 不覆盖项 / 不追溯项>
+
+## 相关指针
+
+- <骨架 / 规范 / 评审报告 / 关联文档路径>
+
+## 参考来源
+
+- [<标题>](<链接>) · 访问 YYYY-MM-DD · <一句话结论>；无外部来源则写「未检索到」。

package/.agents/templates/release-notes.md.example

@@ -2,6 +2,7 @@
   release notes 骨架 —— 复制为 docs/releases/<version>.md 后逐段填空。
   权威规范：@.agents/common/release-notes.md
   用法：把面向用户的「本次更新」放在最前；内部信息一律下沉「技术细节（可略过）」。
+  Release 标题 = 裸 `vX.Y.Z`（仅版本号，描述性概括进正文首段）—— 权威单处 @.agents/common/release-notes.md §一.5。
   ⛔ 自查：正文无编号 / 哈希 / 文件名 / 函数名 / 内部属性名 / 测试例数 / 守卫名 / 内部模块名；正文不要用表格。
 -->
 

package/README.md

@@ -24,7 +24,7 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
    ```bash
    cd 你的项目
-   pi install --local npm:@nathan33/nao-skill@0.17.0   # 声明 pin + 把机制包物化到项目内 .pi/npm
+   pi install --local npm:@nathan33/nao-skill@0.17.3   # 声明 pin + 把机制包物化到项目内 .pi/npm
    npx @nathan33/nao-skill init                        # 写入转发 shim + 生成 AGENTS.md
    ```
 

package/package.json

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