gitnexus-plan

gitnexus-plan — 可直接实施的工程计划

为工程任务生成一份可直接实施的计划。GitNexus 是导航层（该看哪里），语句级 PDG 是约束层（什么在门控和供给该行为），而你原生的定向源码阅读是验证层（当前实际为真的事实）。输出是一份计划文档，外加一个紧凑、机器可读的实施上下文包，后续实施 Agent（gitnexus-work，或任何执行器）可消费它而无需重复调查。

/gitnexus-plan <task description>
/gitnexus-plan impact_depth:3 depth:deep <task description>   # knob overrides, see Configuration

本技能只做计划。它从不实施。 运行期间不要修改生产代码、测试或配置。它唯一写入的仓库文件是计划文档（保存在仓库之外的工作台账也可以）。唯一允许的其他状态变更是通过 analyze --index-only 刷新索引，它只写入 .gitnexus 索引存储。它不得构建分析器的 dist/ 输出，也不得改动源码、测试、配置或评估数据。过期的分析器来源信息作为一项按来源加权的限制予以披露，绝不在计划运行中修复。

硬性规则

• 台账优先。 在每次 GitNexus 调用和每次读取仓库文件之前，先检查上下文台账。绝不要重复已经回答过同一问题的查询，也不要重读未变更且已回答过同一问题的区间（允许的重复定义在 references/context-ledger.md 中；本技能自身的参考文件不受台账记账约束）。
• 每次图查询都回答一个有名字的计划问题。 在台账中记录该问题与结论。不得进行探索式翻找。
• 源码优先于图。 图用于导航；当前源码才是权威。先验证再断言（见第 4 阶段）。注释是最弱的证据——绝不强于可执行代码。
• 不得虚构。 绝不要编造符号、文件名、测试名、工具结果或 PDG 边。未知项归入 假设与未决问题。
• 不得范围蔓延。 任务未要求的相邻重构放入计划 §12，作为明确推迟的后续项，而不是放入拟议变更。
• 固定工作区证据，而不仅是 HEAD。 每份计划表单都携带 references/context-ledger.md 中定义的带版本全局脏摘要和排序后的引用路径清单。只能使用 scripts/evidence-provenance.mjs 和 references/evidence-provenance.md 中的可移植辅助程序与字节契约来生成它；绝不要重新实现该摘要。
• 只能通过辅助程序写入计划。 生成计划的路径是规范化的仓库相对路径 docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-slug>.md。在内存中或目标仓库之外的暂存区中组合完整的 UTF-8 文档，然后通过 stdin 将其传给辅助程序的 write-plan 命令。绝不要直接写入目标位置，也不要在安全写入器失败时退回到外部输出路径。
• 只能通过辅助程序读取现有计划。 Deepen 必须调用 scripts/evidence-provenance.mjs read-plan，从其中以描述符锚定的回执里解析出精确解码后的 plan_bytes_base64，并将该回执的规范 generated_plan_path 与 plan_digest 作为一个绑定保留。绝不要解析直接按词法路径的读取，也不要把一份计划的摘要套用到另一条路径上。
• 证据足够时就停止。 证据充分即结束探索；计划不会随着消耗的 token 增多而单调改进。

阶段 0 — 解析与分类

阅读 references/context-ledger.md，并以任务开启台账： 原始请求、解读后的目标、验收标准。对任务进行分类：

类别	姿态（深度 · 计划形式 · 工具调用预算 · 新鲜度）
Bug 修复（局部）	狭窄，1–2 个主要符号，impact_depth 1 · 紧凑 · ~15 · 接受
功能	默认旋钮 · 紧凑 · ~30 · 接受
重构 / 共享 API 变更	影响分析必需，impact_depth 3 · 完整 · ~45 · 严格
性能	默认 + 性能 PDG 模式（references/pdg-slice.md） · 完整 · ~45 · 严格
安全	默认 + 安全 PDG 模式 + explain 污点发现 · 完整 · ~45 · 严格
依赖升级 / 迁移	影响分析 + 兼容性重点；PDG 很少需要 · 紧凑 · ~20 · 接受
并发 / 事务	控制流 + 状态变更 PDG 重点 · 完整 · ~45 · 严格
测试改进 / 文档	最狭窄：通常不做影响分析或 PDG 遍历 · 紧凑 · ~10 · 接受
架构变更 / 探索	最宽泛：先做聚类 + 进程 · 完整 · 无上限 · 严格

