@nathan33/nao-skill 0.6.0 → 0.7.0

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

@@ -2,14 +2,30 @@
 description: 按需技能——架构模式速查 + ADR 模板
 ---
 
-# 架构模式速查
+# 架构模式对照与 ADR
 
-| 场景 | 推荐架构 | 关键技术 |
-| :--- | :--- | :--- |
-| 高并发交易 | 微服务 + 事件驱动 | Kubernetes, Kafka, Redis |
-| 大数据处理 | Lambda 架构 | Spark, Flink, S3 |
-| 多租户 SaaS | 多租户 + 模块化 | PostgreSQL schemas, API Gateway |
-| 实时系统 | 事件溯源 + CQRS | Event Store, gRPC |
+> 用法：先写清约束，再**对照**候选模式；禁止直接接表选型（同场景不同团队/规模，结论相反）。
+> 检索与引用纪律见 @.agents/skills/research.md（报告落盘 `docs/research/`）。
+
+## 模式对照表（场景信号 → 候选 → 适用条件 → 代价 → 何时别用）
+
+| 场景信号 | 候选模式 | 适用条件 | 代价 / 风险 | 何时别用 |
+| :--- | :--- | :--- | :--- | :--- |
+| 单团队、领域未定、读写同源 | 模块化单体 | 团队 <10 人、交付速度优先、边界待验证 | 后期拆分成本；模块纪律靠评审守 | 多团队并行交付、需独立扩缩容 |
+| 读远多于写、查询形态多 | CQRS | 读写比悬殊、需要多种读模型 | 双模型同步、最终一致、运维面变大 | 以强一致读为主、数据量小 |
+| 需完整审计与回放 | 事件溯源 | 合规/审计/时间旅行需求真实存在 | 事件版本迁移、查询复杂、删除权难处理 | 普通 CRUD、无审计需求 |
+| 跨服务/跨库的事务 | Saga / Outbox | 无法用单库事务、需要可靠消息 | 补偿逻辑、幂等设计、调试难度 | 单库事务可覆盖 |
+| 峰值差大、多方消费 | 消息队列 / 事件驱动 | 需削峰或解耦、消费方 ≥2 | 运维成本、顺序与幂等、可观测性 | 请求-响应强耦合、无峰值 |
+| 多租户 SaaS | schema / RLS / 库级隔离 | 按租户数 + 隔离要求分档选 | 迁移复杂、噪声邻居、连接池压力 | 少数强隔离租户（该独立部署） |
+| 多端体验差异大 | BFF | 端形态（Web/移动/第三方）差异成主要成本 | 多一层维护与部署 | 单端产品 |
+| 依赖不稳的三方集成 | 网关 + 熔断 + 退避 | 外部依赖有抖动历史、影响主链路 | 复杂度、配置治理 | 内部可信调用 |
+
+## 对照四步法（写入 ADR 前必做）
+
+1. **写清约束**：NFR 基线、团队规模与熟悉度、预算与工期、迁移成本、既有约束（`AGENTS.md`）。
+2. **列 ≥2 个候选模式**（含"维持现状/最小改动"这个基线候选）。
+3. **逐条打分**：适用条件是否成立 → 代价能否承受 → 团队能否维护。
+4. **记录不采纳理由**：写进 ADR（不采纳的原因比采纳理由更有审计价值）。
 
 ## 最小示例
 
@@ -31,12 +47,16 @@ graph TD
 - 状态：提议 / 已接受 / 已废弃
 - 背景：<问题与约束>
 - 决策：<选择了什么>
-- 理由：<四步法分析>
+- 理由：<对照四步法分析>
+- 对照过的备选模式：<模式 → 不采纳原因（含"维持现状"基线）>
+- 参考来源：<[标题](链接) · 访问 YYYY-MM-DD；无则写"未检索到">
 - 备选方案：<列表 + 否决理由>
 - 后果：<正面 / 负面 / 风险>
