@nathan33/nao-skill 0.19.2 → 0.20.0

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

@@ -44,6 +44,6 @@ description: 架构师交付核对清单（按需，评审/ADR 归档前读取
 - [ ] 若本次修订**改变既有条款** ⇒ 已附「**连带同步清单（含 Owner）**」（列出**所有持有该结论的文档** + 各自 Owner），并已通知相关 Owner
 - [ ] 性能指标可量化可监控
 - [ ] 评审已纳入 AGENTS.md 项目约束（输入核对）
-- [ ] 影响面评审已用 `codegraph impact/callers`（或注明回退）
+- [ ] 影响面评审已走三段阶梯：原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段（口径见 @.agents/skills/codegraph.md；或注明回退）
 - [ ] 方案已对照 ≥2 个成熟模式（含「维持现状」基线），适用条件与代价已写明（`docs/research/` 或 ADR 内），且已记不采纳理由
 - [ ] 被指定为 PR Reviewer 时：已在 PR 评论给契约/分层/影响面结论（未改代码；需改已转 RD）

package/.agents/checklists/qa.md

@@ -19,7 +19,7 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 - [ ] 用例不可追溯（无关联需求/AC）？
 - [ ] 只测主路径，无异常/边界覆盖？
 - [ ] 未 Verify 就关闭缺陷？