类别姿态会覆盖 Configuration 基线；显式的 key:value 调用旋钮会同时覆盖两者。匹配多行的任务将其合并： 取最宽的深度，并取各重点区域的并集。

种子证据。 当已完成的调查已经提供了 经验证的发现——一份已完成的评审、一份带有 path:line 锚点和具名失败场景的分诊文档——就从它开启台账：将 来源文档引用为开篇台账条目，并直接针对 它们制定计划，而不是在它已经覆盖的基础上重新运行图阶梯。 重新推导证据已证明的内容，就是在违背 轮次经济规则的前提下消耗预算。阶段 4 仍会针对 Proposed Changes 将引用的任何内容，在固定的提交处进行源头验证——种子 替代的是探索，绝不是验证。

深度由用户决定，事先询问一次。 在交互式 会话中，当调用不带有显式深度信号（没有 depth:、 form: 或 freshness: 旋钮，且不是 Deepen 模式）时，在阶段 1 之前询问一个阻塞性 问题——这个计划应该深入到什么程度？

1. 快速 — depth:narrow form:compact freshness:accept。最快的实用 计划：1–2 个主要符号，最少的图工作，仅核心章节。
2. 标准 — 上述类别姿态，保持不变。除非分类另有 理由，否则推荐此项。
3. 深度 — depth:deep form:full freshness:strict。全部 13 个章节， impact_depth 3，读取聚类/进程，为核心函数提供 PDG 切片。

该答案会完全按照在调用中键入的方式设置旋钮； 显式旋钮优先，并跳过该问题。无头运行从不 询问——类别姿态保持不变地适用。事先询问 取代了在完成后提出深化已完成的计划：Deepen 模式（见下文）仍然是 强化现有计划文档的机制——后续会话、 评审发现、执行器回退——而不是默认的后续问题。

轮次经济是一项交付物。 计划的评判标准是每 token 的决策质量，而不是周全性表演（实测：一个两行 变更用了 63 轮的计划——GitNexus 仓库的 eval/workflow_bench/）。保持在类别的工具调用 预算之内；当预算耗尽而问题仍未解决时，将它们记录在 §12 中，而不是进一步挖掘——执行器反正是以低成本重新验证。

阶段 1 — 锚定与新鲜度