-- 相关：<PRD / 关联 ADR>
+- 相关：<PRD / 关联 ADR / docs/research 路径>
 ```
 
+> 长度上限 60 行、骨架与必写/可省/禁写见 @.agents/checklists/deliverable-docs.md §四。
+
 ## 误区
 
 - 过度设计 / 追新 → 务实、成熟稳定优先

package/.agents/skills/commit.md

@@ -8,11 +8,43 @@ description: 按需技能——Git 提交规范（仅在执行 git commit 前读
 
 仅在执行 `git commit` 前读取本文件；其他时候不加载。
 
+本文件同时约束**提交落在哪条线**（需求分支）与**合并方式**（PR squash）。派发消息会给出分支名；**未给出时先问 PM，禁止自行提交到 main**。完整流水线见 @.agents/skills/github-flow.md。
+
 ## 流程
 
-1. `git diff --cached` 与 `git diff --cached --stat` 查看暂存变更
-2. `git log --oneline -10` 参考近期提交风格
-3. 按格式编写提交消息，执行 `git commit -m "消息"`
+1. 确认当前分支是需求分支 `feat/<issue-id>-<slug>`（降级 `nao/<批次-slug>`，**不是 main**）
+2. `git diff --cached` 与 `git diff --cached --stat` 查看暂存变更
+3. `git log --oneline -10` 参考近期提交风格
+4. 按格式编写提交消息，执行 `git commit -m "消息"`
+
+## 提交时机与分支（需求分支制）
+
+**main 只收 squash 合并后的 1 条提交；过程中的提交一律落在需求分支。**
+
+- **需求分支**：派发消息给出 `feat/<issue-id>-<slug>`（无 Issue 时 `nao/<批次-slug>`）。分支不存在时由**首个被派发的 RD** 从 main 拉出并在回执中注明；之后所有 worker 都在该分支提交。
+- **过程提交（检查点）**：每完成一段可自测的逻辑就提交一次，前缀 `wip(<编号>): <可读短语>`。这类提交**可以多、可以小**，只作检查点/归因/回退用，**永不上 main**（合并时被 squash 吸收）。
+- **暂存纪律**：只 `git add <自己负责的路径>`；**禁 `git add -A` / `git add .` / `git commit -a`**——同一工作区有多个会话并行，全量暂存会把别人未完成的改动一起卷进提交。
+- **禁止直推 main / 绕过 PR 合并**：feature 分支允许 `--force-with-lease`（改基 / 压缩历史时），main 永远禁止 force push。
+- **回执必带**：`commit=<短 hash>`，便于 PM 核对归因。
+
+## 合并（squash，由 RD 在 PM 验收通过后执行）
+
+- **闸门**：PM 验收通过 = 授权合并；**PM 不亲自合并、不 push main**。未过验收一律不得合并。
+- 正常（有远端 + `gh`）：`gh pr merge <n> --squash --delete-branch`；提交信息取 PR 标题 + 正文，因此**可读性硬性落在 PR 标题**。
+- 降级（无远端 / 无 `gh`）：`git checkout main && git merge --squash feat/… && git commit` + 删分支。
+- 合并后：main 上本需求**恰好 1 条提交**，且不含任何 `wip()` 提交；不符则回退重做。
+- 合并前清理：工作区干净、无游离文件、分支已 push 到最新。
+
+## 特殊情况白名单（封闭列举，其余一律走需求分支 + PR）
+
+只有以下情况可**直接提交并推送目标分支**（不经 PR 流程）；均须在 `docs/tasks-state.md` 标注原因：
+
+1. 线上 Hotfix（走 `hotfix/<issue-id>` 分支 + PR 快速合并，事后补 Release 与变更单）；
+2. 前后端分离且后端契约需先提交/推送，前端才能消费；
+3. 依赖/构建/CI 变更需被其他会话或流水线立刻消费；
+4. 用户显式要求提交。
+
+「其他特殊情况」须由**用户确认**；PM 不得自行开口子。
 
 ## 消息格式
 
@@ -29,6 +61,14 @@ description: 按需技能——Git 提交规范（仅在执行 git commit 前读
 - 依赖/配置/构建等非功能变更
 ```
 
