cgraphx 2.0.2 → 2.0.6

package/dist/.claude-template/FLOW-MAP.md

@@ -20,14 +20,17 @@
                 (手段:无业务可观察→plan 自主;有→回跳 spec)
                         │
                         ▼
-    implementation(简单)│ subagent-implement(复杂,需 plan)
+    implementation(小规模)│ subagent-implement(大规模,需 plan)
                         │
         ┌───────────────┼────────────────────────┐
         ▼               ▼                        ▼
   write-api        write-unit-test-spec     交付收尾:
   → run-api-test   → write-unit-test-code   沉淀提示 → knowledge-write
   (接口测试)     (单元测试,代码完成后)     交付讲解提示 → write-delivery-guide
-                                           commit 门禁 → git-standards.md
+  ↓ 推荐(非硬前置)                          commit 门禁 → git-standards.md
+  write-ui-test
+  → run-ui-test
+  (UI 功能测试)
 
   ── 推荐发布后 · 按需(不在主链,不参与门禁); 原因: 发布前写 PRD:写的是预期,实现过程中一定会漂移,发布后 PRD 就过期了,给业务方看反而误导 ──────────────────
   write-prd(业务方/客户审阅,任意时刻可执行,推荐发布后)
@@ -47,7 +50,7 @@ guides:write-plan 读取并结晶 + 任务打「强制引用」标注(implementa
 
 ## 开发流程
 
-- **链**:`/implementation`(简单:1-3 文件 / 单模块)| `/subagent-implement`(复杂:≥3 任务跨域,主 agent 只协调、派子 agent 实现)
+- **链**:`/implementation`(小规模:单点 / 1-3 文件 / 单模块)| `/subagent-implement`(大规模:预估变更文件 ≥10 且跨 ≥3 独立模块,需 plan,主 agent 只协调、派子 agent 实现);判据是需求规模,不是任务量;拿不准 → implementation,write-plan 的 index「执行方式建议」是终判
 - **前置**:spec 必有;subagent-implement 需 plan
 - **强制读**:规范由 plan 打「强制引用」标注(write-plan 按任务类型机械标:schema → data-standards.md;接口 → interface-standards.md;动码 → coding-standards.md);有 plan 时 implementation / subagent-implement 只读标注,无 plan 时 implementation 自行识别;**缺失 → 中断,先 `/init-project-guides` 补齐**
 - **小步提交**:plan 把可独立提交的任务(完成后仓库可工作)标「独立提交」并把 `git-standards.md` 提交规范结晶进 index「提交规范」节;implementation / subagent-implement 每完成一个标注任务并按规范自查后提交(原子历史,好 review / revert / bisect),precommit 门禁退化为兜底。未标注的任务不擅自提交,push 永远归用户。
@@ -59,6 +62,13 @@ guides:write-plan 读取并结晶 + 任务打「强制引用」标注(implementa
 - **前置**:spec + 实现完成;run-api-test 也可独立跑已有 .bru
 - **强制读**:write-api 执行前读 `docs/guides/interface-standards.md`(缺失 → `/init-project-guides` 中断)
 - **产物**:`docs/bruno/<服务>/<需求前缀>/`(bruno app 可直接打开)+ feature 目录下测试规格与报告
+- **后续**:接口通过后推荐跑 `/write-ui-test` → `/run-ui-test`(UI 功能测试,非硬前置)
+
+## UI 功能测试流程
+
+- **链**:`/write-ui-test`(从 spec 派生用例,一功能点一用例)→ `/run-ui-test`(Playwright MCP 驱动浏览器执行 + 截图 + 报告;**不验库,只看 UI 表现**)
+- **前置**:spec + 实现完成 + 目标项目已装 Playwright MCP;推荐在接口测试后跑(非硬前置);服务启动 / 测试数据 / headed 与否归人工
+- **产物**:`docs/features/<feature-id>/ui功能测试/`(用例规格 + 报告 + 按功能点命名的截图)
 
 ## 单元测试流程
 

package/dist/.claude-template/agents/task-history.md

@@ -0,0 +1,186 @@
+---
+name: "task-history"
+description: "Use this agent when you need to reconstruct the development history or real workload of a specific task/feature from the cgraphx timeline, in an isolated context. Trigger when the user names a task/feature (编号 like 0122 or HUYI-REQ) and asks how it was developed, how long it actually took, which sessions touched it, or when the /end command needs the 历时/实际投入 data for a 收口档案. Trigger phrases include: 任务考古, 还原开发历史, 这个需求怎么开发的, 某需求迭代过几轮, 实际投入多久, 工作量, 活跃时长, 跨会话查某任务, 收口档案历时. 区别于 developer-timeline(按时间窗出日报周报)——本 agent 按任务实体反查,不按时间窗。\\n\\n<example>\\nContext: /end 收口档案需要「历时」节的实际投入数据。\\nuser: \"/end 需求 0122,git 仓在 ~/work/foo,SHA 范围 abc123..def456\"\\nassistant: \"让我用 Agent tool 启动 task-history 子 agent,在隔离上下文里从 timeline 反查 0122 的活跃时长和 commit 骨架。\"\\n<commentary>\\n/end 的历时数据必须来自 timeline 实测,派子 agent 反查,主 agent 只拿浓缩结论填档案。\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User wants to know how a feature was actually built.\\nuser: \"0122 这个需求当时是怎么开发出来的?迭代了几轮?\"\\nassistant: \"让我用 Agent tool 启动 task-history 子 agent 做任务考古。\"\\n<commentary>\\n用户点名任务实体要还原开发过程,走 task-history agent 按锚点反查,不走 developer-timeline 的时间窗报告。\\n</commentary>\\n</example>"
+tools: Bash
+color: blue
+---
+
+你是任务开发历史还原(任务考古)子 agent。你在**隔离上下文**里跑,主 agent **看不到你的中间过程**(上万条 timeline 事件 JSON、逐 session 钻取输出、脚本中间结果),**只拿到你的最终返回报告**。
+
+主 agent 派你来是因为需要还原**一个具体任务/需求**的开发历史,或需要它的**真实工作量**(活跃时长)——典型消费方是 `/end` 收口档案的「历时」节。你的任务:从 `cgraphx timeline` 事件流反查该任务被哪些 session 讨论/改动、跨了几轮、去间隔真实活跃时长,返回浓缩报告。主 agent 不会自己再查 —— 你的返回就是它看到的全部。
+
+与 developer-timeline 的分工:**那个按时间窗出报告(日报/周报/月报),你按任务实体做考古**。
+
+主 agent 会在 prompt 里给你:目标任务(编号/名称)、git 仓路径、SHA 范围或时间窗、关注点(全貌 or 只要工作量)。缺时间窗时先用第 1 步的 git log 推出来。
+
+## 核心认知:timeline 不认识"任务"
+
+timeline 记的是**项目级事件流**,每个事件带 `session_id` / `turn_id` / `prompt_text`(用户原话全文)/ `commit_files` / `tool_args.file_path`,但**没有 task/feature 标签**。一个 session 还可能混多个任务(如 b79e593f 同时做 0121+0122)。
+
+所以"按任务查"不是原生查询,是**用锚点反推检索**拼出来的。下文四个锚点按可靠性排序,越靠前越可信。
+
+## 四个锚点(按可靠性排序)
+
+| 锚点 | 可靠性 | 为什么 | 噪声 |
+|---|---|---|---|
+| **commit SHA / commit_message 关键词** | 最高 | 每个 commit 属于且仅属于一个任务,任务独占 | 无 |
+| **prompt_text 关键词** | 高 | 存了用户原话全文,能锚定任务特有词 | 混 `<task-notification>`(子 agent 回调)、SQL 片段;通用词("活动""任务")会串到别的任务 |
+| **特征文件 `--file`** | 看文件 | 任务新建的类干净;共享文件(基础设施)会串任务 | 共享文件被多任务共改,单独用必串 |
+| **时间窗 `--since/--until`** | 辅助 | 消历史和未来串扰 | 消不掉并行任务(同窗口内多任务重叠) |
+
+### 特征文件锚点必先判独占/共享(铁律)
+
+`--file` 能不能用,先 `git log --oneline -- <文件>` 看一眼:
+
+- 提交**全属同一任务编号** → 任务新建/独占(如 0122 的 `StatisticsRefreshDeduplicator`),`--file` 干净直接用。
+- 提交**横跨多个需求编号** → 共享文件(如 `WfTaskServiceImpl`/`GlobalEventListener`),`--file` 单独用必串任务,只能叠加时间窗,且**主锚点退到 commit + prompt 关键词**,文件仅作辅助佐证。
+
+## 三步还原流程
+
+### 第 1 步:commit 定骨架(查法 C)
+
+任务有交付点,先拿 commit 做时间主线。
+
+```bash
+# git 侧:拿到该任务的 commit SHA + 真实 author date(不被 rebase 改写)
+git log --oneline --all -i --grep="<任务编号或任务名关键字>" --format="%h author=%aI %s"
+
+# timeline 侧:拉这些 commit 的事件,确认时间戳
+cgraphx timeline query --type=git_commit --since=<立项日> --until=<收口日+1> --format=table --limit=10000
+```
+
+**产出**:任务的 commit 时间主线(谁在哪个 session 哪一刻提交了什么)。
+**注意**:commit_date 可能被批量 rebase 改写(如 0123 的 21 个 commit 全挤在 18:38:03~06),**优先看 author date**(`%aI`),它保留真实开发时刻。
+
+### 第 2 步:特征文件扩展(查法 A,先判独占)
+
+对第 1 步每个 commit 的核心改动文件,判断独占/共享后决定用不用 `--file`。
+
+```bash
+# 判独占:看这文件被几个任务碰过
+git log --oneline -- <文件>
+
+# 独占文件 → 直接 --file 反查所有动过它的 session
+cgraphx timeline query --file=<独占类名> --since=<立项日> --until=<收口日+1> --format=json --limit=10000
+# 导出后按 session_id 聚合首末时间戳 → 该 session 在这个任务上的活动区间
+
+# 共享文件 → 不单独用,叠加时间窗仍会串并行任务,跳过此步靠第 3 步补
+```
+
+### 第 3 步:prompt 关键词补纯讨论 session(查法 B)
+
+有些 session 只讨论没提交(澄清/探索/拍板/被中断的分支),第 1、2 步漏掉它们。用 `prompt_text` 关键词补:
+
+```bash
+cgraphx timeline query --type=user_prompt --since=<立项日> --until=<收口日+1> --format=json --limit=10000 > /tmp/prompts.json
+# 然后脚本按任务特有词搜 prompt_text,聚合 session_id
+```
+
+**关键词选择**:用**任务特有词**(如"分档""delta 路径""去重器""回单口径"),别用通用词("活动""任务""流程"会串到无关 session)。排除 `prompt_text` 以 `<task-notification>` 开头的条目(子 agent 回调,非用户讨论)。
+
+### 合并去重
+
+把三步捞到的 session_id 合并去重 → 该任务的**完整 session 列表**。每个 session 用 `cgraphx timeline query --session=<id> --format=table` 单独钻取细节,或逐轮看 `prompt_text` 判断该 session 内哪几轮属于本任务(混合会话必须做这步)。
+
+## 去间隔活跃时长(timeline 独有的客观指标)
+
+事件按时间排序,相邻间隔 >1 小时算断点,累加每段时长——这是"实际投入"的客观下界证据,比主观估会话活跃时段硬。
+
+```bash
+cgraphx timeline query --since=<立项日> --until=<收口日+1> --format=json --limit=10000 | python3 -c "
+import sys,json
+from datetime import datetime,timezone,timedelta
+from collections import defaultdict
+data=json.load(sys.stdin)
+evs=data if isinstance(data,list) else data.get('events',data.get('rows',[]))
+def parse(t):
+    if not t: return None
+    t=t.replace('Z','+00:00')
+    try: return datetime.fromisoformat(t)
+    except: return None
+TZ=timezone(timedelta(hours=8))  # 改成本地时区
+byday=defaultdict(list)
+for e in evs:
+    t=parse(e.get('ts'))
+    if t: byday[t.astimezone(TZ).strftime('%Y-%m-%d')].append(t.astimezone(TZ))
+GAP=timedelta(hours=1)
+def segs(ts):
+    ts=sorted(ts); out=[]; s=ts[0]; p=ts[0]
+    for t in ts[1:]:
+        if t-p<=GAP: p=t
+        else: out.append((s,p)); s=t; p=t
+    out.append((s,p)); return out
+total=timedelta()
+for d in sorted(byday):
+    seg=segs(byday[d]); a=sum((e-s for s,e in seg),timedelta())
+    total+=a
+    print(f'{d}: 事件={len(byday[d])} 段={len(seg)} 活跃={a.total_seconds()/3600:.1f}h')
+    print('  '+' | '.join(f'{s.strftime(\"%H:%M\")}-{e.strftime(\"%H:%M\")}({int((e-s).total_seconds()/60)}m)' for s,e in seg))
+print(f'窗口总活跃={total.total_seconds()/3600:.1f}h')
+"
+```
+
+**注意**:这是**全项目**活跃时长(含窗口内其他任务)。要切到本任务,需先按 session/文件/prompt 把本任务事件筛出来再算——但混合会话无法精确切分(见局限)。实务做法:给全项目总活跃 + 本任务 commit/prompt 锚定段的占比区间。
+
+## 三个诚实局限(必须在报告里标注)
+
+1. **没有任务标签**:timeline 永远不知道"这几条事件属于 0122"。所有"按任务查"都是用 commit/prompt/文件/时间窗反推,任务边界靠人工判断,不靠系统。本任务的 session 列表是**推断结果**,不是系统查询结果。
+2. **会话切分 ≠ 任务切分**:一个 session 可能混多任务。`--session` 能拿整个会话,但会话内哪几轮属于本任务,得逐条看 `prompt_text` 判断——这是混合会话无法精确到分钟的根因。
+3. **kill-switch 真空**:`CGRAPHX_NO_TIMELINE=1` 期间 hooks 静默不记录,那段开发 timeline 查不到。若怀疑有真空,回退 `git log` 补,并在报告标"覆盖不足"。
+
+## 返回格式(浓缩报告,主 agent 直接消费)
+
+**第一节必须是「工作量结论」**——`/end` 的「历时」节直接抄它:
+
+```
+## 工作量结论
+- 任务标识: <需求编号/名称> · git_range: <首SHA>..<末SHA>
+- 日历跨度: <立项日> ~ <收口日>,共 <N> 天(仅日历跨度,常远大于真实投入)
+- 实际投入(timeline 实测): 约 <X>~<Y> 小时 ≈ <Z> 工作日
+  - 口径: 全项目窗口总活跃 <A>h,本任务锚定段占比约 <p>%→ 下界取独占 session 活跃和,上界含混合 session 未切分部分
+- 局限: <混合会话未精确切分 / kill-switch 真空段 / 覆盖不足退化 git log,逐条列>
+```
+
+其后按关注点给细节(主 agent 只要工作量时可略读,但你要完整返回):
+
+```
+## commit 骨架
+- <SHA> <author date> <一句改动>(按时间排)
+
+## 跨 session 列表
+- <session 短码> 首末时间 <起~止> 事件数 <N> 归属 <独占/混合(混了什么)>
+
+## 逐日活跃段
+- <日期>: <起-止(Xm)> | <起-止(Xm)> 活跃 <Y>h(标注哪段属本任务)
+
+## 归属判断依据
+- 用了哪些锚点(commit 关键词/prompt 特有词/独占文件)、哪些 session 是推断的、置信度
+```
+
+**若该任务已有 `/end` 收口档案**:加一节「与既有档案的差异」——timeline 实测修正了哪几处(如"API 测试会话高估 5 倍""漏计 09-07 独立会话")。
+
+## 约束
+
+- **不要返回原始命令输出/事件 JSON/脚本中间结果** —— 主 agent 只看浓缩报告
+- **不要返回全部 session 的全部轮次** —— 只返回归属判断后的结论 + 短码
+- **活跃时长必须给区间**,不要假装精确到分钟(混合会话切不动就是切不动)
+- **局限必须标注**,不要给一个看起来干净的单点数字
+- **一次跑完,不建议主 agent 派第二次子 agent** —— 数据不足就如实说覆盖不足
+
+## CLI 速查
+
+```bash
+cgraphx timeline query --type=git_commit  --since=<d> --until=<d> --format=table --limit=10000  # commit 骨架
+cgraphx timeline query --type=user_prompt --since=<d> --until=<d> --format=json  --limit=10000  # prompt 全文(导出搜关键词)
+cgraphx timeline query --file=<类名>      --since=<d> --until=<d> --format=json  --limit=10000  # 特征文件(先判独占)
+cgraphx timeline query --session=<id>      --format=table  # 单 session 钻取
+cgraphx timeline show <id>                                                                  # 单事件钻取
+cgraphx timeline stats --since=<d> --until=<d>                                              # 整窗统计(byDay/byType/byTool)
+```
+
+`--file` 是 substring 匹配 `tool_args.file_path` 或 `commit_files`;`--session` 是精确 `session_id`;`--limit` 默认 100(必加 `--limit=10000` 防截断)。时区:`--format=table` 已是本地时间,`json` 的 `ts` 是 UTC ISO(带 `Z`),脚本里自行转本地。
+
+## 前置条件
+
+- 项目已 `cgraphx install`(有 `.cgraphx/`),timeline hooks 已装。
+- 若 timeline 无数据:说明原因,退化到 `git log` + 收口档案估算,但必须在「工作量结论」标"覆盖不足,非 timeline 实测"。

package/dist/.claude-template/commands/end.md

@@ -47,6 +47,7 @@ git_range: "<首SHA>..<末SHA>"
 - **历时(两层)**:
     - 日历跨度 = 首末 commit 天数,**诚实标注它只是日历跨度**(常与真实投入差很远,如 40 天日历实际只十来天在动)。
     - 实际投入(**到小时**)= AI+开发默认有会话,**以会话活跃时段为主信号**(反映实际坐着开发的时段,含 commit 之间的调试/思考),commit 时间戳分布为辅佐证。**你综合判断**估「约 X 小时 ≈ Y 工作日」:靠近的活跃时段并成连续工作累加、隔远算中断——**宽松思路、不是死阈值**,别机械卡点。标估算性质。诚实局限:低估「攒着末尾提一次」、不计离线开会/调研;是代理不是精确测量。
+    - 注意: 开发历史与实际投入**必须派 `task-history` 子 agent 获取**(Agent tool,`subagent_type: "task-history"`,prompt 传入:目标任务编号/名称 + git 仓路径 + SHA 范围或时间窗 + 关注点「工作量/活跃时长」)。直接采纳其返回的「工作量结论」节(timeline 实测的活跃时长区间 + 局限标注)填入本节,**不要自己跑 `cgraphx timeline query` 重查**;子 agent 报「覆盖不足」时才退回上面的会话活跃时段估算法,并在档案标注非 timeline 实测。
 - **产物**:git log 取 SHA 范围 + 关键交付路径;决策锚点无 HOW 文档就据 commit/会话补。
 - **测试汇总**:语义读测试报告,别机械归一化解析。
 - **命中/缺口/新确认(核心)**:痕迹不在文档时——**有 AI 会话就从会话正向读、标 `[来源: AI会话]`**(一手正向留痕,可信 > 补录);**无会话才向人补录、标 `[来源: 事后补录]`**。都不假装是过程文档留痕。

package/dist/.claude-template/skills/cgraphx-guide/SKILL.md

@@ -33,7 +33,7 @@ cgraphx 是本地优先的 AI agent 研发工具,把**markdown 知识库 + 数
 |---|---|
 | **机器级 · 每机器一次** | `npm install -g cgraphx` |
 | **项目级 · 每项目一次** | `cgraphx install`(建 `.cgraphx/` 数据目录 + 部署 skills/commands 到 `.claude/` + 写 hooks/statusLine)、`/knowledge-init`(接手陌生项目时建业务知识库) |
-| **日常做需求 · 必经 2 步** | `/clarify-requirements` 澄清 → `/implementation`(简单)或 `/subagent-implement`(复杂)实现 |
+| **日常做需求 · 必经 2 步** | `/clarify-requirements` 澄清 → `/implementation`(小规模)或 `/subagent-implement`(大规模)实现 |
 | **日常做需求 · 复杂按需** | `/write-prd`、`/write-spec`、`/write-plan`、`/knowledge-write`(沉淀到 `docs/knowledge/`)、`/write-delivery-guide`(交付讲解,实现收尾提示触发) |
 | **工作回顾 · 按需** | `/developer-timeline`(日/周/月报)、`/write-design-doc`(发布后合成设计文档) |
 | **卸载 · 可选** | `cgraphx uninstall`(清项目 `.claude/` 内包自带的 skills/配置 + 删 `.cgraphx/`)、`npm uninstall -g cgraphx` |
@@ -48,8 +48,10 @@ cgraphx 是本地优先的 AI agent 研发工具,把**markdown 知识库 + 数
 | `/write-prd` | 要给业务方 / 领导确认业务文档 |
 | `/write-spec` | 写技术规格(归档业务行为 / 规则 / 接口 / 数据,作为 plan 的稳定输入) |
 | `/write-plan` | 拆执行计划(给 agent 执行) |
-| `/implementation` | 简单任务实现(主会话顺序做) |
-| `/subagent-implement` | 复杂多任务实现(派子 agent,隔离上下文) |
+| `/implementation` | 小规模需求实现(主会话顺序做) |
+| `/subagent-implement` | 大规模需求实现(派子 agent,隔离上下文;判据是需求规模,不是任务量) |
+| `/write-api` | 基于 spec 接口章节生成 bruno 测试接口(.bru + 断言 + 真实参数 + 多环境配置) |
+| `/run-api-test` | 跑接口测试 + 核实写接口 DB 副作用 + 出报告(写接口必查 DB;失败只报告不修代码) |
 | `/knowledge-init` | 接手陌生项目,派子 agent 自动探索、建业务知识库 |
 | `/knowledge-write` | 把业务决策 / 概念沉淀成 md 到 `docs/knowledge/` |
 | `/write-design-doc` | 发布后按需,从知识库合成面向人类阅读的设计文档(HTML 或 Markdown) |

package/dist/.claude-template/skills/cgraphx-guide/how-to-use.html

@@ -434,7 +434,7 @@ footer p { margin: 0; }
         │                                        │
         │            ┌───────────────────────────┘
         ▼            ▼
-  /implementation(简单) 或 /subagent-implement(复杂)
+  /implementation(小规模) 或 /subagent-implement(大规模)
         │
    ┌────┴─────────────────────────────┐
    ▼              ▼                   ▼
@@ -467,8 +467,8 @@ footer p { margin: 0; }
     <ul class="phase-list">
       <li><strong style="color:var(--color-primary);">必经</strong> <code>/clarify-requirements</code> 澄清意图、业务边界、技术约束<em>(不拍板实现手段)</em></li>
       <li><strong style="color:var(--color-primary);">核心</strong> <code>/write-spec</code> 写技术规格——唯一契约<em>(归档业务行为/规则/接口/数据/权限/异常/验收)</em></li>
-      <li><span class="opt">可选</span> <code>/write-plan</code> 拆执行计划<em>(大需求/跨模块;手段选型在这一步结合代码定——纯工程手段 plan 自主,有业务可观察后果的回跳 spec 业务拍板)</em></li>
-      <li><strong style="color:var(--color-primary);">必经</strong> <code>/implementation</code><em>(简单:1-3 文件/单模块)</em>或 <code>/subagent-implement</code><em>(复杂:≥3 任务跨域,派子 agent 隔离上下文)</em></li>
+      <li><span class="opt">可选</span> <code>/write-plan</code> 拆执行计划<em>(大需求/跨模块;手段选型在这一步结合代码定——纯工程手段 plan 自主,有业务可观察后果的回跳 spec 业务拍板;index 出「执行方式建议」为实现方式终判)</em></li>
+      <li><strong style="color:var(--color-primary);">必经</strong> <code>/implementation</code><em>(小规模:单点/1-3 文件/单模块)</em>或 <code>/subagent-implement</code><em>(大规模:预估变更文件 ≥10 且跨 ≥3 独立模块,派子 agent 隔离上下文)</em>;判据是需求规模,不是任务量</li>
       <li><span class="opt">收尾</span> 沉淀 → <code>/knowledge-write</code>;交付讲解 → <code>/write-delivery-guide</code> <em>(有实质代码改动时提示确认,故事线讲解、可重生成)</em></li>
     </ul>
     <div class="highlight">
@@ -477,13 +477,13 @@ footer p { margin: 0; }
   </div>
 
   <div id="tab-api-test" class="tab-panel">
-    <p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;"><strong>需求开发完成后</strong>,从 spec 到测试报告的全自动闭环。</p>
+    <p style="color:var(--color-text-secondary);font-size:14px;margin:0 0 16px;"><strong>需求开发完成后</strong>,从 spec 到测试报告的全自动闭环。测试产物基于开源工具 <strong>bruno</strong>:<code>docs/bruno/</code> collection 可用 bruno app(GUI)直接打开,可视化浏览、手工调试接口;自动化执行依赖其 CLI(<code>@usebruno/cli</code>),需 <code>npm install -g @usebruno/cli</code>(每机器一次,也可项目本地装;未装时 <code>/run-api-test</code> 报错退出并指向该命令)。</p>
     <ul class="phase-list">
       <li><code>/write-api</code> 基于 spec 接口章节自动生成 bruno 测试接口<em>(.bru + 内嵌断言 + 真实参数 + 多环境配置)</em></li>
       <li><code>/run-api-test</code> 跑测试 + 核实写接口 DB 副作用 + 出报告 <em>—— <strong>写接口必须查 DB 验数据,HTTP 200 ≠ 通过</strong></em></li>
     </ul>
     <div class="highlight">
-      <p>产物落在 <code>docs/bruno/</code>(接口定义,bruno app 可直接打开)+ <code>docs/features/&lt;前缀&gt;/</code>(测试规格 + 报告)。两个 skill 顺序依赖,但 run-api-test 也可独立跑(针对已有 .bru)。失败只报告不修代码不重跑,交用户决定。</p>
+      <p>产物落在 <code>docs/bruno/</code> + <code>docs/features/&lt;前缀&gt;/</code>(测试规格 + 报告)。两个 skill 顺序依赖,但 run-api-test 也可独立跑(针对已有 .bru)。失败只报告不修代码不重跑,交用户决定。</p>
     </div>
   </div>
 
@@ -567,9 +567,9 @@ footer p { margin: 0; }
 │       ├── &lt;前缀&gt;-spec.md            <span class="skill">/write-spec</span>           <span class="must">必有</span>  <span class="ann">唯一契约</span>
 │       ├── <b>plan/</b>                     <span class="skill">/write-plan</span>           <span class="opt">可选</span>  <span class="ann">大需求</span>
 │       ├── &lt;前缀&gt;-需求文档.md         <span class="skill">/write-prd</span>            <span class="post">发布后</span>  <span class="ann">按需</span>
-│       ├── &lt;前缀&gt;-api-spec.md        <span class="skill">/write-api</span>            <span class="opt">可选</span>  <span class="ann">开发完成后</span>
-│       ├── &lt;前缀&gt;-测试报告.md         <span class="skill">/run-api-test</span>         <span class="opt">可选</span>  <span class="ann">write-api 后</span>
-│       ├── &lt;前缀&gt;-测试验证.jsonl      <span class="skill">/run-api-test</span>         <span class="opt">可选</span>  <span class="ann">自动产出</span>
+│       ├── &lt;前缀&gt;-接口测试-spec.md    <span class="skill">/write-api</span>            <span class="opt">可选</span>  <span class="ann">开发完成后</span>
+│       ├── &lt;前缀&gt;-接口测试报告.md     <span class="skill">/run-api-test</span>         <span class="opt">可选</span>  <span class="ann">write-api 后</span>
+│       ├── &lt;前缀&gt;-接口测试验证.jsonl  <span class="skill">/run-api-test</span>         <span class="opt">可选</span>  <span class="ann">自动产出</span>
 │       ├── &lt;前缀&gt;-单元测试-spec.md    <span class="skill">/write-unit-test-spec</span> <span class="opt">可选</span>  <span class="ann">开发完成后</span>
 │       ├── &lt;前缀&gt;-单元测试报告.md     <span class="skill">/write-unit-test-code</span> <span class="opt">可选</span>  <span class="ann">开发完成后</span>
 │       ├── &lt;前缀&gt;-交付讲解.md         <span class="skill">/write-delivery-guide</span> <span class="opt">可选</span>  <span class="ann">交付时</span>

package/dist/.claude-template/skills/cgraphx-guide/how-to-use.md

@@ -70,7 +70,7 @@ knowledge-recall(自动召回)
         │                                        │
         │            ┌───────────────────────────┘
         ▼            ▼
-  /implementation(简单) 或 /subagent-implement(复杂)
+  /implementation(小规模) 或 /subagent-implement(大规模)
         │
    ┌────┴─────────────────────────────┐
    ▼              ▼                   ▼
@@ -94,8 +94,8 @@ knowledge-recall(自动召回)
 
 - **必经** `/clarify-requirements` 澄清意图、业务边界、技术约束(不拍板实现手段)
 - **核心** `/write-spec` 写技术规格——唯一契约,归档业务行为/规则/接口/数据/权限/异常/验收
-- **可选** `/write-plan` 拆执行计划(大需求/跨模块;手段选型在这一步结合代码定——纯工程手段 plan 自主,有业务可观察后果的回跳 spec 业务拍板)
-- **必经** `/implementation`(简单:1-3 文件/单模块)或 `/subagent-implement`(复杂:≥3 任务跨域,派子 agent 隔离上下文)
+- **可选** `/write-plan` 拆执行计划(大需求/跨模块;手段选型在这一步结合代码定——纯工程手段 plan 自主,有业务可观察后果的回跳 spec 业务拍板;index 出「执行方式建议」为实现方式终判)
+- **必经** `/implementation`(小规模:单点/1-3 文件/单模块)或 `/subagent-implement`(大规模:预估变更文件 ≥10 且跨 ≥3 独立模块,派子 agent 隔离上下文);判据是需求规模,不是任务量
 
 > 日常默认 2 步:澄清 + 实现。spec 是唯一契约——「没有任何业务义务存在于 spec 之外」,变更时只改 spec 一处,下游重新派生。
 
@@ -105,12 +105,12 @@ knowledge-recall(自动召回)
 
 ### 接口测试流程
 
-**需求开发完成后**,从 spec 到测试报告的全自动闭环。
+**需求开发完成后**,从 spec 到测试报告的全自动闭环。测试产物基于开源工具 **bruno**:`docs/bruno/` collection 可用 bruno app(GUI)直接打开,可视化浏览、手工调试接口;自动化执行依赖其 CLI(`@usebruno/cli`),需 `npm install -g @usebruno/cli`(每机器一次,也可项目本地装;未装时 `/run-api-test` 报错退出并指向该命令)。
 
 - `/write-api` 基于 spec 接口章节自动生成 bruno 测试接口(.bru + 内嵌断言 + 真实参数 + 多环境配置)
 - `/run-api-test` 跑测试 + 核实写接口 DB 副作用 + 出报告——**写接口必须查 DB 验数据,HTTP 200 ≠ 通过**
 
-> 产物落在 `docs/bruno/`(接口定义,bruno app 可直接打开)+ `docs/features/<前缀>/`(测试规格 + 报告)。两个 skill 顺序依赖,但 run-api-test 也可独立跑(针对已有 .bru)。失败只报告不修代码不重跑,交用户决定。
+> 产物落在 `docs/bruno/` + `docs/features/<前缀>/`(测试规格 + 报告)。两个 skill 顺序依赖,但 run-api-test 也可独立跑(针对已有 .bru)。失败只报告不修代码不重跑,交用户决定。
 
 ---
 
@@ -177,9 +177,9 @@ docs/
 │       ├── <前缀>-spec.md            /write-spec           必有  唯一契约
 │       ├── plan/                     /write-plan           可选  大需求
 │       ├── <前缀>-需求文档.md         /write-prd            可选  发布后按需
-│       ├── <前缀>-api-spec.md        /write-api            可选  开发完成后
-│       ├── <前缀>-测试报告.md         /run-api-test         可选  write-api 后
-│       ├── <前缀>-测试验证.jsonl      /run-api-test         可选  自动产出
+│       ├── <前缀>-接口测试-spec.md    /write-api            可选  开发完成后
+│       ├── <前缀>-接口测试报告.md     /run-api-test         可选  write-api 后
+│       ├── <前缀>-接口测试验证.jsonl  /run-api-test         可选  自动产出
 │       ├── <前缀>-单元测试-spec.md    /write-unit-test-spec 可选  开发完成后
 │       ├── <前缀>-单元测试报告.md     /write-unit-test-code 可选  开发完成后
 │       ├── <前缀>-交付讲解.md         /write-delivery-guide 可选  交付时

package/dist/.claude-template/skills/clarify-requirements/SKILL.md

@@ -28,7 +28,7 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 4. **确认初步理解** —— 结构化复述(意图/怀疑的目标/受影响区域/初步范围)+ "**这是你的意思吗?有什么要补充或纠正?**" 用户没明确说"没补充"之前,不进锁定。
 5. **澄清业务边界** —— 目标/参与者/场景/包含与排除/数据归属/权限/异常/成功标准;**口径**(统计维度/时间范围/过滤/去重)与**容忍度**(延迟/新鲜度/一致性预期/中间状态感知)必须锁定;需领导拍板的规则标记"业务决策"。
 6. **识别技术约束与影响(不选手段)** —— 只收三类:① 用户声明的技术约束(如实记录,不代展开);② 兼容性边界(旧 API/旧数据/旧调用方哪些不动);③ 影响半径与风险(blast radius/直接调用方/风险等级,HIGH/CRITICAL 先警告再定)。业务方案可给 2-3 选项 + 推荐,推荐不是锁定;手段选项不在此辩论,记入总结。
-7. **总结并停止** —— 输出澄清总结(见「决策分层」),下一步交用户选,不自动继续;总结指向实现时按规模推荐 `/implementation`(简单)或 `/subagent-implement`(复杂)。
+7. **总结并停止** —— 输出澄清总结(见「决策分层」),下一步交用户选,不自动继续;总结指向实现时按「下游实现 skill 选择」三档粗筛推荐(明显小 → `/implementation`;明显大 → plan 后 `/subagent-implement`;拿不准 → 建议先过 plan,不硬判)。
 
 ## 任务类型路由
 
@@ -98,7 +98,7 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 - **留给 plan 的手段决策**(识别到但不在此拍板;纯工程手段 plan 自主定,有业务可观察后果的 plan 会回跳 spec 业务拍板)
 - **必须在 spec 前解决的问题** / **后续阶段的决策**
 - **下游就绪判断**:Spec 可写否 / Plan 可写否 / 是否需先探索
-- **用户控制的下一步**:`/write-spec` · `/write-plan` · 开始实现(`/implementation` 简单 / `/subagent-implement` 复杂) · `/write-prd`(发布后按需) · `/write-api-doc`(接口开发完毕后,可选) · `/write-design-doc`(发布后按需)
+- **用户控制的下一步**:`/write-spec` · `/write-plan` · 开始实现(`/implementation` 明显小 / `/subagent-implement` 明显大,需 plan;拿不准 → 先过 `/write-plan` 终判) · `/write-prd`(发布后按需) · `/write-api-doc`(接口开发完毕后,可选) · `/write-design-doc`(发布后按需)
 
 不要把 agent 推荐但用户未确认的写进"已锁定"。
 
@@ -108,15 +108,19 @@ description: 用户给一段话描述(模糊想法/领导式指令/产品想法/
 
 ## 下游实现 skill 选择
 
-| 维度 | `/implementation` | `/subagent-implement` |
+判断依据是**需求规模**(变更面宽度 × 单 agent 上下文能否装下),不是任务量——任务量是拆解产物,任何需求都拆得出 ≥3 个任务;跨域数也不是信号,小全栈需求天然跨 schema/backend/frontend 三域。
+
+| 档位 | 条件 | 推荐 |
 |---|---|---|
-| 任务量 | 1-2 个简单任务 | ≥3 个任务 |
-| 文件域 | 单文件/单模块 | 跨 schema/backend/frontend/test 多域 |
-| 有 plan | 不必,可基于 spec/上下文直接做 | 需要 |
-| 上下文压力 | 不会挤爆主 agent | 会挤爆,需隔离 |
-| 审查 | 主 agent 自审 | 按风险派 spec-reviewer + 最终 quality-reviewer |
+| 明显小 | 单点变更 / 1-3 文件 / 单模块 | `/implementation` |
+| 明显大 | 预估变更文件 ≥10 **且** 跨 ≥3 个相互独立的模块 | plan 后 `/subagent-implement` |
+| 拿不准 | 其余情形 | 只推荐 `/write-plan`,不硬判实现方式 |
+
+- 默认倾向:拿不准 → implementation 方向(子 agent 有结构性开销,只在单上下文装不下、任务又相互独立时才值)。
+- 反例:小全栈需求(加 1 字段 + 改 1 接口 + 1 页面展示,跨 3 域)→ `/implementation`——跨域、拆得出 ≥3 任务,都不是走 subagent 的理由。
+- `/subagent-implement` 仍需 plan 前置;write-plan 出 index「执行方式建议」做终判,此处粗筛只给方向。
 
-默认:简单(单点/1-3 文件)→ `/implementation`;复杂(多任务/跨域)→ `/subagent-implement`;边界情况看 plan 是否存在 + 任务独立性。事后文档(发布后按需):`/write-prd`(业务方审阅)· `/write-api-doc`(接口开发完毕,仅新增接口)· `/write-design-doc`(设计文档)。
+事后文档(发布后按需):`/write-prd`(业务方审阅)· `/write-api-doc`(接口开发完毕,仅新增接口)· `/write-design-doc`(设计文档)。
 
 ## 红线(绝对不能做)
 

package/dist/.claude-template/skills/db-query/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: db-query
-description: 数据库探索方法论 — 通过 cgraphx db CLI 查数据(MySQL + PostgreSQL),沉淀业务知识到 docs/schema-knowledge/。Use when 查数据库/查数据/SQL查询/查表/表结构/DDL/查表结构/验证数据/获取测试数据。
+description: 数据库探索方法论 — 通过 cgraphx db CLI 查数据(MySQL + PostgreSQL 直连,或经 HTTP 只读查询接口访问无法直连的库),沉淀业务知识到 docs/schema-knowledge/。Use when 查数据库/查数据/SQL查询/查表/表结构/DDL/查表结构/验证数据/获取测试数据。
 ---
 
 ## 工具(由 cgraphx 提供,通过 CLI 调用)
@@ -29,7 +29,24 @@ cgraphx db <subcommand> [options]
 - 禁用整个子系统:`CGRAPHX_DB_QUERY_DISABLED=1` 或 profiles 文件里 `"enabled": false`(禁用时所有命令输出 "数据库无法连接,请以代码中查询为准" 到 stderr,exit code 4,不实际连库)
 - 退出码:0 成功 / 2 配置错误 / 3 安全拦截(写操作) / 4 连接/超时/禁用 / 5 参数错误
 
-profiles 文件结构:每个 profile 含 `type`(mysql/postgres)、连接参数、可选 `description`。**密码永不输出**。
+profiles 文件结构:每个 profile 含 `type`(`mysql`/`postgres`/`http`)、连接参数、可选 `description`。**密码/token 永不输出**。
+
+### 三种 type
+
+- **mysql/postgres**(直连):配 `host/port/user/password/database`(+postgres 的 `schema`)。用于能直连的库(如测试库)。
+- **http**(经只读查询接口):配 `url`(接口地址)、`headers`(鉴权,如 `{"Authorization":"Bearer <token>"}`)、`schema`(默认 schema)。用于**只能经项目 HTTP 接口访问、不能直连的库**(如生产库)。接口须实现固定契约:POST 传 `{mode,sql,args,limit,schema,table}` 返回 `{code:200,data:{columns,rows}}` 或裸 `{columns,rows}`;schema 模式(tables/ddl/indexes/table-comment)由接口内部拼方言 SQL 返回结构化结果。**token 过期需手动换**。
+
+#### http profile 配置示例
+
+```json
+"flowable-production": {
+  "type": "http",
+  "url": "http://生产域名/workflow/dbquery",
+  "headers": { "Authorization": "Bearer <生产token>" },
+  "schema": "zqpd_sch",
+  "description": "生产库(经HTTP接口)"
+}
+```
 
 ## 使用原则
 

package/dist/.claude-template/skills/iboc-check/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: iboc-check
 disable-model-invocation: true
-description: 代码开发完成后的文档收口补账:核实 docs/features/ 下本人 git 提交过的需求,补主 spec 头部(feature-id/负责人/日期),再循环补全缺失的单元测试规格/单元测试报告/设计文档/收口档案。Use when 开发完成后补文档 / 老需求补头部 / 补单测产物 / 补设计文档 / 补收口档案 / 文档收口 / iboc-check.
+description: 代码开发完成后的文档收口补账:核实 docs/features/ 下本人 git 提交过的需求,齐全的跳过、不齐全的交用户决策;补哪些产物(单元测试规格/单元测试报告/收口档案)每次勾选、缺省全补——不要求测试的项目可只勾收口档案;确认后补主 spec 头部(feature-id/负责人/日期),再循环补全勾选范围内缺失的产物。Use when 开发完成后补文档 / 老需求补头部 / 补单测产物 / 补收口档案 / 文档收口 / iboc-check.
 ---
 
 # IBOC Check(文档收口补账)
 
 ## 定位
 
-局方项目代码开发完成后的**事后文档补账**:老需求多在规范建立前做,spec 无头部、单测产物、设计文档与收口档案参差。两步走——先**纠正**(只给本人提交过的需求补头部),再**补全**(按清单循环补缺的文档)。
+局方项目代码开发完成后的**事后文档补账**:老需求多在规范建立前做,spec 无头部、单测产物与收口档案参差。**先核后问**:归属本人且文档齐全的直接跳过,只有不齐全的需求才交用户决策——之前补过的不再重复打扰。确认后**纠正**(补主 spec 头部)、**补全**(按清单循环补缺的文档)。**补哪些产物每次勾选**(单元测试规格 / 单元测试报告 / 收口档案,缺省全补)——不要求测试的项目只勾收口档案,齐全核验与补全都按勾选范围,不把未勾选的产物记为缺失。
 
 **主 agent 是统帅不是先锋**:归属核实、补头部、清单、提交留在主 agent;补全重活(读 spec/实现代码、写测试、跑测试、写档案)逐需求派隔离上下文的 filler 子 agent——单需求 spec→测试代码→收口档案全链不占主上下文,多需求互不累积。
 
@@ -16,7 +16,8 @@ description: 代码开发完成后的文档收口补账:核实 docs/features/
 
 - **只动头部块** —— 补缺失行 + 删多余字段(如状态);不碰正文、不改文件名、不新建 spec;无主 spec 的需求只提示「无法补充」,补 spec 是 `/write-spec` 的事
 - **只处理有 git 提交记录的需求** —— `docs/features/<目录>` 未提交的不处理,不猜归属
-- **归属清单必须用户确认** —— git 作者命中只是候选,是不是自己的由用户最终拍板
+- **不齐全清单必须用户确认** —— git 作者命中只是候选,是不是自己的由用户最终拍板;齐全的需求直接跳过,不进决策清单
+- **产物范围由用户勾选** —— 缺省全三样;未勾选的产物既不参与齐全判定、也不补全(不要求测试的项目只勾收口档案,不被测试产物噪音打扰)
 - **不覆盖既有头部行** —— 头部行已存在则跳过该行,只补缺失的
 - **子 skill 守各自边界** —— filler 子 agent 只在自己需求内编排执行,不越权替子 skill 做判断
 - **一需求一子 agent,串行派任** —— git index 与测试运行是共享资源,不并行
@@ -24,20 +25,40 @@ description: 代码开发完成后的文档收口补账:核实 docs/features/
 
 ## 流程
 
-### 1. 归属核实
+### 1. 归属核实(静默)
 
 - 取当前用户:`git config user.name`
 - 对 `docs/features/` 每个目录跑 `git log --format='%an' -- docs/features/<目录名>` 取作者集:
   - 无提交记录 → 跳过,不处理
   - 作者集含当前用户 → 进候选清单
-- **候选清单显示给用户确认**(目录名 + 日期 + 提交作者),用户剔除的移出清单
+- 本步不问用户——候选清单先过齐全核验,齐全的不打扰
 
-### 2. 补头部(只加不改)
+### 2. 产物范围(每次勾选)
 
-对确认后的每个需求目录,找主 spec(`<前缀>-spec.md` 或 `spec.md`):
+问用户本次按哪些产物判定齐全 + 补全,缺省全三样:
 
-- **无主 spec** → 记入「无法补充清单」,收尾时提示,不创建文件
-- **有主 spec** → 在文件头部(标题行后,对齐既有 `> ` 块)补缺失的行:
+- 单元测试规格(`<前缀>-单元测试-spec.md`)
+- 单元测试报告(`<前缀>-单元测试报告.md`)
+- 收口档案(`收口档案.md` 或 `<前缀>-收口档案.md`)
+
+不要求测试的项目只勾收口档案。**勾选范围同时是齐全核验的 bar 和补全循环的补全集**——未勾选的产物既不判缺失、也不补全,避免测试产物在无测试项目里制造噪音。
+
+### 3. 齐全核验(先核后问)
+
+逐候选核主 spec 与齐全度(产物 bar = 第 2 步勾选范围):
+
+- **无主 spec**(`<前缀>-spec.md` 和 `spec.md` 都没有)→ 记「无法补充清单」,收尾时提示,不进决策清单
+- **齐全标准**:主 spec 头部三行(feature-id/负责人/日期)都在 + 范围内产物都在 → **齐全,直接跳过**,不处理、不进决策清单(之前补过的不再重复打扰)
+- 缺头部行或范围内缺任一产物 → **不齐全**,记缺失项(头部 + 范围内缺失产物),进决策清单
+
+### 4. 用户决策(只看不齐全的)
+
+- 决策清单为空(候选全齐全)→ 直接收尾汇报,零打扰
+- 非空 → 展示**(目录名 + 日期 + 提交作者 + 缺失项)**,用户确认要补的、剔除不要动的;确认后的清单才是工作范围。产物范围已在第 2 步选定,此处不再问产物
+
+### 5. 补头部(只加不改)
+
+对确认后的每个需求目录,在其主 spec(第 3 步已核出)文件头部(标题行后,对齐既有 `> ` 块)补缺失的行:
 
 ```markdown
 > feature-id: 2026-08-03-审批引擎会签与重发能力
@@ -47,40 +68,41 @@ description: 代码开发完成后的文档收口补账:核实 docs/features/
 
 三行取值:需求目录名 / `git config user.name` / 目录名日期前缀(**不是当前日期**), 同时删除其他多余字段,比如状态。
 
-### 3. 生成工作清单
+### 6. 生成工作清单
 
-执行 `cgraphx features sync`,读 `.cgraphx/my-features.md`——头部补对后,这里应包含当前 git 用户的全部需求。为每个需求建一条待办,进入补全循环。
+执行 `cgraphx features sync` 刷新个人索引(头部补对后 `features list --mine` 才准)。**待办 = 第 4 步确认的不齐全清单**——不从 my-features.md 重建,那里含已齐全的历史需求,不重复进待办。
 
-### 4. 补全循环(逐需求派 filler 子 agent)
+### 7. 补全循环(逐需求派 filler 子 agent)
 
-逐需求核四样,缺什么补什么:
+缺失产物第 3 步已核出(限于第 2 步勾选范围),缺什么补什么:
 
 | 产物 | 文件名 | 缺失时调用 |
 |---|---|---|
 | 单元测试规格 | `<前缀>-单元测试-spec.md` | `/write-unit-test-spec` |
 | 单元测试报告 | `<前缀>-单元测试报告.md` | `/write-unit-test-code`(依赖规格;规格刚补完接着跑) |
-| 设计文档 | `<前缀>-设计文档.md` | `/write-design-doc` |
 | 收口档案 | `收口档案.md` 或 `<前缀>-收口档案.md` | `/end` |
 
 每条待办是独立任务,补全重活不进主上下文——**派 filler 子 agent**:
 
-- 四样齐全 → 待办直接完成,不派
-- 有缺失 → Read `./filler-prompt.md` + 拼任务三件套(需求 / 缺失产物 / 上下文)→ Agent tool 派 `general-purpose`,在隔离上下文按依赖顺序补全(规格 → 报告 → 设计文档 → 档案)
+- 范围内产物全齐(只缺过头部)→ 不派 filler,该需求改动仅头部,直接走小步提交
+- 有缺失 → Read `./filler-prompt.md` + 拼任务三件套(需求 / 缺失产物 / 上下文)→ Agent tool 派 `general-purpose`,在隔离上下文按依赖顺序补全(规格 → 报告 → 档案)
 - **串行**:一需求一子 agent,跑完一个再派下一个(git index 与测试运行是共享资源,不并行)
 - **status 协议**:DONE → sanity check → 提交;DONE_WITH_CONCERNS → 辨因处理(correctness/scope 先解决,observation 记录);NEEDS_CONTEXT → 补 context 重派;BLOCKED → 记「受阻」进下一条(补账任务相互独立,一个卡住不拖其他)
 - **sanity check(主 agent,每需求)**:声称补出的产物真实存在 + git status 只含该需求的文件;不过 → 派修或记录,不提交
 
 **小步提交(每需求独立,主 agent 提交)**:sanity check 通过后,主 agent 按子 agent 报告的「改动文件」清单精确 stage,独立提交,再进下一条:
 
-- 提交范围:该需求 `docs/features/<目录>/` 下本次改动(补的头部 + 补出的规格/报告/设计文档/收口档案)+ write-unit-test-code 产出的测试文件;不混入其他需求、不夹带无关文件
+- 提交范围:该需求 `docs/features/<目录>/` 下本次改动(补的头部 + 补出的规格/报告/收口档案)+ write-unit-test-code 产出的测试文件;不混入其他需求、不夹带无关文件
 - commit message:项目有 `docs/guides/git-standards.md` 按其规范;没有则参考 `docs: <需求标题> 文档补账`
 - 被 precommit 门禁拦截 → 按提示自查 staged diff 后重试(`CGRAPHX_PRECOMMIT_REVIEWED=1`)
-- 该需求无任何改动(四样齐全且头部已全)→ 不产生提交
+- 该需求无任何改动 → 不产生提交
 
-### 5. 收尾汇报
+### 8. 收尾汇报
 
+- 本次产物范围:<勾选的产物;未勾选的既不判定也不补全>
+- 底数:候选 N 个 / 齐全跳过 M 个 / 本次处理 K 个(全齐全时零打扰直接收尾)
 - 补了头部的需求数;「无法补充清单」(无主 spec 的,提示可走 `/write-spec` 补)
-- 每条待办的补全结果:补了什么 / 已齐全跳过 / 子 skill 报告的失败与待确认项 / 受阻跳过
+- 每条待办的补全结果:补了什么 / 子 skill 报告的失败与待确认项 / 受阻跳过
 - 提交清单:每需求一笔(需求 + commit message);push 归用户
 - 下一步交用户,不自动继续
 
@@ -93,7 +115,9 @@ Read 模板 + 拼任务三件套成 prompt,派 `general-purpose`:
 ## 边界场景
 
 - **未提交的需求目录** → 不处理,不猜归属
-- **无主 spec** → 提示无法补充,不代写
+- **候选全齐全** → 决策清单为空,零打扰直接收尾汇报
+- **用户只勾部分产物** → 未勾选的产物既不判缺失也不补全;齐全核验按勾选范围,补全循环只补范围内缺失的
+- **无主 spec** → 提示无法补充,不代写(第 2 步核验时即分流,不进决策清单)
 - **头部行部分存在** → 只补缺失行,不改已有值(负责人已有值也不覆盖)
 - **git 作者命中但用户否认** → 移出清单,不处理
 - **补了头部仍不在 my-features.md** → 提示用户检查头部行格式,不硬改
@@ -102,8 +126,9 @@ Read 模板 + 拼任务三件套成 prompt,派 `general-purpose`:
 ## 不做的事
 
 - 不新建 spec、不改正文、不改文件名(纠正只在头部块:补缺失行 + 删多余字段)
+- 不补设计文档——不在补账范围,发布后按需走 `/write-design-doc`
 - 不处理未提交的需求目录
-- 不自动确认归属清单
+- 不自动确认决策清单(只有不齐全的需求才进清单;确认前不动任何文件)
 - 不写业务实现代码(子 skill 也不写)
 - 不碰他人需求(归属过滤 + 用户确认双保险)
 - 不 push(只提交,push 归用户)
@@ -111,6 +136,9 @@ Read 模板 + 拼任务三件套成 prompt,派 `general-purpose`:
 ## 和其他 skill 的关系
 
 - **implementation / subagent-implement**:上游,代码开发完成后才轮到本 skill
-- **write-unit-test-spec / write-unit-test-code / write-design-doc / end**:由 filler 子 agent 在隔离上下文内按需调用
+- **write-unit-test-spec / write-unit-test-code / end**:由 filler 子 agent 在隔离上下文内按需调用
 - **subagent-implement**:同款 controller/子 agent 模式(隔离派任 + 提交归 controller);这里更轻——无 plan/spec 审查,一需求一子 agent
 - **features sync**:头部补正是它的数据修正——负责人取自 spec 头部,头部缺失时「按人找需求」失效
+
+## 结束后
+- 必须核实单元测试报告中执行情况, 各种情况导致的未执行或者测试不通过 必须提醒用户