1. 确定目标仓库：如有疑问，使用 list_repos，否则使用覆盖工作目录的已索引仓库。当索引了多个仓库时，每次调用都显式传入 repo。
2. 在台账中记录仓库当前的 HEAD 提交——计划中的每一处行号引用都固定到该提交。
3. 确定并记录分析器运行器（本技能中每条 analyze 命令都会用到它）：当项目带有运行器时（此前的一次 analyze 将其放在了索引旁边），使用 node .gitnexus/run.cjs analyze …，否则使用 gitnexus analyze …（已安装的 CLI —— npm install -g gitnexus），再否则使用 npx gitnexus analyze …。记录其路径/版本及任何可用的源码/构建标识；不要根据时间戳臆造来源。
4. 读取 gitnexus://repo/{name}/context —— 代码库概览 + 过期检查。 新鲜度门禁。 基于过期图谱构建的计划会得出过期的爆炸半径结论——但重新索引是规划会话承担的最大固定成本，因此该门禁按类别定价：
   • 精简计划类别默认 freshness: accept：在当前图谱上规划，并将源码验证的权重调高——它们的计划很少引用图谱证据。仅当某条图谱结论变得关键时（例如拟议变更依赖于 d=1 的依赖项列表），才在计划中途升级为刷新，且仅在这种情况下。
   • 完整计划类别默认 freshness: strict，在其下：
   • 分析器来源检查——在任何刷新之前。 将已确定的运行器标识与索引元数据进行比较，并在分析器源码检出中与当前分析器源码进行比较。如果标识过期或未知，则不要构建输出，也不要让该图谱成为关键依据。在 index_refresh、计划头部和 §12 中记录一条 分析器来源过期——源码加权限制；改为依赖有针对性的源码阅读，或将执行交给 gitnexus-work，后者负责构建即最新门禁。
   • 索引过期 → 通过已确定的运行器运行 analyze --index-only（当任务类别将进入阶段 3 时追加 --pdg），并仅在运行器来源已知为最新时重新读取 context 资源。刷新预算，在此说明一次：每个规划会话在阶段 1 中至多一次 --index-only 刷新，外加阶段 3 中至多一次后续的 --pdg 升级（仅当阶段 1 的刷新缺少 --pdg 时）——Deepen 运行是它自己的会话。将每条命令、运行器标识和结果记录在台账的 index_refresh 中。
   • 刷新失败或不可行（对索引无写权限、仓库规模过大），或传入了 freshness: accept → 在过期图谱上继续，将源码验证的权重调高，并在计划头部和假设中说明过期情况及跳过的刷新。
   • 资源不可读但工具可用 → 仅凭工具继续，将新鲜度视为未知（将源码权重调高），并在计划中注明。
   • GitNexus 完全不可用 → 切换到 回退模式（见下文）。
5. 仅对于架构规模的任务，还要读取 gitnexus://repo/{name}/clusters 和 .../processes。

阶段 2 — 图导航阶梯

按此顺序，使用能回答当前账本问题的最窄操作。预算：账本中最多有 max_primary_symbols（5）个主符号和 max_related_symbols（20）个相关符号处于活跃状态。

1. query {search_query, task_context} — 定位任务相关的概念、执行流、模块和关联测试。
2. context {name} — 每个候选主符号的 360° 视图：调用者、被调用者、分类引用、过程。将其提升为主符号或丢弃。对于 ambiguous 结果（带排名的候选），通过一次使用 kind / file_path / uid 收窄的重试来回答——该重试属于允许的重复。
3. impact {target, direction} — 共享或高连通性符号的上游/下游影响范围（maxDepth = impact_depth；对枢纽符号先使用 summaryOnly: true，然后再深入——属于允许的重复）。记录 d=1 的条目——即直接（深度 1）依赖项——计划必须涵盖其中每一项。
4. trace {from, to} — 当任务取决于 A 如何到达 B 时，一次调用即可，而无需链式 context 跳转。
5. 语句级 PDG — 阶段 3，针对变更所聚焦的函数。
6. cypher — 最后手段，仅用于上述工具无法表达的精确图问题。先阅读 gitnexus://repo/{name}/schema；为每个查询设置锚点并加上 LIMIT。
7. detect_changes {scope} — 仅当针对现有未提交工作或分支工作进行规划时使用。

不要默认运行每个工具。一个本地测试修复可能在步骤 2 就结束阶梯。

阶段 3 — 语句级 PDG 切片

对于与变更最核心相关的 1–3 个函数，构建一个有界的 PDG 上下文切片。阅读 references/pdg-slice.md 并遵循它——它规定了工具调用、纳入标准、深度边界、切片 schema、安全与性能模式，以及无 PDG 层时的回退方案。

阶段 4 — 有针对性的源码验证

GitNexus 指出了去哪里看；现在确认那里有什么。使用普通的文件读取（精确行范围，除非确实需要，否则不要读取整个文件）：