+**可读性（硬性）**：提交信息是给**用户/未来的自己**看的，不是给编译器看的。
+
+- 标题与变更点写「**用户能得到什么 / 行为怎么变**」，如「支持按当前筛选条件导出 CSV（含表头与中文编码）」。
+- **禁止**只写编号、类名、函数名、文件路径、字段名、包路径（如 `实现 exportCsvHandler 与 ExportService`、`完成 AC1`、`改 packages/domain-task`）。
+- 任务编号只作追溯用，放标题**尾部** `[T1]` 或关联 Issue `(#123)`，不替代描述。
+- **main 上的可读性由 PR 标题承担**（squash 合并取 PR 标题）；PR 标题同样禁纯编号/类名/路径。
+- `scope` 用可读的模块/功能名（`导出`、`日历`），不用包路径。
+
 ## 类型（可扩展）
 
 - feat   新增功能
@@ -39,6 +79,7 @@ description: 按需技能——Git 提交规范（仅在执行 git commit 前读
 
 ## 规则
 
+- **先写用户可见的行为变化**，再补技术细节；纯技术变更（如依赖升级）也写清「会带来什么」
 - 变更点列出主要逻辑或用户可见变动，描述具体
 - 其他仅放配置文件、依赖版本（注明旧→新版本号）等
 - 避免重复，已列变更点的不再写其他
@@ -47,7 +88,7 @@ description: 按需技能——Git 提交规范（仅在执行 git commit 前读
 ## 示例
 
 ```text
-feat(calendar): 日期时间选择器显示当前选中值
+feat(日历): 日期时间选择器显示当前选中值 [T3]
 
 变更点：
 
@@ -60,9 +101,18 @@ feat(calendar): 日期时间选择器显示当前选中值
 - 升级 dayjs 从 1.10.7 到 1.11.5
 ```
 
+反例（不可读，禁止）：
+
+```text
+feat(T1): 实现 exportCsvHandler
+变更点：
+- 新增 ExportService 与 CsvWriter
+- 调整 packages/domain-task 接口
+```
+
 ## 注意事项
 
-- 提交前确保所有变更已暂存
-- 尽量拆分逻辑独立的提交
+- 工作期暂存只用**路径级** `git add <路径>`；降级本地 squash 合并时才允许 `git add -A`
+- 工作期提交可小而多（检查点）；**main 上每个需求恰好 1 条提交**（PR squash 产生），不在分支上拆分主线提交
 - 使用中文，简洁准确
 - 禁止提交未测试或含调试代码的变更

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