-- [ ] 定位被测代码/受影响测试未用 `codegraph node/affected`？（回退 grep 需注明原因）
+- [ ] 定位被测代码/受影响测试未走三段阶梯：原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段（口径见 @.agents/skills/codegraph.md）？（回退 grep 需注明原因）
 - [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 - [ ] 视觉/UI 呈现类验证启动了浏览器自动化（无头浏览器/截图对比）？（应产出用户验收清单交用户人工，见 skills/test-design.md「视觉/UI 呈现验证」）
 - [ ] 含 UI 呈现的交付未产出用户验收清单（测什么/怎么操作/预期结果/对应 AC）？
@@ -41,6 +41,6 @@ description: 测试工程师交付核对清单（按需，交付前读取）
 - [ ] UI 四态（加载/空/错误/成功）与反馈模式按 UX Playbook 核对；无硬编码色值残留（rd-fe 侧已扫）
 - [ ] UI 呈现类交付：用户验收清单已产出（最低覆盖集按范围取用，每项含 测什么/怎么操作/预期结果/对应 AC），落 `docs/reports/<编号>-user-acceptance.md`，回执附路径
 - [ ] 环境/运行方式按 AGENTS.md；已遵守项目约束
-- [ ] 受影响测试已用 `codegraph affected` 定位（或注明回退）
+- [ ] 受影响测试已按三段阶梯定位（原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；口径见 @.agents/skills/codegraph.md）（或注明回退）
 - [ ] PR 评论已贴全量门禁精确数字 + 预览环境结论
 - [ ] 未在 PM 验收通过前以「测试已过」催促合并（合并由 RD 在 PM 授权后执行）

package/.agents/checklists/rd-fe.md

@@ -15,7 +15,7 @@ description: 前端研发交付核对清单（按需，交付前读取）
 - [ ] 视图无 `if (status)` 业务分支
 - [ ] Store 存聚合根实例（非裸 DTO）
 - [ ] 组件逻辑 >200 行抽 `useXxx`
-- [ ] 定位/变更代码未先试 `codegraph context/query`？（仅索引不可用才回退 grep + 行段读取，禁 cat 全文）
+- [ ] 定位/变更代码未走三段阶梯（原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；口径见 @.agents/skills/codegraph.md）？禁 cat 全文
 - [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 
 **DI**

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

@@ -1,8 +1,8 @@
 ---
 description: 资深系统架构师角色 Prompt（短常驻）——架构设计/技术选型/评审/ADR
 role: arch-designer
-version: 12
-updated: 2026-10-14
+version: 13
+updated: 2026-10-28
 ---
 
 # 架构设计师
@@ -11,7 +11,7 @@ updated: 2026-10-14
 > 项目约束：项目根 `AGENTS.md`（pi 已注入上下文，**最高优先级**，优先于本卡默认习惯）。
 > 按需技能：@.agents/skills/arch-patterns.md（模式对照表 + ADR 模板）。
 > @.agents/skills/research.md（业界方案检索：边界 + 引用纪律 + 适配三栏）。
-> @.agents/skills/codegraph.md（impact/调用链做影响面评审，替代手动追踪）。
+> @.agents/skills/codegraph.md（三段阶梯定位 + 影响面评审口径：原生入口 `codegraph_explore` → CLI → `grep -rn` + 行段）。
 > @.agents/skills/github-flow.md（被 PM 指定为 PR Reviewer 时的评审范围与流程）。
 
 资深系统架构师，专精分布式系统，遵循企业级最佳实践。核心职责：**设计可扩展、高可用、安全的架构，确保技术决策与业务目标对齐，交付可演进、不过度设计的方案。**
@@ -68,7 +68,7 @@ PRD 摘要/路径、范围与非范围、NFR 基线（缺失必须索要）、
 - 仓库路径以 PM 输入信封「关联仓库」为准；缺失/不确定 → `ask` PM，不臆测。
 - bash 每次冷启动（`cd` 不跨调用）；用绝对路径或单条命令内 `cd <repo> && ...`。
 - 一个会话即可评审两端；cwd 只是主视角默认值。
-- **影响面/调用链评审**：用 `codegraph impact/callers <符号>`（repo 根执行，见 @.agents/skills/codegraph.md）替代手动追文件。
+- **影响面/调用链评审**：原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；详情见 `@.agents/skills/codegraph.md`（替代手动追文件）
 
 ## 九、NFR 归口
 
@@ -100,7 +100,7 @@ PRD 摘要/路径、范围与非范围、NFR 基线（缺失必须索要）、
 
 ## 十三、PR Reviewer（被 PM 指定时）
 
-- 在 PR 上评审**契约 / 分层 / 影响面**（用 `codegraph impact`），评论给结论与风险；**不改代码**（需改转 RD）。
+- 在 PR 上评审**契约 / 分层 / 影响面**（定位口径见 @.agents/skills/codegraph.md 三段阶梯），评论给结论与风险；**不改代码**（需改转 RD）。
 - 评审范围限于架构与契约一致性；实现细节与门禁数字归 RD/QA。
 - 流程见 @.agents/skills/github-flow.md（阶段 5）。
 

package/.agents/prompts/backend-developer.md

@@ -1,8 +1,8 @@
 ---
 description: 后端开发工程师角色 Prompt（短常驻）——Golang DDD
 role: rd-be
-version: 11
-updated: 2026-10-13
+version: 12
+updated: 2026-10-28
 ---
 
 # 后端 DDD 架构师（Golang）
@@ -11,7 +11,7 @@ updated: 2026-10-13
 > 项目约束：项目根 `AGENTS.md`（pi 已注入上下文，**最高优先级**，优先于本卡默认习惯）。
 > 按需技能：
 > @.agents/skills/backend-ddd-details.md（代码骨架、事务、事件、命名、误区）。
-> @.agents/skills/codegraph.md（代码定位，替代 grep 全文扫描，省 token）。
+> @.agents/skills/codegraph.md（三段阶梯：原生入口 → CLI → `grep -rn` + 行段，省 token）。
 > @.agents/skills/commit.md（提交时机/需求分支/可读信息；仅在执行 git commit 前读取）。
 > @.agents/skills/github-flow.md（需求分支 / Draft PR / 验收后 squash 合并）。
 
@@ -49,7 +49,7 @@ updated: 2026-10-13
 
 ## 五、关键约定（简）
 
-- **代码定位**：定位/变更代码先 `codegraph context/query/node`（在 repo 根执行，见 @.agents/skills/codegraph.md）；索引缺失或无结果才回退 `grep -rn` + `sed` 行段读取，**禁 cat 全文**。
+- **代码定位**：原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；详情见 `@.agents/skills/codegraph.md`；**禁 cat 全文**。
 - **事务**：应用层闭包 `repo.Transaction(ctx, func(txRepo) error {...})`；禁在 Interface/Domain 管事务。
 - **读写分离**：复杂列表/报表走 `XxxQuery` + 优化 SQL，返回只读 DTO，**绕过聚合根**。
 - **错误**：Domain 哨兵 `ErrXxx`；Interface 映射 HTTP（`ErrNotFound`→404，`ErrConflict`→409，`ErrInvalid`→400）；禁透传 `sql.ErrNoRows`。

package/.agents/prompts/frontend-developer.md

@@ -1,8 +1,8 @@
 ---
 description: 前端开发工程师角色 Prompt（短常驻）——Vue 3 / React + TS DDD
 role: rd-fe
-version: 11
-updated: 2026-10-13
+version: 12
+updated: 2026-10-28
 ---
 
 # 前端 DDD 架构师（Vue 3 / React + TS）
@@ -12,7 +12,7 @@ updated: 2026-10-13
 > 按需技能：
 > @.agents/skills/frontend-ddd-details.md（骨架、场景速决、命名、误区、UI/UX 落地）。
 > @.agents/skills/frontend-design/SKILL.md（**新建页面/组件或涉及布局样式前先读**：视觉方向/反 AI 味，官方 anthropics/skills）。
-> @.agents/skills/codegraph.md（代码定位，替代 grep 全文扫描，省 token）。
+> @.agents/skills/codegraph.md（三段阶梯：原生入口 → CLI → `grep -rn` + 行段，省 token）。
 > @.agents/skills/commit.md（提交时机/需求分支/可读信息；仅在执行 git commit 前读取）。
 > @.agents/skills/github-flow.md（需求分支 / Draft PR / 验收后 squash 合并）。
 
@@ -40,7 +40,7 @@ updated: 2026-10-13
 - [ ] Domain 零框架；用例仅依赖端口
 - [ ] 视图无 `if (status)` 业务分支；Store 存聚合根（非裸 DTO）
 - [ ] DI 唯一入口 `useXxx`；禁组件/Store 内 `new 仓储`、禁 Context 传业务依赖
-- [ ] 定位/变更代码未先试 `codegraph context/query`？（仅索引不可用才回退 grep + 行段读取，禁 cat 全文）
+- [ ] 定位/变更代码未走三段阶梯（原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；详情见 `@.agents/skills/codegraph.md`）？禁 cat 全文
 - [ ] 改/新增组件未先研究项目既有 UI 风格（读同类组件/tokens/playbook）或未按 tokens/组件库落地？（默认延续既有风格；仅用户指定新风格才脱离）
 - [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 

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

@@ -1,15 +1,15 @@
 ---
 description: 工程基座工程师角色 Prompt（短常驻）——CI/构建发布/脚本守卫/依赖安全/仓库治理
 role: rd-infra
-version: 3
-updated: 2026-10-27
+version: 4
+updated: 2026-10-28
 ---
 
 # 工程基座工程师（Infra）
 
 > 通用规范见 @.agents/common/output-format.md 与 @.agents/common/intercom-protocol.md（常驻）。
 > 项目约束：项目根 `AGENTS.md`（pi 已注入上下文，**最高优先级**，优先于本卡默认习惯）。
-> 按需技能：@.agents/skills/commit.md（提交规范）、@.agents/skills/github-flow.md（分支/PR/合并）、@.agents/skills/codegraph.md（代码定位；无索引回退 grep/read）。
+> 按需技能：@.agents/skills/commit.md（提交规范）、@.agents/skills/github-flow.md（分支/PR/合并）、@.agents/skills/codegraph.md（三段阶梯：原生入口 → CLI → `grep -rn` + 行段）。
 
 负责**工程基座**：CI 与流水线 · 构建/发布工具 · 脚本与守卫（`guard:*`、fleet 脚本）· 依赖与安全告警升级 · 仓库治理 · lint/格式化工具链 · 跨项目安装器与分发 · 开发环境排障。核心职责：让「**怎么构建 / 怎么验 / 怎么发 / 怎么治理**」可靠、可自证、可移植。
 
@@ -49,7 +49,7 @@ updated: 2026-10-27
 - **跨项目**：安装器/脚本在第二个项目或临时目录验证；不假设单仓结构（不写死仓库名/包管理器）。
 - **仓库治理**：分支/保护/清理按已定策略执行；baseline 合并等一次性例外须登记台账。
 - **提交**：路径级暂存（禁 `-A`/`.`/`-a`）；只提自己文件用 `git commit --only <paths>` 并先 `git diff --cached --name-only` 核 index。
-- **定位**：先 `codegraph`（见 @.agents/skills/codegraph.md）；索引缺失/无结果才回退 `grep -rn` + 行段读取，**禁 cat 全文**。
+- **定位**：原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；详情见 `@.agents/skills/codegraph.md`；**禁 cat 全文**。
 
 ## 五、Git 与 PR
 

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

@@ -1,7 +1,7 @@
 ---
 description: 产品经理角色 Prompt（短常驻）——需求分析/PRD/优先级/验收/多会话调度
 role: pm
-version: 27
+version: 28
 updated: 2026-10-28
 ---
 
@@ -13,7 +13,7 @@ updated: 2026-10-28
 > @.agents/skills/pm-to-spec.md（成熟需求直出 PRD：验证接缝 + 对话综合；判定命中即跳过 grill）。
 > @.agents/skills/pm-routing.md（路由与派单纪律 + 技术调研边界；派发/调研前读取）。
 > @.agents/skills/pm-operations.md（调度细则 / 开工确认卡 / 会话生命周期 / AGENTS.md 治理 / 归档）。
-> @.agents/skills/codegraph.md（验收读码：node --file/--limit 行段读取，禁 cat 全文）。
+> @.agents/skills/codegraph.md（三段阶梯：原生入口 → CLI → `grep -rn` + 行段；验收读码只读行段，禁 cat 全文）。
 > @.agents/skills/research.md（产品形态业界调研：清单 + 检索纪律 + 边界）。
 > @.agents/skills/github-flow.md（新需求落地流水线：Issue/分支/PR/验收/squash 合并/发布；立项·终签·发布时读取）。
 
@@ -56,12 +56,12 @@ updated: 2026-10-28
 **PM 是唯一调度者**。操作细则（准入/登记/舰队启动/任务派生/角色提示词加载/收窗）见 @.agents/skills/pm-operations.md §一；路由见 @.agents/skills/pm-routing.md。
 
 - **开工确认闸门**：PRD 完成后**禁止自动派发**，先出「开工确认卡」并经用户确认。
-- **环境自检**：派发前 `bash .agents/scripts/nao-fleet.sh check`——默认单行摘要，`warn>0` 或失败加 `-v`；**exit code 非 0（硬错误）→ 停止派发**。
+- **环境自检**：派发前 `bash .agents/scripts/nao-fleet.sh check`——默认 2 行摘要（摘要行 + codegraph 状态行），`warn>0` 或失败加 `-v`；**exit code 非 0（硬错误）→ 停止派发**。
 - **架构评审闸门**：PRD 涉及架构/NFR/选型时，开工确认后、派发前 `send` arch-designer 评审。纯 CRUD 跳过。
 - **忙闲闸门**：`list` 见目标在线**且 `idle`** 才派完整任务；忙碌（`thinking`/`tool:*`）→ **不投递任务内容**，记入待排队列（`docs/tasks-state.md`），转 `idle` 再派；**紧急**才抢占（交互会话可 steer 注入并注明 `紧急抢占：…回执须报告挂起任务状态`；非交互会话只能排队）。
 - **终态回执闸门**：每次派发（含架构评审）必须收到 `[编号] 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 node --file <f> --offset <n> --limit <m>` 行段，**禁 cat 全文**；**UI 呈现类验收 = 用户验收清单**（QA 产出 → PM 审 → 用户执行回填 → QA 据回填关闭/重开缺陷；清单落 `docs/reports/<编号>-user-acceptance.md`，见 qa 卡）。
+- **验收闭环（省 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 专属）**：按批次边界重开（归档完成 / 用户换需求 / `/session` contextTokens 超窗口 40%）+ 落盘接续 + 重开后**回读确认**；细则见 @.agents/skills/pm-operations.md §三。
 - **状态外部化**：任务状态落 `docs/tasks-state.md`（含接续快照），每次派发/回执/验收后更新；重开先读它。

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

@@ -1,8 +1,8 @@
 ---
 description: 测试工程师角色 Prompt（短常驻）——策略/用例/缺陷/质量保障
 role: qa
-version: 14
-updated: 2026-10-14
+version: 15
+updated: 2026-10-28
 ---
 
 # 测试工程师（QA）
@@ -11,7 +11,7 @@ updated: 2026-10-14
 > 项目约束：项目根 `AGENTS.md`（pi 已注入上下文，**最高优先级**，优先于本卡默认习惯）。
 > 按需技能：
 > @.agents/skills/test-design.md（用例设计、缺陷管理、性能安全、DDD 分层对齐）。
-> @.agents/skills/codegraph.md（`affected` 找受影响测试，替代手动追踪）。
+> @.agents/skills/codegraph.md（三段阶梯：原生入口 → CLI（含受影响测试定位）→ `grep -rn` + 行段）。
 > @.agents/skills/commit.md（提交时机/需求分支/可读信息；仅在执行 git commit 前读取）。
 > @.agents/skills/github-flow.md（PR 验证评论 / 验收与合并时序）。
 
@@ -71,7 +71,7 @@ DDD 分层对齐（简）：
 - [ ] 私自修改现有功能代码？
 - [ ] 未经用户/PM（开工确认卡）确认就执行测试？
 - [ ] 未 Verify 就关闭缺陷？
-- [ ] 定位被测代码/受影响测试未用 `codegraph node/affected`？（回退 grep 需注明原因）
+- [ ] 定位被测代码/受影响测试未走三段阶梯（原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；详情见 `@.agents/skills/codegraph.md`）？（回退 grep 需注明原因）
 - [ ] 未跑**全范围门禁**（不是子目录）并回执精确数字？（PM 不重复跑，回执数字即验收唯一依据；全范围口径见项目 `AGENTS.md`）
 - [ ] 造数/探针类测试**回滚不完整**（漏表 ⇒ 孤儿数据）或**未做收尾孤儿扫描**？
 - [ ] 视觉/UI 呈现类验证启动了浏览器自动化（无头浏览器/截图对比）？（应产出用户验收清单交用户人工，见技能包）

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

@@ -9,7 +9,7 @@
 #
 # 用法
 #   nao-fleet.sh check [--strict] [-v]            静态体检：roles.yaml/缩进/EOL/角色卡/交叉引用/PR 模板/白名单/布局/tmux+pi 前提
-#                                                 默认单行摘要（含 warn 计数）；-v 展开完整报告；失败始终展开
+#                                                 默认摘要 2 行：摘要行 + codegraph 状态行（四态之一）；-v 展开完整报告（六态全展开）；失败始终展开
 #   nao-fleet.sh status                           角色会话在线状态（按 tmux 终端标题/名册判定；权威名单见 intercom list）
 #   nao-fleet.sh ensure <别名>[@<repo>] [更多...]  拉起角色窗口（默认工作区=roles.yaml workspace）
 #   nao-fleet.sh ensure -m <model> <别名>...       显式指定模型（须命中白名单）
@@ -83,20 +83,33 @@ declare -A ROLE_CARDS ROLE_WS ALIAS_ROLE
 MODEL_WHITELIST="${NAO_MODEL_WHITELIST:-}"
 TMUX_LAYOUT="${NAO_TMUX_LAYOUT:-main-row2}"
 # main-row2 主 pane 宽度百分比：默认值与非法值回退共用同一常量（防三处漂移）
-TMUX_MAIN_WIDTH_DEFAULT=35
+TMUX_MAIN_WIDTH_DEFAULT=33
 TMUX_MAIN_WIDTH="${NAO_TMUX_MAIN_WIDTH:-$TMUX_MAIN_WIDTH_DEFAULT}"
 # 最小非主 pane 列宽守卫：默认值与非法值回退共用同一常量（防漂移）
 TMUX_MIN_PANE_WIDTH_DEFAULT=30
 TMUX_MIN_PANE_WIDTH="${NAO_TMUX_MIN_PANE_WIDTH:-$TMUX_MIN_PANE_WIDTH_DEFAULT}"
 # T517：派生宿主窗口 ID（归一化 @<window_id>；空 = 定位失败 ⇒ 该角色 pane warn+skip，禁无 -t 续建）
 HOST_WINDOW=""
-# check 输出契约：默认单行摘要（省 PM 上下文），-v 展开完整报告；失败始终展开
+# check 输出契约：默认摘要 2 行（摘要行 + codegraph 状态行，四态之一），-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}"
 
+# ---- CodeGraph（T532 · BR1/BR2）：四态检测全 warn，**永不计入 rc** ----
+# 包名单源（BR5）：与 bin/nao-skill.js 的 PI_PLUGINS.codegraph 各一处，由 tests/t4/cases/18 等值断言兜住。
+# 运行时**不**跨语言抽取（sed 抽空 ⇒ 静默假「未声明」，且 shim-only 安装可能无 bin/）。
+CODEGRAPH_PKG="@sean_pedersen/pi-codegraph"
+# 状态文案单点（CG_MSG_*）：用例断言只认**固定前缀 + 命令子串**，不断言整行（防文案微调误伤）。
+CG_MSG_UNDECLARED='codegraph 插件未声明（装法：pi install npm:@sean_pedersen/pi-codegraph；定位回退 grep）'
+CG_MSG_NO_CLI='codegraph 插件已声明但 CLI 不在 PATH（装：npm i -g @colbymchenry/codegraph；回退 grep -rn + 行段）'
+CG_MSG_NO_INDEX='codegraph 已就绪但当前仓无索引（codegraph init；索引后每会话约 +70–90MB PSS）'
+CG_MSG_READY='codegraph 齐备（生效还依赖插件未被过滤/禁用）'
+CG_MSG_READY_SHORT='codegraph 齐备（索引新鲜度用 -v 查；生效依赖插件未被过滤/禁用）'
+CG_MSG_PENDING='codegraph 索引 pending（codegraph sync 同步）'
+CG_MSG_UNPARSABLE='codegraph status 输出不可解析（手工 codegraph status 核对）'
+
 log()  { printf '\033[1;32m[fleet]\033[0m %s\n' "$*"; }
 warn() { printf '\033[1;33m[fleet]\033[0m %s\n' "$*" >&2; }
 die()  { printf '\033[1;31m[fleet]\033[0m %s\n' "$*" >&2; exit 1; }
@@ -275,25 +288,45 @@ check_alias_resolution() {
   return $rc
 }
 
-# CodeGraph 索引健康（ensure 拉起前 / check 用；缺失或过期仅 warn，不阻塞）
-check_codegraph() {
-  local repo="$1" name st
-  name="$(basename "$repo")"
-  command -v codegraph >/dev/null 2>&1 || { warn "$name codegraph 未安装（RD 定位将回退 grep，属预期）"; return 0; }
+# CodeGraph 四态检测（T532 · BR1/BR2）—— check / ensure 唯一发射点。
+#   codegraph_state <repo> [full] [name]
+#   ！（永不计入 rc）所有状态都只是**可观测信号**：不设 rc=1、--strict 亦不升级；
+#     理由 = 六会话并发下「索引 pending」是稳态，长期拉红会侵蚀真失败信号（arch A1）。
+#   严格短路：① 声明（两份 settings.json 的 packages 含包名）② command -v codegraph
+#              ③ <repo>/.codegraph ④ status 文本（**仅 full=1**）
+#   full=0（默认 check）：**零 codegraph 调用**（AC11 判据 = codegraph 调用 0 次）——实际新增 2 次 grep fork
+#     （settings 声明匹配 + 摘要行抽取）；不 spawn 任何第三方进程
+#   full=1（check -v / ensure）：每仓一次 `codegraph status`（实测 0.37–0.42s，不进派发热路径）
+#   契约前缀：· 未声明 / ! 已声明但 CLI 不在 PATH / ! 无索引 / ✓ 齐备 / ! pending / ! 不可解析
+codegraph_state() {
+  local repo="$1" full="${2:-0}" name="${3:-}" f declared=0 pre="" st
+  local -a sets=("$PI_AGENT_DIR/settings.json" "$repo/.pi/settings.json")
+  [[ -n "$name" ]] && pre="[$name] "
+  for f in "${sets[@]}"; do
+    [[ -f "$f" ]] || continue
+    if grep -qF -- "$CODEGRAPH_PKG" "$f" 2>/dev/null; then declared=1; break; fi
+  done
+  if (( ! declared )); then
+    printf '  · %s%s\n' "$pre" "$CG_MSG_UNDECLARED"; return 0
+  fi
+  if ! command -v codegraph >/dev/null 2>&1; then
+    printf '  ! %s%s\n' "$pre" "$CG_MSG_NO_CLI"; return 0
+  fi
   if [[ ! -d "$repo/.codegraph" ]]; then
-    warn "$name 无 CodeGraph 索引（RD 定位将回退 grep；建议 codegraph init）"
-    return 0
+    printf '  ! %s%s\n' "$pre" "$CG_MSG_NO_INDEX"; return 0
   fi
-  st="$(cd "$repo" 2>/dev/null && codegraph status 2>&1)"
-  if [[ "$st" == *"Index is up to date"* ]]; then
-    log "$name CodeGraph 索引 ✓ up to date"
-  elif [[ "$st" == *"Pending Changes"* ]]; then
-    warn "$name CodeGraph 索引有未同步变更（建议 codegraph sync）"
-  elif [[ "$st" == *"Not initialized"* ]]; then
-    warn "$name .codegraph 存在但未初始化（建议 codegraph init）"
-  else
-    warn "$name codegraph status 输出不可解析"
+  if (( ! full )); then
+    printf '  ✓ %s%s\n' "$pre" "$CG_MSG_READY_SHORT"; return 0
   fi
+  st="$(cd "$repo" 2>/dev/null && codegraph status 2>&1)" || st=""
+  # 文本契约（已冻结于 codegraph 1.6.2 实测，见 docs/reports/M20261028-codegraph-followups.md §二 T1）
+  case "$st" in
+    *"Index is up to date"*) printf '  ✓ %s%s\n' "$pre" "$CG_MSG_READY" ;;
+    *"Pending Changes"*)     printf '  ! %s%s\n' "$pre" "$CG_MSG_PENDING" ;;
+    *"Not initialized"*)     printf '  ! %s%s\n' "$pre" "$CG_MSG_NO_INDEX" ;;  # 目录在但无 DB（下游常见态）
+    *)                       printf '  ! %s%s\n' "$pre" "$CG_MSG_UNPARSABLE" ;;
+  esac
+  return 0
 }
 
 # pi 运行前提（BR4/AC3）：版本源 = `pi --version` 首个 semver token；预发布（含 `-`）视为不满足。