• 读取计划将引用的每个源码范围：签名、分支条件、状态变更、错误路径、会改变行为的附近注释。紧凑的计划引用更少——验证它们所引用的内容，不要为了有更多内容可验证而扩大引用集合。
• 读取 GitNexus 与主符号关联的测试；绝不要在未定位到测试的情况下声称某个测试存在。
• 验证计划将指定的构建/测试命令确实存在（package.json scripts / CI workflows），并优先使用带有其前置条件（pre-hooks）的脚本形式，而不是直接调用底层二进制文件。
• 检查约束该变更的仓库约定（AGENTS.md、GUARDRAILS.md、lint/build config）——仅限变更所触及的部分。
• 在过程中将每个账本符号标记为 source_verified: true。在 Proposed Changes 中命名的符号必须经过源码验证。
• 当图与源码不一致时：信任源码，在账本和计划中记录该差异，建议重新索引。绝不要将过时的图数据作为事实呈现。
• 在撰写之前，立即按照 references/evidence-provenance.md 中的确切规定调用 scripts/evidence-provenance.mjs，重新计算带版本的 evidence_provenance 快照：包括覆盖所有脏路径的规范全局脏摘要，以及每个被引用路径的排序清单，包括对象类型和 HEAD/index/worktree/untracked 层摘要。重新读取规划期间发生变化的任何引用。仅排除生成的计划路径。

证据层级，从最强开始：当前源码与配置 → 当前测试与可执行行为 → 编译器/构建/lint 输出 → GitNexus 图与 PDG → 文档与注释。

阶段 5 — 编写计划

1. 阅读 references/plan-template.md，并根据台账填写该类别的表单 —— 精简版 （核心章节，不含包体 ≤80 行）或完整版（全部 13 个章节）—— 用模板的四个类别标注各项断言 —— [verified]、[graph]、[inferred]、[assumed] —— 并将待解决问题 归入 §12。
2. 按照 references/context-pack.md 构建实现上下文包 （即计划的第 11 节），在精简版和完整版中均须包含强制的 evidence_provenance。
3. 将 generated_plan_path 设为 docs/plans/YYYY-MM-DD-gitnexus-plan-<slug>.md，位于被规划仓库的根目录下 （即阶段 1 的目标仓库，不一定是 cwd）；使用 3–5 个单词的 kebab-case slug，并在文档内使用仓库相对路径。 编写完整文档时不要创建该目标位置，然后将文档的精确 UTF-8 字节通过管道传给 scripts/evidence-provenance.mjs write-plan，具体 如 references/evidence-provenance.md 中所规定。该辅助程序会安全地 创建缺失的父目录。初始规划不得传入 --replace。安全写入失败会阻止计划发布：应报告该失败，并且 不要直接写入、选择外部目标位置，或弱化 仓库相对来源契约。快照和写入命令会应用 相同的严格生成计划文件名/日期校验器；在任一调用中都不要替换为 源文件、.git 或任意的 docs/plans/ 路径。
4. 在聊天中呈现：目标、拟议变更摘要、实现 顺序、主要风险、待解决问题以及计划文件路径。不要将 整个文档粘贴到聊天中。

深化模式

/gitnexus-plan deepen <plan-path> 会就地强化现有计划，而不是创建新计划：