@@ -0,0 +1,82 @@
+---
+description: 按需技能——新需求落地流水线（Issue → 分支 → PR → 验收 → squash 合并 → Release；GitHub Flow / trunk-based）
+---
+
+# 新需求落地流水线（GitHub Flow）
+
+## 触发时机
+
+PM 在**立项 / 终签 / 发布**时读取；RD 在**起分支 / 开 PR / 合并**时读取；QA 在 **PR 验证**时读取。日常轮次不加载。
+
+## 原则
+
+- **main 始终可发布**：main 只接收经 PR + 验收的 **squash 合并（1 条 = 1 需求）**。
+- **短生命周期分支**：一个需求一条分支，存活 ≤ 一个批次；跨天过长就拆需求。
+- **边界对齐**：一个批次 ≡ 一个需求 ≡ 一个父 Issue ≡ 一条分支 ≡ 一个 PR（前后端分离则每仓库一条）。
+- **合并权在 RD，闸门在 PM**：PM **验收通过前不得合并**；合并由 RD 在 PR 上执行，**PM 不亲自合并**。
+
+## 八阶段
+
+| # | 阶段 | 主责 | 动作 | 产出 |
+| :--- | :--- | :--- | :--- | :--- |
+| 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 | 复盘 + 归档 |
+
+## 分支与提交
+
+- 命名：`feat/<issue-id>-<slug>`；无 Issue 时降级 `nao/<批次-slug>`；hotfix 用 `hotfix/<issue-id>`。
+- **禁止** `git push` 到 main、**禁止绕过 PR 合并**；feature 分支允许 `--force-with-lease`（改基 / 压缩历史时）。
+- 提交规范、`wip()` 前缀、路径级暂存、可读性：见 @.agents/skills/commit.md。
+- **squash 后 main 上的提交信息 = PR 标题 + PR 正文** → **可读性硬性落在 PR 标题**（用户可见行为，禁纯编号/类名/路径）。
+
+## Issue 与状态（避免双源）
+
+- **Issue = 入口 / 摘要 + 指针**：body 只放 TL;DR、AC 编号、优先级、`docs/prds/...md` 指针。
+- **`docs/` = 正文权威**（PRD 全文、`tasks-state.md` 运行时状态）：离线可用、会话重开读本地。
+- **同步时机（仅 5 个节点）**：立项、派发、验收通过、合并、发布——其余不动 Issue，省 gh 往返。
+- Issue 上的业务讨论由 PM **摘录进 `docs/`**，不留在平台。
+
+## PR 模板与 Reviewer
+
+- 模板 `.github/pull_request_template.md`（PM 从 `.agents/templates/github/pull_request_template.md.example` 复制建立）。
+- Reviewer 由 PM 在开工确认卡指定（默认 `arch-designer`；纯 CRUD 可写「无」并注明理由）。
+- QA 在 PR 评论贴**门禁精确数字**；PM 在 PR 评论核 AC。
+
+## 发布（阶段 7）
+
+- 版本号：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 auth status` 按 **exit code** 判定（`keyring` 警告但 exit 0 **仍可用**，可 `gh api user` 复核）；**不自动 `gh auth login`**（涉用户凭证）。
+- release notes 落盘 `docs/releases/<version>.md`（规范见 @.agents/checklists/deliverable-docs.md）。
+- 回滚：未 push → `git tag -d`；已 push → **不删远端 tag**，改发下一个 PATCH 修正（用户明确要求才删）。
+
+## 离线 / 无远端降级
+
+无 `gh` / 无远端 / 未认证时**不阻断交付**，按同构降级（**保持「main = 1 条/需求」不变**）：
+
+| 环节 | 正常 | 降级 |
+| :--- | :--- | :--- |
+| 立项 | GitHub Issue | 摘要写 `docs/prds` + tasks-state，跳过 Issue |
+| 分支 | `feat/<issue-id>-<slug>` | `nao/<批次-slug>` |
+| 评审 | PR + CI + 预览环境 | 本地全量门禁 + PM 读 diff |
+| 合并 | PR squash merge | PM 验收通过后，RD 本地 `git merge --squash feat/… && git commit` + 删分支 |
+| 发布 | `gh release create` | `git tag -a` + notes 落 `docs/releases/` |
+
+降级须在 `tasks-state` 与回执中标注「降级」。
+
+## 红线
+
+- [ ] 未过 PM 验收就合并 PR，或直推 main？
+- [ ] main 上出现多条本需求提交，或出现 `wip()` 提交（未 squash）？
+- [ ] PM 亲自执行合并 / `push` main？
+- [ ] Issue 与 `docs/` 双源（正文抄进 Issue，或状态只留平台）？
+- [ ] 未过验收 / 门禁未绿就打 tag，或 tag 指向非 main 提交？
+- [ ] PR 标题 / release notes 不可读（纯编号 / 类名 / 路径）？
+- [ ] 降级未标注？

package/.agents/skills/research.md

@@ -0,0 +1,70 @@
+---
+description: 按需技能——外部调研协议（产品形态可查；技术选型归架构师）
+---
+
+# 外部调研协议（research）
+
+> 按需读取：需要「外部既有做法」才能决策时（PM 产品形态 / arch 模式选型 / RD 库用法 / qa 测试惯例）。
+> 工具：`web_search`、`fetch_content`（pi-web-access 插件；未装则回退"已知常识 + 明确标注"）。
+
+## 一、边界（严格：产品可查、技术禁查）
+
+| 谁 | 可调研 | 不可调研（越界） |
+| :--- | :--- | :--- |
+| **PM** | 产品形态：同类功能有哪些功能点、实体属性、组织结构、视图与排序筛选、协作权限、生命周期、通知、导入导出、空/错状态、行业惯例与合规 | **任何技术结论**：该用哪个方案/库/中间件、性能量级、限流与排序语义、契约字段语义、跨端影响面 |
+| **arch** | 架构模式、一致性/容错方案、协议与规范、同类系统的取舍 | 替 PM 改需求与指标 |
+| **RD** | 具体库/API/SDK 用法、报错与版本事实 | 自定架构方案（转 arch） |
+| **qa** | 测试策略、工具与业界用例惯例 | 替代 RD 定实现 |
+
+- PM 命中「不可调研」任一项 → **停止检索，转 arch**（见 PM 卡 §九）。
+- 不确定是否越界 → **按越界处理**。
+- 外部做法一律是**参考与候选**，不是既定前提；**技术前提只能由 arch 以 ADR 定**。
+
+## 二、产品形态调研清单（PM 用，逐项标 有/无/不做）
+
+> 例：需求是「实现一个待办任务应用」时，要系统探索的是**这些**——而不是去查"用什么框架"。
+
+- **功能点集合**：创建/编辑/完成/删除、批量操作、重复任务、子任务、依赖关系
+- **实体属性**：优先级、状态、负责人、截止/开始时间、预计耗时、进度、备注与附件
+- **组织结构**：标签（多标签）、清单/项目分组、层级、模板、收件箱
+- **视图**：列表 / 看板 / 表格 / 日历 / 时间线；排序、筛选、分组、搜索、保存视图
+- **协作与权限**：共享、指派、评论、@提醒、角色与可见范围
+- **生命周期**：归档、回收站与恢复、软删、历史记录
+- **通知提醒**：到期提醒、重复规则、渠道（站内/邮件/推送）
+- **数据进出**：导入导出、第三方集成、API/Webhook
+- **状态完整性**：空态、加载态、错误态、超限态、离线态
+- **惯例与合规**：同类产品的既有交互习惯、无障碍、隐私与数据留存
+
+> 输出：报告内一张表（`项目 × 是否纳入 × 依据/来源`），供 PM 决定 PRD 的「范围 / 非范围」。
+
+## 三、检索纪律（省 token）
+
+1. **先建文件再检索**：先写 `docs/research/YYYY-MM-DD-<主题>.md` 的问题清单与表头——结果有落点，上下文才不留残渣。
+2. **只取 3–5 条一手来源**：官方文档 / 规范 / RFC / 一手实现 > 高质量博客 > 二手综述；**拒内容农场与营销页**。
+3. **引用格式**（每条来源必带）：`- [标题](URL) · 访问 YYYY-MM-DD · 一句话结论`。
+4. **全文只落盘**：抓取内容写进报告文件；线程只回 `≤150 字摘要 + 路径`，**禁止贴正文**。
+5. **查不到就写**「未检索到 / 未联网 / 无公开资料」——**禁止凭印象编造引用**（幻觉引用比没查更糟）。
+
+## 四、适配三栏（禁止照搬）
+
+每条外部做法必须给全三栏：
+
+| 它解决什么 | 适用条件 | 本项目差异（采纳 / 改造 / 不采纳 + 理由） |
+| :--- | :--- | :--- |
+
+> 「业界都这么做」不是理由：适用条件（规模、团队、合规、既有约束）不成立就得写「不采纳」。
+
+## 五、出口（不替代对方结论权）
+
+- PM → PRD「用户场景 / 业务规则 / 范围」；引用来源，**技术前提留空**待 arch。
+- arch → ADR：`参考来源` + `对照过的备选模式（含不采纳理由）`（见 @.agents/skills/arch-patterns.md）。
+- 报告统一落盘 `docs/research/`（归档约定见 @.agents/common/intercom-protocol.md「归档约定」）。
+- 报告正文按 @.agents/checklists/deliverable-docs.md §六 写：结论摘要 ≤5 行、来源带访问日期、适配三栏、抓取正文不进正文（上限 120 行）。
+
+## 六、反模式
+
+- 把链接当结论；把「X 家这么做」当需求依据。
+- 抓取全文贴进消息（污染线程 + 烧 token）。
+- 用外部文章推翻用户已定的约束或项目 `AGENTS.md` 的红线。
+- PM 用外部调研替代 arch 的技术取舍；RD 用它替代实现判断。
+- 无来源、无访问日期的引用。

package/.agents/skills/test-design.md

@@ -30,6 +30,12 @@ description: 按需技能——用例设计、缺陷管理、性能安全、DDD
 - 报告要素：标题、环境版本、复现步骤、预期 vs 实际、日志/截图、影响范围
 - 不 Verify 不关闭；Reopen 有依据
 
+## 测试报告（≤80 行）
+
+- 结构：范围 / 不测 → 环境与命令 → 结果（用例数/通过/失败/exit code）→ 缺陷表 → 未覆盖与风险 → 发布建议
+- **用例集单列文件**（`docs/reports/<编号>-cases.md`）；报告只放汇总与失败项，通过项不罗列（`未过：无` 即可）
+- 完整骨架与必写/可省/禁写见 @.agents/checklists/deliverable-docs.md §五
+
 ## 自动化与 CI/CD
 
 - 测试左移：早参与需求/用例评审

package/.agents/templates/AGENTS.md.example

@@ -23,12 +23,16 @@
 - <领域约束 1，如：任务状态流转只走领域实体方法>
 - <命令纪律，如：禁 cat 全文读代码，用 CodeGraph 或 sed 行段>
 - <依赖限制 / 禁止事项>
+- **Git 流程（GitHub Flow）**：一个需求一条分支 `feat/<issue-id>-<slug>`；工作期 `wip()` 小步提交 + 路径级暂存（禁 `git add -A`）；**PM 验收通过后由 RD 在 PR 上 squash 合并**（main = 1 条/需求）；**禁直推 main**。
+- **发布与仓库治理**：PM 负责 Issue / PR 验收评论 / tag / release / `.github/` 模板（优先 `gh`，不可用降级 `git`）。
 
 ## 与 nao 机制衔接
 
 - **CodeGraph**：本仓库 `.codegraph/` 索引；写完代码 `codegraph sync` 保持新鲜。
 - **UI/UX**：Design Tokens 在 `<src/styles/tokens.css>`；UX Playbook 在 `<docs/ux-playbook.md>`；硬编码色值禁入（`ui-tokens-check.sh` 兜底）。
 - **交付核对**：交付前读取 `@.agents/checklists/<role>.md`（完整红线 + 清单）。
+- **Git 纪律**：提交前读取 `@.agents/skills/commit.md`（需求分支 / 路径级暂存 / 可读信息）；流水线见 `@.agents/skills/github-flow.md`。
+- **流水线**：Issue → 需求分支 → PR → 验收 → squash 合并 → Release，见 `@.agents/skills/github-flow.md`（含离线降级）。
 
 ## 指针（勿复制内容）
 

package/.agents/templates/github/pull_request_template.md.example

@@ -0,0 +1,28 @@
+<!-- 由 PM 在立项时复制为项目 .github/pull_request_template.md（见 @.agents/skills/github-flow.md） -->
+## 需求
+
+- Issue：Closes #<id>
+- PRD：`docs/prds/<file>.md#<section>`
+- 验收标准：AC1 / AC2 / …
+
+## 用户可见变化
+
+<!-- 一句话，用户可读；将作为 squash 提交的标题主体 -->
+
+## 变更点
+
+- <行为变化 1>
+- <行为变化 2>
+
+## 门禁（全量精确数字）
+
+- `<命令>` → exit=<n> · 文件数/例数/红数：<n>/<n>/<n>
+
+## 验收 / 预览
+
+- 预览环境：<URL 或「无」>
+- PM 验收：<待验收 / 通过（日期）>
+
+## 风险 / 回滚
+
+- <风险 + 应对；无则写「无」>

