plan-next について
plan-nextは、プロジェクト資産を調査し、目標の連鎖にある最初の不足を特定して次の行動を提案する読み取り専用のガバナンススキルです。毎回最初から調査し、後続作業は実行しません。
主な機能
- 01戦略・計画・設計・コード・規則の資産を調査
- 02目標ツリーから優先度の高い不足を特定
- 03ノードの状態から集中または並行作業を判断
- 04文書のドリフトとガバナンス上の衛生問題を確認
- 05優先度と完了条件を添えて提案
活用シーン
- 01タスク完了後に次のガバナンス上の重点を決定
- 02戦略目標からタスクまでの最初の不足を発見
- 03阻害事項を特定し独立作業の開始可否を判断
- 04文書のドリフトと未対応の衛生問題を確認
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/plan-nextを入力して読み込まれたか確認します。
同梱ファイルREADME.md
詳細
プロジェクトの README より技能：计划下一步（Plan Next）
角色：治理入口顾问 WHAT：按三步法 扫（盘点治理资产）→ 诊（目标树遍历——逐目标深度优先找首个未完成节点，结合并行判定）→ 荐（给出下一步行动建议） HOW：只读诊断；单一维度问题（只查已知缺失）直接推荐专用技能（
define-*等） 区别：本技能仅给出建议，不执行下游；文档健康检测由 runtime / linter / CI 工具按rules/doc-health-criteria.md执行
目的与边界
盘点治理输入源并给出下一步行动建议。
适用时机：项目任何阶段均可；推荐在每次任务完成后执行，用以确认下一焦点。
边界
| 维度 | 做 | 不做 |
|---|---|---|
| 建议 | 给出下一步行动建议（散文或结构化卡片） | 不充当任务状态 API；不维护任务列表 / 不分配；不记任务历史，不答"本周晋升几条"类时序问题 |
| 执行 | 只读——建议交用户或外层编排器决策 | 不自动推进下游；不充当自动化引擎——自动化由外层编排器 + loop 组合驱动 |
行为
整体规则：无状态——每次从零重扫，不依赖上次结果。三步法：扫 → 诊 → 荐。
步骤 0：规范解析
cache 用于步骤 2.1 的 path_pattern 解析。
步骤 1：扫 — 资产盘点
扫什么：3 抽象层 × 5 主题（联合 MECE）。
| 抽象层 | 主题 | 扫描位置 | 细化字段 |
|---|---|---|---|
| 意图层 | Why | docs/project-overview/{mission,vision,north-star,strategic-goals,strategic-pillars}.md | — |
| 意图层 | What/When | docs/process-management/{roadmap,backlog/}.md、docs/requirements/、docs/tasks/ | 路线图 → 节点状态；tasks/ → status |
| 意图层 | How | docs/adr/、docs/designs/ | status |
| 实施层 | Is | 仓库代码 | — |
| 元规则层 | Rules | docs/ARTIFACT_NORMS.md、specs/、protocols/、rules/ | — |
抽象层互斥；细化字段是同主题的辅助维度，不是独立扫描，供 §2.1 消费。
怎么扫——对每项资产记录 2 字段：
| 字段 | 判据 |
|---|---|
| 路径 | 文件系统路径 |
| 状态 | present（存在且内容非空非占位）/ placeholder（仅含 [TODO]/<待填>/TBD）/ missing（不存在） |
步骤 2：诊 — 目标树遍历
核心问题：目标链在哪里卡住了？下一步该专注还是并行？
模型：治理制品构成一棵树；"下一步"= 优先级最高目标下，深度优先找首个未完成节点，结合并行判定给出执行建议。
战略目标
└── 路线图节点（多个，有顺序）
└── 需求（多个，每路线图节点下）
└── 设计/ADR（多个，每需求下）
└── 任务（多个，每设计下）
4 子步骤（依次执行）：
| 子步 | 做什么 | 产出 |
|---|---|---|
| 2.0 前置闸门 | Rules 层是否就位？ | 否则短路 |
| 2.1 目标树遍历 | 逐目标深度优先遍历，定位首缺口 + 并行判定 | 每目标的当前位置 + 路由建议 |
| 2.2 漂移巡检 | 制品 updated_at vs 对齐目标变更时间，超阈值路由专用技能 | 漂移条目列表 |
| 2.3 卫生巡检 | 已完成里程碑归档、ADR 状态、仓库结构、技能层改动等 | 卫生问题条目列表 |
G1-G4 缺口类型用作诊断依据节的子标签。
2.0 前置闸门：Rules 层缺位检查
若 ARTIFACT_NORMS.md 缺失或 specs/ 为空，触发短路：跳过目标树遍历，"现在该做"只列一条 P0 路由（建立规范 + 重跑 plan-next）。
2.1 目标树遍历
节点状态判定
每个制品节点（路线图节点 / 需求 / 设计 / 任务）的状态按以下规则解析：
- 显式优先：读取制品文件 frontmatter 中的
status:字段- 有效值：
pending（默认）|in-progress|done|blocked
- 有效值：
- 子节点推算（无显式
status:时）：- 所有直接子节点
done→ 当前节点视为done - 任一直接子节点
in-progress→ 当前节点视为in-progress - 无子节点 → 视为
pending
- 所有直接子节点
- 优先级：显式字段 > 子节点推算
并行决策规则
在任意层级，扫描该层所有兄弟节点后，按以下规则判定：
| 当前层兄弟节点状态 | 并行建议 |
|---|---|
仅 1 个 in-progress，其余 pending | 专注：完成当前再启动下一个 |
1+ 个 blocked，有 pending 且独立 | 并行：blocked 继续等待，启动下一个独立节点 |
多个 in-progress（均未 blocked） | 收敛：识别最滞后的，优先推进至完成 |
全部 done | 触发上层下一兄弟推进 |
全部 pending，无 in-progress | 启动：路由最高优先级 pending 节点 |
节点间有显式 depends_on: 依赖 → 被依赖节点必须先完成，不可并行。
层级定义
| 层级 | 名称 | 存在性判据 | 完成判据 |
|---|---|---|---|
| L1 | 战略目标 | strategic-goals.md present 且非占位，含 ≥1 可识别目标项 | 同时满足：(a) 目标 status = done；(b) 目标"验收标准"中所有可观测 KPI 已达成（数据可查且达标）。status = approved 视同 in-progress，必须继续下钻 |
| L2 | 路线图节点 | 路线图节点存在且可追溯到 L1 某目标 | 节点 status = done（显式或子推算） |
| L3 | 需求 | 需求文件 present 且非占位 | status = done（显式或子推算） |
| L4 | 设计 | 设计/ADR 文件 present 且非占位 | status = done（显式或子推算） |
| L5 | 任务 | 任务记录 present | status = done |
L1 验收 KPI 强制检查（关键）
不可跳过：每次遍历 L1 目标时，必须先解析「验收标准」字段，提取其中的可观测 KPI（含名称 + 目标阈值 + 数据源）。然后判定 KPI 当前状态：
| KPI 状态 | 含义 | L1 完成判定 |
|---|---|---|
| 已达成（数据≥阈值，连续条件满足） | 验收通过 | L1 done（前提 status=done） |
| 未达成（数据<阈值或连续条件不满足） | 验收未通过 | L1 in-progress，继续下钻 |
| 数据缺失（无监控/无查询路径） | 验收不可验证 | L1 in-progress，且首条路由必须先建立 KPI 数据源（早于任何下游路由） |
关键反模式：status = approved ≠ L1 完成。approved 表示决策已批准，仅说明文档已成型；done 表示验收已达成。混淆这两者会跳过整棵 L1 子树的下游遍历，导致直接从中间层（M5/任务）开始扫描，丢失"为什么这条任务重要"的因果链。
无目标场景：strategic-goals.md 缺失且 mission.md 也缺失 → 路由 define-mission（P0）；mission.md present 但无战略目标 → 路由 design-strategic-goals（P0）。
路线图未分层：路线图存在但无 Now/Next/Later 分层 → 路由 promote-roadmap-items（P1），不继续评估下游。
遍历算法
对 每个战略目标 G（按优先级顺序，跳过 status = done 的）：
[L1] 目标自身 status = done？→ 跳过，检查下一目标
[L2] 取 G 下所有路线图节点，应用并行决策规则：
无节点 → 路由: define-roadmap（P1）；停止此目标
全 done → G 达成；考虑新目标；停止
取"当前焦点节点"集合 F（依并行决策）
对 F 中每个节点 N（按优先级）：
[L3] 取 N 下所有需求，应用并行决策规则：
无需求 → 路由: capture-work-items（P2）；停止此节点
全 done → N 完成；移向下一兄弟路线图节点
对当前焦点需求 R：
[L4] 取 R 下所有设计，应用并行决策规则：
无设计 → 输出"设计待制作"待执行卡片（设计工作流由 AgentFabric runtime 承接）；停止此需求
全 done → R 完成；移向下一兄弟需求
对当前焦点设计 D：
[L5] 取 D 下所有任务，应用并行决策规则：
无任务 → 输出"任务待拆分"待执行卡片（任务拆分由 AgentFabric runtime 承接）；停止此设计
全 done → D 完成；移向下一兄弟设计
有 blocked 任务 + 有独立 pending 任务 → 并行：路由启动 pending
有 in-progress 任务（未 blocked）→ 专注：执行中，检测卡点
★ 全 pending 无 in-progress（任务已拆分但未启动）→
治理层无可路由子技能（执行属开发者层，不是 plan-next 范围）；
"现在该做"输出"待执行"标记卡片（区别于"无内容"），含：
- 焦点任务名 + 任务 ID + 关联战略目标 + 该任务对 L1 验收 KPI 的影响路径
- 标签：`待执行`（新优先级标签，区别于紧急/重要/缓/可略）
此卡片用于告知 orchestrate-governance-step：治理就绪、等待外部执行（应输出 blocked，不是 done）
物理扫描方法（L3-L5 存在性检测）
2.1.1 从步骤 0 cache 读各 artifact_type 的 path_pattern
（命中用项目值；未命中 fall back 到技能默认规范路径）
2.1.2 按节点 slug 在各 path_pattern 目录 glob
→ 匹配到 = 存在；未匹配 = G1 缺口
2.1.3 (增强) 扫前置属性 `parent:` 字段构反向索引补充信任度
2.1.4 (增强) 检测清单文件（如 `now/<slug>.md`）
→ 存在则对比清单 vs 物理；差异作 G3 漂移
2.1.5 G1 通过后检查层间内容对应（G3 链路）：
L3→L4：设计含 parent/upstream_ref 指向需求，或内容明确响应需求关键约束
L4→L5：任务含 parent 指向设计，或覆盖设计中的主要实现模块
深度优先：L3→L4 G3 命中则不继续报 L4→L5 G3
诊断依据需注明扫描依赖的物理信号组合（例："slug + 检测到 2 个清单 + 无 parent 字段"）。
诊步骤产出物
步骤 3 消费以下产出：
- 每目标遍历结果：{目标名称, 当前焦点节点, 所在层级, 并行建议, 缺口子标签（G1/G2/G3）, 推荐技能}
- blocked 节点列表：[(层级, 节点名, blocked 原因（若有）)]
- 次要发现：聚焦目标之外的其他发现
- 漂移条目列表（步骤 2.2 产出）：[(制品路径, 漂移类型, 推荐技能)]
- 卫生问题列表（步骤 2.3 产出）：[(问题描述, 推荐技能)]
步骤 2.2：漂移巡检
比较制品的 updated_at 与对应层级变更事件时间，超阈值则路由专用技能。
阈值（内部常量，不暴露给用户）：
| 参数 | 默认值 | 含义 |
|---|---|---|
drift_staleness_days | 30 | 制品未更新超过此天数视为漂移 |
backlog_rescore_days | 90 | backlog 最后重评超过此天数视为老化 |
doc_health_staleness_days | 30 | 文档健康报告超过此天数视为过期（runtime / CI 产出） |
路由表：
| 漂移信号 | 推荐技能 |
|---|---|
backlog last_rescored_at 超 backlog_rescore_days | /prioritize-backlog |
| 架构文档 vs 代码漂移（ADR updated_at 与最近代码提交差距超阈值） | /review-architecture |
| 文档 SSOT / 代码对齐 / 链路腐烂等健康信号 | runtime / linter / CI 工具按 rules/doc-health-criteria.md 检测 |
约束：漂移项强制进「也要留意」节，不占用「现在该做」前两位（除非主路由空闲且漂移优先级达 P1）。
步骤 2.3：卫生巡检
检查慢性积累的治理债务，输出卫生问题列表。
阈值（内部常量）：
| 参数 | 默认值 | 含义 |
|---|---|---|
milestone_archive_age_days | 60 | 里程碑完成后超过此天数成熟可归档 |
milestone_archive_lookback | 2 | 当前进行中里程碑索引与 slug 差值 ≥ N 视为可归档 |
检查项：
| 检查 | 判定条件 | 推荐技能 |
|---|---|---|
| 已完成里程碑未归档 | milestones/{slug}/tasks.md 全 done，且满足成熟度任一条件 | /archive-milestone {slug} |
| ADR 状态闭环违规 | superseded / 冲突 / 无 accepted 结论 | /review-architecture |
| 仓库结构漂移 | _templates/ 遗漏 / 文件命名违规 | runtime / CI 按 rules/repo-structure-hygiene.md 检测 |
| 文档健康检测积压 | 健康报告 > doc_health_staleness_days 天未更新 | runtime / CI 跑一次 rules/doc-health-criteria.md 全量检测 |
约束：卫生项强制进「也要留意」节，不占用「现在该做」前两位。
步骤 3：荐 — 路由生成与分层
来源：消费步骤 2 的产出（见"诊步骤产出物"）。
3.1 分层决策
消费 §2.1 产出的每目标遍历结果，全部路由至"现在该做"（1-3 条）：
- 主链路由（最高优先级目标的首缺口）必进"现在该做"
- 并行路由（blocked 触发的独立节点）若可立即执行，也进"现在该做"
- 超出 3 条时，按优先级截断；其余目标的次要缺口不展示
并行路由：并行决策建议为"并行"或"收敛"时，在路由依据中明确说明并行理由或收敛目标；"专注"时只路由当前节点。
兄弟推进规则：当一个节点完成时，自动推进至同层下一兄弟节点，不需要用户重跑；遍历在下一兄弟的首缺口处停止。
多任务多卡渲染规则：
当 L5 全 pending 触发"待执行"分支且独立可启动任务 ≥2 个时，渲染多张并列卡片而非合并到单卡。每张卡聚焦 1 个任务。最多 3 张；超出按 §3.2 优先级截断。
- ✅ 正确：3 张并列卡片，每张一个任务（行动名称、TL;DR、完成标志各自独立）
- ❌ 禁止：单卡主题用顿号 / 加号 / "并行启动" 等动词合并多任务（如
T51 + T-SG5-002 并行启动） - ❌ 禁止：单卡完成标志堆叠多任务的 KPI（如
T51 仪表盘可访问 + T52 日志可查 + T-SG5-002 后台可用）
明日就绪、本周稍后就绪等时间差任务，用 缓 标签 + TL;DR 注明就绪时间；不要把它塞进当下卡的脚注。
3.2 优先级（治理紧迫性）
- 现在（P0）：阻断其他治理进展的根基问题（Rules 层缺失或 L1 无目标）
- 下次（P1）：L2 路线图缺失或未对齐目标
- 以后（P2）：L3-L5 任意层级缺口
- 可忽略（P3）：其余次要发现
3.3 输出格式选择
输出格式根据场景自适应：
| 场景 | 推荐格式 |
|---|---|
| 单条建议，情况清晰 | 散文：1-3 句话说清楚做什么、为什么、完成标志 |
| ≥2 条并列建议，或需要并行 / 收敛判断 | 结构化卡片（见下方格式） |
散文格式（简单场景）：直接用自然语言表述，包含：做什么 → 为什么现在 → 怎么算完成。不需要字段、标签、卡片头。
结构化卡片格式（复杂场景，≥2 条并列建议时）：
**N. [行动名称]** · `优先级标签`
> [TL;DR 卡片头：一句话答"做什么 → 立刻可见的收益"，≤30 字]
- 治理上下文：[多行短链，每行 ≤25 字，详见下方"治理上下文写法"]
- 推荐技能：`/skill-name [聚焦点 ≤40 字]`
- 依据：[文件路径或可观测信号 ≤20 字]
- 完成标志：[可观测结果 1 句话]
- [选填] 暂缓代价：[不做的影响 ≤30 字]
- [选填] 上手门槛：[前置知识 / 文档路径 ≤30 字]
共同约束（散文和卡片均适用）：无论使用哪种格式，每条建议必须包含：做什么、为什么、可观测的完成标志。项目代号首次出现必须附自然语言副标题（详见 §3.3.1 + §3.7）。
TL;DR 卡片头写法：
引用块（> ...）形式，置于优先级标签下方、字段列表上方。回答"做什么 → 立刻可见的收益"，≤30 字。视觉锚点最高，让读者首屏即知核心动作。
- ✅ 好例：
> 让 PM 实时看到覆盖率进度，填补 Goal 1 验收的可视化缺口。 - ❌ 坏例：
> 启动并行任务以推进里程碑（与下方主题字段重复，无新信息）。
治理上下文写法：
显示从战略目标到当前缺口的追踪链，且必须包含 L1 验收 KPI 的当前状态。改为多行短链格式（每行 ≤25 字）：
- 治理上下文：
- 战略目标：[目标自然语言名 + 一句话核心 KPI]
- 当前 KPI：[当前值 / 目标值 / 参考系；无数据写"数据缺失"]
- 路线图：[里程碑自然语言名 + 当前阶段]
- 当前位置：[卡口所在层 + 卡因，≤15 字]
每行 ≤25 字硬上限。超长拆下一行；嵌套括号不超过 1 层。
强制约束：每条路由必须显式回答「这个动作如何回到战略目标的验收？」如果回不到，应改为路由 KPI 数据源建立任务，不得直接路由下游执行。
KPI 状态三种表达（沿用三件套，详见 §3.3 阈值标注）：
- 已达成：
引用可见率 85% / 目标 ≥80% / 行业 75-85%（达成） - 未达成：
引用可见率 62% / 目标 ≥80% / 行业 75-85%（未达）或引用可见率 数据未测 / 目标 ≥80%（待测） - 数据缺失：
引用可见率 数据源缺失 / 目标 ≥80% / 参考系无（数据源待建）
阈值标注三件套：
任何 KPI / 阈值首次出现必须三件套：
格式：
[指标名（口语化解释）]：当前 X / 目标 Y / 参考系 Z示例：
采纳率（用户主动接受推荐占比）：当前 42% / 目标 ≥70% / 行业 50-65% 算良好
参考系取一：行业基准 / 项目历史值 / 经验阈值。无参考时写"项目自定（无外部基准）"提醒读者警惕。同卡片同指标第二次出现可省略参考系。
推荐技能写法：斜杠命令 + 完成提示词，格式：
/skill-name [聚焦点：本次要做什么、范围、关键资产路径或任务 ID]
提示词要求：说明本次调用的具体聚焦点，包含关键资产路径或任务 ID，≤40 字，可直接复制执行。L5 全 pending"待执行"分支无治理技能可用时，写"（无治理技能；交开发团队按 [路径] 实施）"。
优先级标签（由 §3.2 内部优先级映射，"现在该做"节只用标签不用编号）：
| 内部码 | 用户标签 |
|---|---|
| P0 | 紧急 |
| P1 | 重要 |
| P2 | 缓 |
| P3 | 可略 |
| — | 待执行（特殊：治理就绪、等执行；只用于 L5 全 pending 分支） |
完成标志：可观测的结果，1 句话；若执行受阻（战略冲突、依赖循环）则追加"受阻时回 plan-next 重评"。多任务时每张卡管自己的完成标志，不在外层堆叠。
暂缓代价（选填）：
回答"不做这条会怎样"，让读者能判断"先做这个 vs 先做别的"。≤30 字。
- ✅ 好例：
Goal 1 验收无可视化途径，PM 无法判断应交项收尾时机 - ❌ 占位填充（禁止）：
待补充/详见任务/影响进度（同反模式 · 模糊措辞）
信息不足时省略此字段，不允许臆造。
上手门槛（选填）：
回答"接下来该谁做、要不要先补课"。≤30 字。指向具体文档时附路径。
- ✅ 好例：
需了解 Grafana 数据源配置；不熟可参考 docs/runbooks/grafana-setup.md - ❌ 占位填充（禁止）：
需相关知识/参考文档
信息不足时省略此字段，不允许臆造。
3.3.1 现在该做节输出禁用词
"现在该做"节，以下词汇一律禁止出现——包括编码本身及其中文对应词：
| 禁止使用 | 允许的替代写法 |
|---|---|
| L1、L2、L3、L4、L5；目标层、路线图层、需求层、设计层、任务层 | 直接说"战略目标"、"路线图"、"需求文档"、"设计文档"、"任务" |
| G1、资产缺失 | 描述具体缺什么："xxx.md 不存在" |
| G2、内容不全 | 描述具体缺什么内容："缺 X 字段 / X 节" |
| G3、真相漂移、完成漂移、追踪漂移 | 描述具体不一致："任务状态未反映代码进度" |
| G4、位置错位 | 描述具体问题："文件命名不符规范" |
| P0、P1、P2、P3；现在/下次/以后/可忽略(作优先级标注) | 使用 紧急 / 重要 / 缓 / 可略 |
| pending、in-progress、done、blocked（作用户输出原文） | 说"待开始"、"进行中"、"已完成"、"被阻塞" |
| Rules 层、Why 层、What 层、How 层、Is 层 | 说"规范文件"、"战略文档"、"计划文档"、"设计文档"、"代码实现" |
项目代号裸出：T\d+ / M\d+ / Goal \d+ / BL-\d+ / ADR-\d+ / commit hash 等内部 ID | 在头部摘要、「现在该做」及「也要留意」节中，首次出现必须附自然语言副标题：T51（覆盖率仪表盘） / M5（混合检索成熟里程碑）；同卡内后续出现可用裸代号；缺字典见 §3.7 fallback |
| MoSCoW 框架词：Must Have / Should Have / Could Have / Won't Have | 改用"必交项 / 应交项 / 可选项 / 暂不做" |
| 治理流程黑话：前置闸门 / 短路 / soft-blocked / 兄弟扫描 / 焦点节点 / all-pending 分支 / 子节点推算 | 用通俗描述："规范文件缺失，先建立"/"等开发者执行"/"同层其他节点扫描结果" |
裸阈值无参考系：≥70% / P95 ≤30s / 14 天连续窗口（只给数字不给参考系） | 改用三件套：[指标名（口语化解释）]：当前 X / 目标 Y / 参考系 Z（详见 §3.3 阈值标注） |
违反本表 = "现在该做"节输出不合格，须重写违规字段，不得保留。
3.4 用户输出结构
格式选择：单条建议可用散文替代下方卡片。以下结构化模板适用于 ≥2 条并列建议的场景。
# 下一步建议
> **现状**：[客观状态摘要，≤25 字。例：M5 必交项已清，应交项三项待启动]
> **核心矛盾**：[本期判断卡点，≤30 字。例：采纳率管道在线但样本未达 100，验收暂不可判]
---
## 现在该做
**1. [行动名称（含项目代号自然语言副标题）]** · `紧急 / 重要 / 缓 / 待执行`
> [TL;DR 卡片头：做什么 → 立刻可见的收益，≤30 字]
- 治理上下文：
- 战略目标：[目标自然语言名 + 一句话核心 KPI]
- 当前 KPI：[当前值 / 目标值 / 参考系；无数据写"数据缺失"]
- 路线图：[里程碑自然语言名 + 当前阶段]
- 当前位置：[卡口所在层 + 卡因，≤15 字]
- 推荐技能：`/skill-name [聚焦点 ≤40 字]`
- 依据：[文件路径或可观测信号 ≤20 字]
- 完成标志：[可观测结果 1 句话]
- [选填] 暂缓代价：[不做的影响 ≤30 字；信息不足省略，不允许臆造]
- [选填] 上手门槛：[前置知识 / 文档路径 ≤30 字；信息不足省略]
---
**2. [行动名称]** · `优先级标签`
...（格式同上，最多 3 条；多任务并行启动渲染为多张并列卡，详见 §3.1 多任务多卡渲染规则）
---
## 也要留意
<!-- 漂移巡检（步骤 2.2）+ 卫生巡检（步骤 2.3）条目汇聚于此，最多 5 条，按优先级截断 -->
**[漂移/卫生名称]** · `缓 / 可略`
[一句话：发现了什么问题]
- 依据：[文件路径或可观测信号]
- 推荐技能：`/skill-name [聚焦点]`
---
## 诊断依据（技术追溯）
<!-- 本节为内部追溯区：L1-L5、G1-G4、P0-P3 及状态码（pending/in-progress/done/blocked）在此处允许使用 -->
- **项目情况**：[一句话摘要]
- **资产清单**：[仅列有状态变化的资产]
**判定逻辑**：
| 层级 | 节点 | 状态 | 推断 |
|---|---|---|---|
| 战略目标 | [Goal 名] | [KPI 状态] | [继续下钻 / 跳过 / 路由] |
| 路线图 | [节点名] | [pending/in-progress/done/blocked] | [兄弟扫描结论 + 焦点节点 / 触发的规则] |
| 需求 | [需求名] | [状态] | [判定结果] |
| 设计 | [设计名] | [状态] | [判定结果] |
| 任务 | [任务名 / 集合] | [状态] | ["待执行"分支 / 路由下游 / 完成判定] |
- **漂移巡检结果**：[漂移条目列表；空时写"无"]
- **卫生巡检结果**：[卫生问题列表；空时写"无"]
- **字典缺失提示**（若有）：[未命中字典的项目代号列表，建议补 `docs/glossary.md`]
3.7 术语字典查表
目的：对项目代号自动注入自然语言副标题，让用户输出可独立判读，不让读者必须查内部 ID 字典才能理解。
字典源（按发现顺序）：
- 输入参数
glossary_path（若调用方提供） .ai-cortex/glossary.yamldocs/glossary.md- Fallback：读源制品 frontmatter
title:字段（如docs/tasks/T51.md的title:）；无 frontmatter 时取首个 H1 标题
字典 schema（YAML 形式）：
T51:
full_name: 覆盖率仪表盘任务
one_liner: 让 PM 实时看到覆盖率进度
M5:
full_name: 第 5 个里程碑「混合检索成熟」
Goal 1:
full_name: 需求澄清依赖知识库稳定跑通
kpi: 采纳率 ≥70% 连续 14 天
字段说明：
full_name（必填）：自然语言名称，用于注入副标题one_liner（选填）：一句话核心价值，可用于 TL;DR 卡片头辅助生成kpi（选填，仅战略目标）：核心 KPI 简述
输出层查表规则：
| 场景 | 渲染策略 |
|---|---|
| 项目代号首次出现，字典命中 | 注入 代号（full_name），例：T51（覆盖率仪表盘任务） |
| 同卡内后续出现 | 仅用裸代号 |
| 字典缺失对应条目 | Fallback 读源制品 frontmatter title:，取前 ≤12 字注入 |
| 字典 + Fallback 双重缺失 | 进诊断依据节标记"字典缺失：建议补 docs/glossary.md 加入 <代号>"，不在用户输出节展示该代号；改用通用描述（如"待执行的任务"） |
约束：
- 字典缺失不报错、不阻塞——退化输出仍可用
- 字典查表仅注入到"现在该做"和"也要留意"节；诊断依据节允许裸代号
- 字典源 YAML 畸形 → HALT 并提示用户修复（同 §0 规范解析行为）
反模式
关于职责边界：
- ❌ 调用任何下游技能（只读硬边界）
- ❌ 隐藏跳过原因（短路时必须明示）
- ❌ 混入下游执行细节（不写 ADR、不修代码、不整结构）
关于路由本身：
- ❌ 模糊措辞（"可能 / 或许 / 可以考虑"）
- ❌ 省略完成标志
- ❌ 一条路由混多个缺口类型
- ❌ 按缺口数量给优先级
- ❌ 树遍历跳层报告（L2 缺失时直接报 L3 路由）——违反"首缺口优先"
- ❌ 用 git 信号判"完成"——L2-L5 完成判定看
status字段；L1 完成必须叠加验收 KPI 检查 - ❌ 忽略显式
status:字段，只用子节点推算——显式优先 - ❌ 以
status = approved作为 L1 done 判据——approved=决策已批准≠验收已达成；混淆会跳过整棵 L1 子树 - ❌ 绕过 L1 直接报告中间层（M5/任务）状态——必须先回答"L1 验收 KPI 是否达成"，再下钻
- ❌ 治理上下文字段缺 L1 验收 KPI 当前值——违反"路由必须回到战略目标验收"约束
- ❌ L1 验收 KPI 数据源缺失时直接路由下游执行任务——首条路由应先建立 KPI 数据源
- ❌ L5 全 pending 时硬塞下游技能——任务已存在时无治理技能可用，应输出"待执行"卡片
- ❌ 有 blocked 节点时不考虑并行启动——blocked 是并行信号
- ❌ 多个 in-progress 未 blocked 时推荐继续并行扩展——应建议收敛
- ❌ 多目标合并路由但未在依据中注明各目标来源
- ❌ 路线图未分层时跳过
promote-roadmap-items直接评估下游 - ❌ 忽略
depends_on:字段强行建议并行——有依赖必须顺序
关于树遍历与扫描：
- ❌ 在主路由「现在该做」中对 done 节点报告缺口（卫生巡检对 done 节点的检查是例外，输出到「也要留意」）
- ❌ 同时报同一节点的多层缺口（违反深度优先）
- ❌ 引入 mode 枚举或配置字段（直接看物理信号）
- ❌ 承担清单维护职责（plan-next 只读，差异作 G3 输出诊断条目，不做修复）
关于内部术语泄漏：
- ❌ "现在该做"节出现编码：L1-L5、G1-G4、P0-P3 任一形式
- ❌ "现在该做"节出现编码中文对应词：资产缺失、内容不全、真相漂移、完成漂移、追踪漂移、位置错位、目标层、路线图层、需求层、设计层、任务层、Rules 层、Why 层、What 层、How 层、Is 层
- ❌ 优先级使用旧标签"现在/下次/以后/可忽略"或 P0-P3 编号（改用
紧急/重要/缓/可略） - ❌ status 值原文出现在"现在该做"节：pending/in-progress/done/blocked（改用：待开始/进行中/已完成/被阻塞）
- ❌ 诊断依据用层级编号作主语（允许括注追溯，不允许作主语）
- ❌ 示例标题写"L2→L3 推进"（用自然语言场景描述）
关于黑话与判断脚手架：
- ❌ 项目代号裸出（
T51/M5/Goal 1/BL-001/ADR-033等）首次出现无自然语言副标题 - ❌ MoSCoW 框架词在用户输出节出现（Must Have / Should Have / Could Have / Won't Have）
- ❌ 治理流程黑话出现在用户输出节（前置闸门、短路、soft-blocked、兄弟扫描、焦点节点、all-pending 分支、子节点推算）
- ❌ 阈值无参考系（裸
≥70%/P95 ≤30s/14 天连续窗口）—— 必须三件套：当前值 / 目标值 / 参考系 - ❌ 多任务用顿号 / 加号 / "并行启动" 合并到单卡主题（
T51 + T-SG5-002/T51、T52 并行）—— 多任务渲染多卡 - ❌ 单卡完成标志堆叠多任务的 KPI（
A 可访问 + B 可查 + C 可用）—— 每张卡管自己的完成标志 - ❌ 治理上下文嵌套括号超过 1 层（
目标X（验收: KPI A 当前 80%（达成）/ 目标 ≥70%（高线）））—— 拆多行短链 - ❌ 治理上下文写成单链超 60 字 ——必须改为多行短链每行 ≤25 字
- ❌ 暂缓代价 / 上手门槛字段填占位文字（"待补充" / "详见任务" / "影响进度" / "需相关知识"）—— 信息不足应省略
- ❌ TL;DR 卡片头与主题字段语义重复（"启动并行任务以推进里程碑"重述主题）—— 必须答"立刻可见的收益"
- ❌ 字典缺失代号硬塞用户输出节（应进诊断依据节标记，用户节用通用描述）
自检
扫：
- 缓存已加载或明示"no norms found"
- 资产 2 字段齐（路径 + 状态）
- 路线图是否分层已判定；未分层时已路由
promote-roadmap-items
诊：
- 战略目标已读取；无目标时已触发 L1 路由
- L1 验收标准 KPI 已解析；每个目标的 KPI 当前状态已判定（已达成 / 未达成 / 数据缺失）
- L1 status=approved 视同 in-progress，未跳过下钻
- KPI 数据源缺失时，首条路由是建立数据源，未直接路由下游
- 每个节点的 status 已按"显式优先 > 子节点推算"解析
- 每个层级的兄弟节点已全量扫描并分类（done / in-progress / blocked / pending）
- 并行决策规则已应用；建议（专注 / 并行 / 收敛 / 启动）已标注
- L3-L5 物理扫描完成（glob + 可选 parent: + 可选 manifest）
- L3→L4 / L4→L5 G3 链路检查已执行；深度优先（上层 G3 命中不继续报下层）
- "完成"判定仅依赖 status 字段，未引入 git 信号
- 漂移巡检（步骤 2.2）已执行；超阈值制品已列入漂移条目列表
- 卫生巡检（步骤 2.3）已执行；已完成未归档里程碑、ADR 状态问题、仓库结构问题均已扫描
荐：
- 每条建议包含：做什么、为什么、可观测完成标志（无论散文还是卡片）
- 格式选择正确：单条建议用散文；≥2 条并列建议用结构化卡片
- KPI / 阈值首次出现含三件套（当前值 / 目标值 / 参考系）；无参考时已标注"项目自定（无外部基准）"
- 深度优先（每目标只报树中首缺口）
- 并行建议已在文字中说明并行理由
- 漂移/卫生条目均在「也要留意」节，未挤占「现在该做」前两位
- （使用结构化卡片时） TL;DR 引用块 ≤30 字，不与主题重复
- （使用结构化卡片时） 治理上下文为多行短链（每行 ≤25 字），含 L1 验收 KPI 当前状态
- （使用结构化卡片时） 优先级标签正确映射（紧急 / 重要 / 缓 / 可略 / 待执行）
- （使用结构化卡片时） L5 全 pending 多任务（≥2 个独立可启动）渲染为多张并列卡，未合并
- （使用结构化卡片时） 暂缓代价 / 上手门槛字段信息不足时已省略，未填占位文字
输出：
- 头部摘要（现状/核心矛盾）≤字数上限：现状 ≤25 字，核心矛盾 ≤30 字；无项目代号裸出（与「现在该做」节规则一致）
- "现在该做"节无编码：L1-L5、G1-G4、P0-P3
- "现在该做"节无编码中文对应词：资产缺失、内容不全、真相漂移、完成漂移、追踪漂移、位置错位
- "现在该做"节无旧优先级标签：现在/下次/以后/可忽略；优先级统一为
紧急/重要/缓/可略 - "现在该做"节无英文状态码：pending、in-progress、done、blocked
- "现在该做"及「也要留意」节无项目代号裸出（
T\d+/M\d+/Goal \d+/BL-\d+/ADR-\d+）—— 首次出现均附自然语言副标题 - "现在该做"节无 MoSCoW 词（Must Have / Should Have / Could Have / Won't Have）
- "现在该做"节无治理流程黑话（前置闸门 / 短路 / soft-blocked / 兄弟扫描 / 焦点节点 / all-pending 分支 / 子节点推算）
- 字典缺失代号已进诊断依据节标记，未在用户输出节硬塞
- 诊断依据节判定逻辑用表格（4 列：层级 / 节点 / 状态 / 推断），未用陈述
- 只读已遵守
- 诊断依据注明每目标的遍历位置及 blocked 节点
示例
示例 1：战略半成品（正常路径）
场景：项目有 mission / vision；无 strategic-goals；roadmap 存在但无法追溯到战略目标。
输出（示例）：
下一步建议
现状：有使命愿景，战略目标文档缺失 核心矛盾：路线图节点存在但无目标可追溯，治理遍历无法开始
现在该做
1. 补充战略目标文档 · 重要
补全缺失的战略目标文件，让路线图节点有来源可追溯。
- 治理上下文：
- 战略目标：缺失（使命愿景已存在）
- 当前 KPI：数据缺失（战略目标未建立，无验收标准）
- 路线图：存在，但节点无目标可追溯
- 当前位置：战略目标缺失，遍历停止
- 推荐技能：
/design-strategic-goals 基于 mission.md 和 vision.md 生成 strategic-goals.md，包含可识别的目标项 - 依据：
docs/project-overview/strategic-goals.md缺失 - 完成标志：strategic-goals.md 写入并含可识别目标项；受阻时回 plan-next 重评
诊断依据
- 项目情况：有使命愿景但无战略目标，路线图对齐待建立
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|---|---|---|
| 战略目标 | strategic-goals.md | missing | L1 缺口，遍历停止；路由 design-strategic-goals |
| 路线图 | — | 未评估 | L1 就绪后重跑 |
- 漂移巡检结果：无
- 卫生巡检结果：无
示例 2：新项目起步（短路场景）
场景：新项目，docs/ARTIFACT_NORMS.md 不存在，specs/ 为空。
输出（示例）：
下一步建议
现状：新项目，文档规范文件缺失 核心矛盾：无统一规范，后续所有治理文档无标准可依，目标树遍历跳过
现在该做
1. 建立文档规范基础 · 紧急
先建立文档规范，后续所有治理文件有标准可依。
- 治理上下文：
- 战略目标：暂未可及（规范文件缺失导致提前停止）
- 当前 KPI：数据缺失（治理规范未建立）
- 路线图：暂未评估（规范文件就绪后重跑）
- 当前位置：规范文件缺失，目标树遍历跳过
- 推荐技能：
/define-docs-norms 基于项目结构生成 docs/ARTIFACT_NORMS.md - 依据：
docs/ARTIFACT_NORMS.md缺失，specs/为空 - 完成标志：ARTIFACT_NORMS.md 落盘后重跑 plan-next
诊断依据
- 项目情况：规范层缺位，目标树遍历跳过
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|---|---|---|
| 规范层 | ARTIFACT_NORMS.md | missing | 规范缺位触发提前停止，目标树遍历跳过 |
| 战略目标 | — | 未评估 | 规范就绪后重跑 plan-next |
- 漂移巡检结果：无
- 卫生巡检结果：无
示例 3：兄弟节点推进 + 并行决策
场景：目标 A，路线图节点 N1（in-progress）。N1 下有需求 R1（in-progress，子推算）和需求 R2（pending）。R1 下有设计 D1a（done）和 D1b（in-progress）。D1b 下任务尚未拆解。
遍历路径：N1 → R1（in-progress，子推算）→ 兄弟扫描：D1a done，D1b in-progress → 进入 D1b → 无任务（L5 缺口）→ 输出"任务待拆分"待执行卡片（任务拆分由 AgentFabric runtime 承接）。
并行判定：D1b 为唯一 in-progress 设计，R2 pending。建议：专注 D1b，完成后 R2 自动成为下一焦点。
输出（示例）：
下一步建议
现状：目标 A 进行中，设计 D1b 就绪待拆任务 核心矛盾：D1a 已完成，D1b 无任务，执行层无法推进
现在该做
1. 为设计 D1b 拆解可执行任务 · 缓
D1b 设计就绪，拆出任务后 D1b 可进入执行。
- 治理上下文：
- 战略目标：目标 A（进行中）
- 当前 KPI：数据缺失（目标 A 无量化验收标准）
- 路线图：路线图节点 N1（进行中）
- 当前位置：设计 D1b 就绪，任务层缺口
- 推荐技能：（无治理技能；任务拆分由 AgentFabric runtime 承接，按设计 D1b 与 D1a 同等粒度执行）
- 依据：D1b 设计文件存在，任务文件缺失；D1a 已完成触发推进
- 完成标志：D1b 任务列表创建且有至少一条任务记录
诊断依据
- 项目情况：目标 A 处于执行阶段，N1→R1→D1b，任务层缺口
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|---|---|---|
| 战略目标 | 目标 A | in-progress | 继续下钻 |
| 路线图 | N1 | in-progress | 专注（唯一 in-progress 节点） |
| 需求 | R1 | in-progress（子推算：D1b in-progress） | 继续下钻 |
| 设计 | D1a | done | D1a done 触发兄弟推进 |
| 设计 | D1b | in-progress | 无任务（G1），输出"任务待拆分"待执行卡片 |
- 漂移巡检结果：无
- 卫生巡检结果：无
示例 4：路线图未分层
场景：战略目标存在，路线图存在但节点无 Now/Next/Later 分层，仅为扁平列表。
输出（示例）：
下一步建议
现状：战略目标存在，路线图为扁平节点列表 核心矛盾：无 Now/Next/Later 分层，无法确定当前执行焦点
现在该做
1. 为路线图建立当期/下期/远期分层 · 重要
分层后可锁定当前焦点节点，下游层级才能继续评估。
- 治理上下文：
- 战略目标：存在
- 当前 KPI：数据缺失（路线图无分层前无法评估）
- 路线图：存在，但无 Now/Next/Later 分层
- 当前位置：路线图层，缺优先级分层
- 推荐技能：
/promote-roadmap-items 将 roadmap.md 中的节点按 Now/Next/Later 优先级分层 - 依据：
docs/requirements-planning/roadmap.md存在但无分层结构 - 完成标志：路线图含 Now/Next/Later 分层后重跑 plan-next
诊断依据
- 项目情况：路线图存在但未分层，遍历在 L2 停止
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|---|---|---|
| 战略目标 | strategic-goals.md | present | 继续下钻 |
| 路线图 | roadmap.md | 未分层（扁平列表） | 路线图未分层规则命中，路由 promote-roadmap-items，不评估下游 |
- 漂移巡检结果：无
- 卫生巡检结果：无
示例 5：blocked 触发并行
场景：目标 A，路线图节点 N1。N1 下需求 R1（blocked，等待外部依赖）和 R2（pending，与 R1 无 depends_on 依赖）。
并行判定：R1 blocked，R2 pending 且独立 → 并行：建议同时启动 R2。
输出（示例）：
下一步建议
现状：目标 A 进行中，N1 下 R1 被外部依赖阻塞 核心矛盾：等待 R1 解锁将浪费窗口期，R2 独立且可安全并行推进
现在该做
1. 启动需求 R2 的方案设计 · 缓
R1 阻塞期间并行推进 R2，避免等待浪费。
- 治理上下文：
- 战略目标：目标 A（进行中）
- 当前 KPI：数据缺失（目标 A 无量化验收标准）
- 路线图：路线图节点 N1（进行中）
- 当前位置：设计层，R1 被阻塞触发并行
- 推荐技能：（无治理技能；R2 设计工作流由 AgentFabric runtime 承接，R1 被阻塞期间并行推进）
- 依据：R1 被外部依赖阻塞；R2 无
depends_on依赖 - 完成标志：R2 设计文件创建；受阻时（R2 与 R1 存在隐含耦合）回 plan-next 重评
诊断依据
- 项目情况：目标 A，N1 下 R1 blocked，R2 pending
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|---|---|---|
| 战略目标 | 目标 A | in-progress | 继续下钻 |
| 路线图 | N1 | in-progress | 专注 |
| 需求 | R1 | blocked | 被外部依赖阻塞，触发并行决策 |
| 需求 | R2 | pending | 无 depends_on 依赖，可安全并行启动 |
- 被阻塞节点：R1（等待外部依赖，需人工介入解除）
- 漂移巡检结果：无
- 卫生巡检结果：无
示例 6：战略目标 status=approved 但验收未达成（最易误判）
场景：strategic-goals.md 中目标 G1 frontmatter status: approved，验收标准为「引用可见率 ≥ 80% 连续两个迭代」，无监控数据。M5 阶段（承载 G1 的里程碑）下 17 条任务全部 pending，任务已拆分完整、设计/ADR 完备。
关键判定：
- L1: G1
status=approved视同in-progress；验收 KPI「引用可见率」数据缺失 → 首条路由必须建立 KPI 数据源 - L5: 任务全 pending 触发"待执行"分支，第二条路由输出"待执行"卡片标记焦点任务
输出（示例）：
下一步建议
现状：G1 验收未达成，引用可见率无监控；M5 任务全部待启动 核心矛盾：KPI 数据源缺失，验收不可验证；任务治理就绪但等开发执行
现在该做
1. 建立 G1（需求澄清稳定跑通）验收 KPI 数据源 · 紧急
建立引用可见率监控，才能判断 G1 验收是否达线。
- 治理上下文：
- 战略目标：G1 需求澄清依赖知识库稳定跑通
- 当前 KPI：引用可见率（用户文档被召回占比）数据源缺失 / 目标 ≥80% / 项目自定（无外部基准）
- 路线图：M5（混合检索成熟里程碑，进行中）
- 当前位置：战略目标验收，KPI 数据源未建立
- 推荐技能：（无治理技能；citation 引用可见率埋点 + 监控查询路径设计由 AgentFabric runtime 承接，落入 docs/architecture/）
- 依据：
strategic-goals.md验收字段含 KPI 但无数据源指向 - 完成标志：引用可见率可在监控/查询接口取数；数据源指向写入 strategic-goals.md
2. 启动 T47（BM25 稀疏检索集成） · 待执行
任务治理就绪，等开发者执行；T47 是引用可见率提升的关键依赖。
- 治理上下文：
- 战略目标：G1 需求澄清依赖知识库稳定跑通
- 当前 KPI：引用可见率 数据源缺失 / 目标 ≥80%
- 路线图：M5（混合检索成熟里程碑，进行中）
- 当前位置：任务层，全部待启动（治理就绪，等开发执行）
- 推荐技能：（无治理技能；交开发团队按 m5/tasks.md T47 实施）
- 依据：M4 T31（QueryRouter）已完成；T47 待开始且无前置阻塞
- 完成标志：T47 验收通过（BM25 召回率较纯向量提升 ≥15%、混合检索 P95 ≤1.5s）；完成后回 plan-next 重评
诊断依据
- 项目情况：G1 status=approved（设计完成），验收未达成，KPI 数据源缺失；M5 进行中，任务全 pending
判定逻辑：
| 层级 | 节点 | 状态 | 推断 |
|---|---|---|---|
| 战略目标 | G1 | approved（视同 in-progress） | status=approved ≠ done；KPI 数据源缺失 → 首条路由建立数据源 |
| 路线图 | M5 | in-progress | 唯一焦点里程碑，继续下钻 |
| 需求 | M5 需求集 | in-progress | 设计/ADR 已就绪，下钻到任务层 |
| 设计 | ADR-033/034 | done | 无任务缺口 |
| 任务 | T47（共 17 项，all-pending） | all-pending | "待执行"分支，输出焦点任务卡片（标签：待执行） |
- 漂移巡检结果：无
- 卫生巡检结果：无