1. 解析目标仓库以及规范化后的仓库相对计划候选路径，然后使用 scripts/evidence-provenance.mjs read-plan --repo <root> --generated-plan <candidate> 加载它，具体方式与 references/evidence-provenance.md 中的规定完全一致。拒绝缺失、外部、逃逸、 符号链接或作用域不同的路径。仅解码并解析回执中确切的 plan_bytes_base64；在整个 Deepen 会话期间，保持其规范 generated_plan_path 和 plan_digest 不变。
2. 完整重新运行 Phase 1 —— 分析器来源检查与新鲜度门禁（一次 Deepen 运行本身就是一次独立会话，拥有自己的刷新预算）。
3. 在重新固定之前先重新锚定。 重新计算计划的全局 dirty digest 和引用路径清单，并将其旧 HEAD pin 与当前 HEAD 进行比较。已更改、重命名、删除、混合或新近缺失的引用路径，其范围会被重新读取 —— 或者该声明会被降级 —— 这一切都发生在 pin 和 来源快照移动 之前。只移动提交 pin 会悄悄把 dirty 或 stale 声明洗白为已验证。
4. 升级为 depth: deep（impact_depth 3，读取 clusters/processes）， 除非调用显式覆盖这些旋钮。
5. 从计划的 §11 pack 初始化 ledger，然后重新验证：每个 [graph]/[inferred] 声明都会进行针对性处理以迈向 [verified]； 每个 [assumed] 声明都会被解决，或连同其理由一起保留； 直接（d=1）依赖核算会依据刷新后的图重新检查； 当该层存在时，会为中心函数构建或扩展 PDG slices。
6. 协调执行状态。 如果 gitnexus-work 已经为该计划落地了提交 （执行中途回退），则将 HEAD 中存在的 §7 步骤标记为已完成，并重新排列其余步骤 —— 重写后的计划必须能够从头执行，而无需重做已落地的步骤。
7. 强化更深层遍历显示为薄弱的部分 —— 测试场景、风险、 Definition of Done —— 并将声明标签升级贯穿到正文中。
8. 通过 scripts/evidence-provenance.mjs write-plan --replace --expected-plan-path <retained-read-plan-path> --expected-plan-digest <retained-read-plan-digest> 重写 同一个规范文件：相同的 13 个章节， 上下文包保持同步，证据头更新。--replace 保留给 Deepen 模式， 并且两个 expected 值都必须来自同一个 read-plan 回执；任何 digest/path 不匹配都会阻止发布。保留成功回执中的 prior_plan_backup_git_path；它指向被替换计划的、已验证的 Git 管理备份。在聊天中总结差异：升级的声明、重新验证失败的声明、变更的章节，以及该备份路径。

配置

基线默认值——Phase 0 类别姿态会覆盖它们，而任务文本之前的行内 key:value 标记会同时覆盖两者（仓库没有 skill-config 文件机制； 调用参数就是该机制）：

选项	默认值	含义
depth	按类别	narrow = impact_depth 1，仅当一个函数明显处于中心位置时才使用 PDG；default = 此表；deep = impact_depth 3 + 读取 clusters/processes
form	按类别	compact（核心章节 + mini-pack，不含 pack 时 ≤80 行——参见 references/plan-template.md）或 full（全部 13 个章节）
impact_depth	2	impact 的 maxDepth
pdg_data_depth	2	PDG 切片中的数据依赖跳数
pdg_control_depth	2	PDG 切片中的控制依赖跳数
max_primary_symbols	5	Ledger 预算（活跃符号；丢弃项不计入）
max_related_symbols	20	Ledger 预算（活跃符号；丢弃项不计入）
max_snippet_lines	30	计划中引用的最长源代码摘录
freshness	按类别	strict（完整计划类别） = 在依赖图之前，使用 analyze --index-only [--pdg] 刷新过期索引（以及缺失的 PDG 层）；accept（紧凑类别） = 在当前图上制定计划，以源代码为权重并加以标注，仅在某个图断言成为关键依据时才刷新

回退模式（GitNexus 或 PDG 不可用）

1. 首先在聊天和计划中说明这一点。
2. 使用针对性的仓库探索（grep/glob/读取）来近似推断调用方、依赖关系、执行流程、状态变更及相关测试。
3. 在计划中将每一项此类发现标注为源自源码——绝不要将其表述为源自图，也绝不要编造语句级边。
4. 当这样做能实质性提升置信度时，通过解析后的运行器——node .gitnexus/run.cjs、已安装的 gitnexus 或 npx gitnexus——推荐 analyze --index-only（对于 PDG 层可加上 --pdg）。

技能反馈

如果本次运行暴露出指令中的摩擦点，请在最终回复中包含简明的反馈。反馈仅在聊天中进行：不要附加评估学习内容、编辑基准数据，也不要在实时规划任务期间修改本技能。