package/.agents/templates/tasks-state.md.example

@@ -3,17 +3,44 @@
 > 每次派发 / 回执 / 验收 / 抢占后更新本文件；PM 会话重开（`ensure --force`）后**先读本文件重建状态**再继续调度。
 > 归档后的历史见 `docs/prds/` 与 `docs/adr/`；本文件只记**运行时**任务状态，保持精简。
 
+## PM 接续快照（会话重开后**先读本区**）
+
+> 本区是 PM 的**悬空状态**（任务状态见下方五栏）。每次重开前更新；重开后逐行回读确认（当前阶段 · 未决决策 · 口头约束）。
+
+- 当前阶段：<澄清 / PRD / 派发中 / 验收中 / 已归档待重开>
+- 当前 PRD：`docs/prds/YYYY-MM-DD-<主题>.md`（状态：<草稿 / 待用户确认开工 / 已开工 / 已归档>）
+- 未决决策点：<等谁拍板 → 事项；无则写「无」>
+- 待用户回答：<Q1 → 问题；无则写「无」>
+- 未派发队列：见下方「待派发队列」（共 N 项）
+- 下次唤醒条件：<用户答复 Q1 / worker 回执 T1 / 定时>
+- 口头约束已落盘：<`AGENTS.md` §… / PRD「变更治理」；无则写「无」>
+- 需求分支 / PR：见下方「需求分支 / PR / 发布」
+- 会话体检：contextTokens=<n>（窗口 <x>%）· 压缩次数=<n> · cacheRead=<x>%（每次归档后更新）
+
+## 需求分支 / PR / 发布（PM 维护）
+
+> 细则见 `@.agents/skills/github-flow.md`；本区只记**运行时**状态。
+
+- Issue：<#123 / 「降级：无 Issue，摘要见 docs/prds/…」>
+- 需求分支：`feat/<issue-id>-<slug>`（降级 `nao/<批次-slug>`）
+- PR owner / Reviewer：<角色> / <arch-designer / 无>
+- PR：<#45（Draft / Ready / 已合并）> · 预览环境：<URL / 无>
+- 合并：<未合并 / 已 squash 合并（main `<hash>`）> · 分支已删：<是/否>
+- 版本 / Tag：<vX.Y.Z · tag 名 · 待发布/已发布（gh 或降级）>
+- 降级标注：<无 / 无 gh · 无远端 · 无预览环境>
+- 特例提交（白名单）：<无 / Hotfix/契约/CI/用户要求 → 简述 + hash>
+
 ## 待派发队列
 