@@ -1046,7 +1079,7 @@ spawn_one() {
 
   # 前提已由入口 require_tmux 硬校验（exit 3）；此处只走唯一路径（BR1/BR3）。
   prompt_file="$(build_system_prompt "$card")"
-  inner="cd $(printf %q "$repo") && exec pi --name $(printf %q "$name")"
+  inner="cd $(printf %q "$repo") && export CODEGRAPH_TELEMETRY=0 && exec pi --name $(printf %q "$name")"
   [[ -n "$model" ]] && inner+=" --model $(printf %q "$model")"
   inner+=" --append-system-prompt $(printf %q "$prompt_file")"
   ( sleep 60; rm -f -- "$prompt_file" ) & disown 2>/dev/null || true
@@ -1196,27 +1229,13 @@ cmd_check() {
   echo "== 交叉引用（@.agents/common|skills|prompts|scripts/... 均须存在）=="
   check_cross_refs || rc=1
 
-  echo "== CodeGraph 索引（业务 repo 的索引在 ensure 拉起时检查）=="
-  if command -v codegraph >/dev/null 2>&1; then
-    if [[ -d "$PWD/.codegraph" ]]; then
-      local cgst
-      cgst="$(codegraph status 2>&1)"
-      if [[ "$cgst" == *"up to date"* ]]; then
-        echo '  ✓ 当前目录索引 up to date'
-      elif [[ "$cgst" == *"Pending Changes"* ]]; then
-        echo '  ! 当前目录索引有未同步变更（codegraph sync）'; rc=1
-      else
-        echo '  · 当前目录有索引，状态见 codegraph status'
-      fi
-    else
-      echo '  · 当前目录无索引（业务 repo 的索引在 ensure 拉起时检查）'
-    fi
-  else
-    echo '  · codegraph 未安装（回退 grep 属预期行为）'
-  fi
+  echo "== CodeGraph（四态检测：全部 warn，永不计入 rc；默认不调用 CLI）=="
+  local cgfull=0
+  if $VERBOSE; then cgfull=1; fi
+  codegraph_state "$PWD" "$cgfull"
 
   echo "== pi 插件（业界调研能力）=="
-  local piset="$HOME/.pi/agent/settings.json"
+  local piset="$PI_AGENT_DIR/settings.json"
   if [[ -f "$piset" ]]; then
     if grep -q 'pi-web-access' "$piset" 2>/dev/null; then
       echo '  · pi-web-access ✓ 已装（PM/arch 业界调研可用）'
@@ -1553,7 +1572,7 @@ cmd_ensure() {
     # CodeGraph 索引健康（同 repo 只查一次，不阻塞拉起）
     key="$repo"; seen=0
     for k in "${cg_done[@]:-}"; do [[ "$k" == "$key" ]] && seen=1; done
-    if (( ! seen )); then check_codegraph "$repo"; cg_done+=("$key"); fi
+    if (( ! seen )); then codegraph_state "$repo" 1 "$(basename "$repo")"; cg_done+=("$key"); fi
     if [[ "$force" != "true" ]] && running "$disp" "$repo"; then
       warn "$disp 已在运行（终端标题/名册命中），跳过；确需重开请加 --force"
       continue
@@ -1612,7 +1631,10 @@ fi
 
 case "$CMD" in
   check)
-    # 默认单行摘要（派发前自检只需 exit code + 计数；完整报告 30+ 行不进 PM 上下文）；-v 或失败时展开
+    # 默认摘要 2 行（派发前自检只需 exit code + 计数 + codegraph 态；完整报告 30+ 行不进 PM 上下文）；-v 或失败时展开
+    # warn 计数口径：只有**非 codegraph** 的 `  ! ` 行计入摘要 warn=N；codegraph 的四类 `!` 态
+    #   （CLI 不在 PATH / 无索引 / pending / 不可解析）**既不计入 warn、也不进 rc**（BR1 + arch D4）——
+    #   它的可见性由常驻的第 2 行（四态之一）承担，故不会因「不计数」而静默。
     # 子 shell 隔离：cmd_check 内部 die/exit 不得吞掉报告（计数从报告解析，不靠子 shell 内变量）
     REPFILE="$(mktemp)"
     set +e
@@ -1620,7 +1642,9 @@ case "$CMD" in
     CHECK_RC=$?
     set -e
     if (( CHECK_RC == 0 )) && ! $VERBOSE; then
-      WARNS="$(grep -c '^  !' "$REPFILE" || true)"
+      # D4（arch 裁 A）：codegraph 任态**不计入** warn 计数 —— 它是常驻第 2 行，不必重复计数；
+      # 六条 CG_MSG_* 全以 `codegraph ` 开头 ⇒ 前缀匹配不误伤其它体检项（grep -c 0 命中 rc=1，|| true 别丢）。
+      WARNS="$(grep '^  !' "$REPFILE" | grep -vc '^  ! codegraph ' || 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
@@ -1630,6 +1654,9 @@ case "$CMD" in
         printf 'check: OK · roles=%s · files=%s · layout=%s\n' \
           "${ROLES_N:-?}" "${FILES_N:-?}" "$TMUX_LAYOUT"
       fi
+      # CodeGraph 四态行常驻可见（BR9 不静默）：摘要模式下也从报告里抽这一行原样回显，
+      # 保持「默认只出四态中的一行」（PRD AC1）且不额外 fork（full=0 已在报告期算完）。
+      grep -m1 -E '^  . codegraph ' "$REPFILE" || true
     else
       cat "$REPFILE"
     fi

package/.agents/skills/codegraph.md

@@ -1,52 +1,69 @@
 ---
-description: 按需技能——CodeGraph 代码定位（替代 grep 全文扫描，省 token）
+description: 按需技能——CodeGraph 代码定位（三段阶梯：原生入口 → CLI → grep + 行段）
 ---
 
-# CodeGraph 代码定位
+# CodeGraph 代码定位（三段阶梯）
 
-> 用图谱精确命中符号/调用链/影响面，**替代"grep 全文 + cat 大文件"**——上下文只进相关代码块。
-> 不可用时降级到 `grep -rn` + 行段读取（见文末）。
+> 目标不变：图谱精确命中符号/调用链/影响面，**替代「grep 全文 + cat 大文件」**——上下文只进相关代码块。
+> 口径按阶梯降级：**① 原生入口 → ② CLI → ③ `grep -rn` + 行段**。任一步不可用即顺延，**不需审批**；
+> 「**禁 cat 全文**」永久有效。
 
-## 何时用（对比 grep）
+## ① 原生入口（首选）
 
-| 场景 | 首选 | 理由 |
-| :--- | :--- | :--- |
-| 定位函数/类型/符号定义 | `codegraph query` | 语义精确，一次命中 |
-| 理解某任务涉及哪些代码 | `codegraph context "<任务>"` | 一次返回相关符号+代码块，无需多轮 grep+cat |
-| 追踪调用链 / 改动影响面 | `callers` / `callees` / `impact` | 图谱遍历，替代手动读 N 个文件 |
-| 找受影响的测试 | `codegraph affected` | 一步到位 |
-| 文件名/配置/字符串/文档 | `grep -rn` | 更快更直接，不绕道 |
+- 唯一硬编码工具名 = **`codegraph_explore`**（上游默认只暴露它；其余工具名**不写死** —— 是否出现随
+  CLI 版本 / `CODEGRAPH_MCP_TOOLS` 变化，需用时先看会话工具列表）。
+- 一次调用拿「相关符号源码 + 调用路径」，等价于 `codegraph explore`。
+- 生效前提（三者齐备）：插件已声明 + CLI 在 PATH + 当前仓有 `.codegraph/` 索引。
+  **有插件无索引 / 无 CLI ⇒ 不生效**（插件激活条件 = cwd 存在 `.codegraph/`，否则静默 no-op）。
+- 注意「已声明 ≠ 生效」：`check` 的声明判定读的是 `settings.json` 的 `packages` 条目 ——
+  条目被 `pi` 过滤 / 禁用时仍算已声明（⇒ 会报「齐备」但工具未必出现在会话里）；工具是否真在，
+  以会话工具列表为准。
+- **插件不供 system prompt 指引（截至 pi 1.4.0 / pi-codegraph 0.1.0）** —— 舰队恒带
+  `--append-system-prompt`，该开关抑制插件的指引注入 ⇒ 口径由**本技能**承载（不要期待自动注入）。
 
-## Token 纪律（省的是上下文累积）
-
-- **一次 `context` 拿全，不再 grep+cat 同一段代码**——codegraph 已给出精确代码块，直接使用。
-- 输出过大用 `-n <num>` 限符号数；只看结构用 `--no-code`。
-- 文件模式用 `node --file <f> --offset <n> --limit <m>` 只读需要的行段，**禁止 cat 全文**。
-- 大任务拆成多个子问题分别 `context`，不做一次超大查询。
-- 拿到的代码块不重复读取（同一内容第二次进上下文 = 重复计费）。
+## ② CLI（原生入口不可用时的回退）
 
-## 命令速查
+真实命令（`codegraph 1.6.2` 实测；**上游 README 与本机 CLI 冲突时以实测为准**）：
 
-- `codegraph status` — 索引健康检查（无索引 → `codegraph init`；有改动 → `codegraph sync`）
+- `codegraph status` — 索引健康（无索引 → `codegraph init`；有改动 → `codegraph sync`）
+- `codegraph status --json` — 同上（机器读；`pendingChanges` / `index.state`）
+- `codegraph explore "<查询>"` — 相关符号源码 + 调用路径（= 原生入口同款输出）
 - `codegraph query "<符号>"` — 精确定位符号
 - `codegraph context "<任务描述>"` — 任务上下文：相关符号 + 关系 + 代码块
 - `codegraph node <符号>` — 符号源码 + caller/callee 调用链
 - `codegraph node --file <f> --offset <n> --limit <m>` — 读文件行段（带行号）
 - `codegraph callers <符号>` / `codegraph callees <符号>` — 调用追踪
-- `codegraph impact <符号>` — 改动影响分析（**修改前必跑**）
+- `codegraph impact <符号>` — 改动影响分析（**改前必跑**）
 - `codegraph affected <文件...>` — 受影响的测试文件
 - `codegraph files` — 项目文件结构
+- `codegraph init` — 首次建索引（**不带 `-i`**：该 flag 已废弃，仅向后兼容）
+- `codegraph sync` — 增量同步（写完代码提交前跑一次）
+
+## ③ `grep -rn` + 行段（保底，永不过期）
+
+- `grep -rn "<关键词>" --include=<扩展名> <目录>` 定位，再 `sed -n '<起>,<止>p' <文件>` 读**精确行段**；
+  **禁止 cat 全文**。
+- 非代码内容（配置/字符串/日志/文档）直接 grep，不绕道。
+- 查询无结果先换关键词再试一次，仍无 ⇒ 回退（写明原因即可，不需要审批）。
+
+## Token 纪律（省的是上下文累积）
+
+- 一次 `explore` / `context` 拿全，不再 grep + cat 同一段代码；拿到的代码块不重复读取。
+- 输出过大用 `-n <num>` 限符号数；只看结构用 `--no-code`。
+- 大任务拆成多个子问题分别查，不做一次超大查询。
 
-## 工作区与索引维护
+## 索引维护（项目级）
 
-- 索引是**项目级**的：在对应 repo 目录跑（fleet 会话 cwd 即 repo）；跨仓库用 `-p <路径>`。
-- 写完代码跑一次 `codegraph sync` 保持索引新鲜（提交前）。
-- 首次进入新 repo：`codegraph status` → 无索引则 `codegraph init`（一次性成本，之后只 `sync`）。
+- 索引是**项目级**的：在对应 repo 目录跑（舰队会话 cwd 即 repo）；跨仓用 `-p <路径>`。
+- 首次进新仓：`codegraph status` → 无索引则 `codegraph init`（一次性，之后只 `sync`）。
+- 索引未同步（`codegraph status` 报 `Pending Changes:`）不影响本技能可用性，提交前 `codegraph sync`。
+- `check` 的 codegraph 行**全是提示，永不进退出码**：`-v` 才看索引新鲜度（默认只报是否齐备）。
 
-## 降级（codegraph 不可用 / 无结果）
+## 副产物与 daemon（已知边界，机制不代跑）
 
-1. 无 `.codegraph/` → 先 `codegraph sync`；仍失败则 `codegraph init`（慢则放弃）。
-2. 查询无结果 → 换关键词再试一次 → 仍无 → 回退。
-3. **回退 grep**：`grep -rn "<关键词>" --include=<扩展名> <目录>` 定位，再用
-   `sed -n '<起>,<止>p' <文件>` 读精确行段；**禁止 cat 全文**。
-4. 非代码内容（配置/字符串/文档）直接 grep，不绕道。
+- 插件在项目根创建 `.pi/APPEND_SYSTEM.md`，正常会话退出时删除；但**任何加载扩展的非会话 `pi` 调用**
+  （`pi list` / `pi install` / `pi --help -e`）也会写它且不触发清理 ⇒ 残留。本仓 `.gitignore` 已覆盖该单文件；
+  需要清理时**用户手工** `rm -f .pi/APPEND_SYSTEM.md`（nao 不写、不删 —— 无法区分用户自建）。
+- 已建索引的仓内，非会话 `pi` 动作可能留下 1 棵孤儿 `codegraph` daemon（约 177MB RSS）。规避：
+  `( cd /tmp && pi list )` 在**非索引 cwd** 执行（实测 0 副作用）；已泄漏则 `codegraph daemons`（交互选停）
+  或 `kill <pid>`。nao 侧**不杀 daemon**（daemon argv 不含仓库身份 ⇒ `pkill` 会跨仓误杀）。

package/.agents/skills/pm-operations.md

@@ -12,7 +12,7 @@ description: 按需技能——PM 运行手册（调度细则 / 开工确认卡
 - **准入判定**：先 `intercom status` + `list`；不可用立即降级不重试。
 - **会话登记**：用户提供名称**及角色标注**（`fe-dev`/`be-dev`/`qa`/`infra`）；**未标注禁止猜测**，必须补问。
 - **舰队启动**：不在线先拉起再 `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「开工前自检」）。
+- **环境自检（开工确认后、派发前）**：`bash .agents/scripts/nao-fleet.sh check`——默认 2 行摘要（摘要行 + codegraph 状态行；完整报告不进 PM 上下文），`warn>0` 或失败加 `-v`；**exit code 非 0（硬错误）→ 停止派发**（白名单 / CodeGraph 处置见 intercom-protocol「开工前自检」）。
 - **架构评审闸门**：PRD 涉及架构/NFR/选型时，开工确认后、派发前 `send` arch-designer 评审。纯 CRUD 跳过。
 - **派发协议（省 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 注入并注明 `紧急抢占：…回执须报告挂起任务状态`；非交互会话只能排队）。
@@ -22,7 +22,7 @@ description: 按需技能——PM 运行手册（调度细则 / 开工确认卡
 - **残留自检**：`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 先行用例。
+- **验收闭环（省 token）**：核对 AC 五覆盖 + 回执「清单」字段（未核对则打回）；验收 = 核对回执**全量门禁精确数字** + 读变更文件核对 AC + **异常才复跑/抽查**（**不可改码**、**不重复跑 worker 已跑的门禁**）；读码走三段阶梯（原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段；行段读取如 `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。
 
 ## 二、开工确认卡（强制闸门）

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

@@ -15,7 +15,7 @@
   - 构建/启动：`<cmd>`
   - 测试：`<cmd>`
   - lint/格式：`<cmd>`
-  - 代码索引同步：`codegraph sync`（如已配）
+  - 代码定位：原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段（`codegraph init` 建索引**不带 `-i`**；`codegraph sync` 同步；见 @.agents/skills/codegraph.md）
 - **环境**：<关键环境变量 / 运行方式 / 数据依赖>
 
 ## 项目约束（红线）
@@ -28,7 +28,8 @@
 
 ## 与 nao 机制衔接
 
-- **CodeGraph**：本仓库 `.codegraph/` 索引；写完代码 `codegraph sync` 保持新鲜。
+- **CodeGraph**：三段阶梯「原生入口 `codegraph_explore`（需插件 + CLI + 索引齐备）→ CLI → `grep -rn` + 行段」；本仓库若建了 `.codegraph/` 索引，写完代码 `codegraph sync` 保持新鲜。
+- **插件副产物**：`.pi/APPEND_SYSTEM.md` 是插件生成物（非会话 `pi` 调用会残留）→ 建议 `.gitignore` 加**单文件** `.pi/APPEND_SYSTEM.md`；已建索引的仓内跑非会话 `pi` 动作请换 cwd（`( cd /tmp && pi … )`），已泄漏的 daemon 用 `codegraph daemons` 手工停（nao 不代杀）。
 - **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`。

package/README.md

@@ -36,6 +36,23 @@ nao-skills 是一套 **角色卡 + 协作规矩 + 小工具**。装上以后，
 
 升级：改 `.pi/settings.json` 里的 pin 版本，再 `pi update --extensions`（机制以包为准，项目里只有 shim）。
 
+### CodeGraph（可选增强，不装也能干活）
+
+插件 `@sean_pedersen/pi-codegraph` 给角色一个原生定位入口，但**三者齐备才生效**：插件已声明 + `codegraph` CLI 在 PATH + 当前仓有 `.codegraph/` 索引。缺任一 ⇒ 自动回退 CLI / `grep -rn` + 行段，`check -v` 会告诉你缺什么（**全部只是提示，永不进退出码**）。
+
+```bash
+npm install -g @colbymchenry/codegraph     # CLI（实测 1.6.2）
+codegraph telemetry off                    # 关匿名遥测（舰队 session 由 nao 自动注入 CODEGRAPH_TELEMETRY=0）
+cd <repo> && codegraph init                # 建索引（不带 -i；该 flag 已废弃）
+```
+
+**资源**：sidecar 内存口径 = 进程树全集 **PSS 之和**（RSS 求和会重复计共享页）。本机实测同一仓 6 会话全集 **PSS 675.7MB**、同仓边际 **+70–90MB/会话**、**每新增一个有索引的仓 ≈ +155MB**（daemon + watchdog，按仓共享）⇒ 成本跟**仓数**走，不跟会话数线性放大。默认 `check` 不 fork CLI（零外部进程），`-v` / `ensure` 才每仓跑一次 `codegraph status`（约 0.4s）。
+
+**副产物与 daemon**（已知边界，nao 不代清理）：
+
+- `.pi/APPEND_SYSTEM.md` 由插件生成 —— 正常会话退出会删，但**任何加载扩展的非会话 `pi` 调用**（`pi list` / `pi install` / `pi --help -e`）会写完就残留 ⇒ 已加进本仓 `.gitignore`（单文件）；需清理时**自己** `rm -f .pi/APPEND_SYSTEM.md`。
+- 已建索引的仓内做个非会话 `pi` 动作，可能留下 1 棵孤儿 `codegraph` daemon（约 177MB RSS）。规避：**在非索引 cwd 执行** —— `( cd /tmp && pi list )`（实测 0 副作用）；已泄漏用 `codegraph daemons`（交互选停）。nao 不会去杀它（daemon 的 argv 不含仓库身份，`pkill` 会跨仓误杀）。
+
 **老项目迁移**（曾在项目里铺开整套 `.agents/` 的）：执行 `npx @nathan33/nao-skill migrate` 即可，细则见文末「老用户迁移与维护者注记」。
 
 ## 用起来（3 步）
@@ -81,7 +98,7 @@ PM：在 PR 核 AC 并评论 → 验收通过（授权合并）→ rd-be squash
 - **常驻的东西尽量小**：每个角色卡只留最硬的红线，细节放到用到时才读的文件里。
 - **按需才读**：设计规范、检查清单、读代码手册，都是在需要那一刻才读进上下文。
 - **不靠聊天记录记事**：任务状态和待办写在 `docs/` 文件里；会话重开先读文件恢复状态。
-- **查代码用索引**：配了 CodeGraph 就一次拿到相关代码块，比全文搜索省一个数量级。
+- **查代码用索引**：配了 CodeGraph 就一次拿到相关代码块，比全文搜索省一个数量级。它**不是硬依赖** —— 插件 / CLI / 索引缺任一就自动回退 `grep -rn` + 行段，`check` 的 codegraph 行永远只是提示（不进退出码）。
 
 一句话概括定位：这是在给 AI 做「上下文工程」——决定每个会话**该看到什么、不该看到什么**；在这之上再叠了多会话协作和交付纪律。它自己不跑 AI，产出的是给 AI 读的 Markdown。
 

package/package.json

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