-| 任务编号 | 目标会话 | 角色 | 概要 | 排队原因 |
-| :--- | :--- | :--- | :--- | :--- |
-| T3 | rd-be | 后端 | 实现 X 接口 | 目标忙碌 |
+| 任务编号 | 目标会话 | 概要 | 排队原因 |
+| :--- | :--- | :--- | :--- |
+| T3 | rd-be | 实现 X 接口 | 目标忙碌 |
 
 ## 进行中
 
-| 任务编号 | 目标会话 | 角色 | 概要 | 派发时间 | 对应 AC |
+| 任务编号 | 目标会话 | 概要 | 派发时间 | 对应 AC | WIP 提交 |
 | :--- | :--- | :--- | :--- | :--- | :--- |
-| T2 | rd-fe | 前端 | 登录页 + 校验 | 2026-09-21 14:00 | AC1/AC2 |
+| T2 | rd-fe-T2 | 登录页 + 校验 | 2026-09-21 14:00 | AC1/AC2 | `wip(T2): …`@`<hash>` |
 
 ## 已回执待验收
 
@@ -29,6 +56,6 @@
 
 ## 已验收 / 已归档
 
-| 任务编号 | 结论 | 归档路径 |
-| :--- | :--- | :--- |
-| — | — | `docs/prds/` |
+| 任务编号 | 结论 | main 合并 commit | 归档路径 |
+| :--- | :--- | :--- | :--- |
+| — | — | — | `docs/prds/` |