gitnexus-work

gitnexus-work — 执行 gitnexus-plan

执行由 gitnexus-plan 生成的实施计划，将其作为一系列经过验证的原子提交交付。计划的第 11 节 （implementation_context 包）是主要的机器可读输入；各散文部分是它的理由说明。本技能会编辑代码——它是仅负责规划的 gitnexus-plan 的执行方对应物。

/gitnexus-work <plan path>        # execute this plan
/gitnexus-work                    # newest docs/plans/*gitnexus-plan*.md here
/gitnexus-work <small task text>  # direct mode, see Input triage

输入分诊

• 计划路径（或留空 → 当前仓库根目录下最新的 docs/plans/*gitnexus-plan*.md）：常规模式；继续进入第 1 阶段。Schema-2 计划具有规范化的仓库相对路径 docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-slug>.md generated_plan_path。只解析一个词法候选，然后调用 scripts/evidence-provenance.mjs read-plan --repo <root> --generated-plan <candidate>，并且只加载其锚定描述符回执中所包含的确切字节。要求回执的规范化仓库相对路径与文档的 generated_plan_path 逐字节相等； 拒绝外部、越界、作用域不同或不匹配的值。位于另一个目标仓库中的计划仍可通过显式路径传入。如果第 1 阶段的 预完成检查发现最新计划的每个 §7 步骤均已落地，则停止并询问，而不是重新执行它。
• 纯任务文本：简单且有界（1–2 个文件，无架构决策）→ 以同样的纪律直接实施：每次符号编辑前先 impact，最小改动，行为变化时补测试， 验证命令取自仓库自身的脚本（package.json / CI），每次提交前执行 detect_changes，并在依赖图谱的影响分析和最终验证之前执行共享的 Build-current/index-current 流程。任何更大的任务 → 建议先运行 /gitnexus-plan；如果用户拒绝，则尊重其选择。

第 1 阶段 — 加载并重新锚定计划

1. 解析目标仓库和规范化计划候选，然后严格按照 references/evidence-provenance.md 中的说明，调用本 skill 中锚定描述符的 scripts/evidence-provenance.mjs read-plan 命令。拒绝缺失、外部、逃逸、符号链接或作用域不同的路径。完整解码并读取回执中精确的 plan_bytes_base64；绝不直接读取或重新打开词法路径。它是决策产物，而不是脚本：作用域边界和 avoid 条目约束你；具体代码由你编写。在会话状态中保留回执的规范 generated_plan_path 和 plan_digest。绝不编辑计划正文。
2. 解析 §11 implementation_context 包：acceptance_criteria、evidence_provenance、primary_symbols、related_symbols、files_to_modify、execution_path、pdg_constraints、architectural_patterns、tests、verification_commands、risks、assumptions、open_questions、avoid。紧凑计划带有 mini-pack 子集 —— 缺失的可选字段为空，而非错误。evidence_provenance 是强制性的：缺失或 schema 1 表示遗留计划，而不是干净的树。在依赖它之前，要求 read-plan 回执的规范 generated_plan_path 与 evidence_provenance.generated_plan_path 逐字节完全相等。
3. 两层漂移检查 —— 始终重新计算。 即使当前 HEAD 与计划固定的 HEAD 相同，也要重新计算规范全局脏摘要和排序后的引用路径清单。阅读 references/evidence-provenance.md，然后使用计划的精确 generated_plan_path、每个引用的清单路径以及 schema 版本 2 调用本 skill 的 scripts/evidence-provenance.mjs。绝不在 shell 或文字中重建其字节。Schema 1 无法明确地重新计算，需要保守地重新锚定。包括对象类型以及 HEAD/index/worktree/untracked 层摘要，并对 staged、unstaged、untracked、deleted、renamed、mixed 和 absent 证据进行分类。严格遵守生成计划排除规则；不要排除所有计划。
4. 任一不匹配时重新锚定。 缺失或遗留的溯源信息、HEAD 不匹配或全局脏摘要不匹配，都需要在开始工作前进行保守的重新锚定：
   • 对比每个引用路径清单条目。更改的引用路径 —— 包括仅暂存、仅未暂存、已删除、两个重命名端点、混合暂存+未暂存以及消失的未跟踪路径 —— 在依赖之前要重新读取其引用范围。
   • 将当前整树脏集合与固定的全局摘要进行比较。新的未引用脏路径需要进行作用域评估：确定它们是否与计划、需求、测试或关键技术决策重叠；不要仅仅因为它们未被引用就默默忽略它们。
   • 不可读或无法分类的引用证据会阻塞每个依赖步骤，直到可以恢复、读取或与用户一起解决。绝不用捏造的摘要替代，也不要把缺失当作空文件。
   • 在会话状态中保留重新锚定结果；绝不修改计划正文。仅当协调使作用域、需求、关键 技术决策 (KTD) 或计划的实现接缝失效时才使用 Deepen。使这些决策仍然有效的普通字节漂移在本地重新验证。
5. 低成本地重新验证 assumptions（每一项都说明要检查什么）。失败的假设对依赖它的步骤而言是停止并重新规划的信号，而不是默默绕过去编码。
6. 注意 open_questions —— 如果某个问题阻塞了某一步骤，且答案会实质性改变工作，那么要在该步骤之前询问用户，而不是之后。
7. 预先完成检查。 如果此计划的提交已存在于分支上（之前的部分运行，或路由返回后的 Deepen 周期），验证哪些 §7 步骤已在 HEAD 落地：这些步骤被跳过并报告为预先完成，执行从第一个未落地步骤恢复。所有步骤均已落地 → 报告并停止。

阶段 2 — 环境

• 在默认分支上 → 根据计划 slug 创建一个以它命名的功能分支。 如果已经在某个功能分支上 → 只有在该分支对本计划有意义时（名称与计划 slug 匹配，或用户确认）才留在该分支；否则从当前位置以该 slug 名称创建分支。
• 如果计划文档尚未提交，现在就提交它 （docs(plans): add <slug> plan）——计划应随它所驱动的工作一起流转，这样最终评审 diff 中也会包含它。
• 在开始之前，确认该 pack 中的 verification_commands 在当前检出中确实可以运行（已安装依赖、构建产物存在），而不是在最后一步之后才确认。

构建当前状态 / 建立当前索引流程

这是由 gitnexus-work 拥有的唯一图新鲜度流程；它适用于计划模式和直接模式。在每次依赖图的 impact 查询之前，运行构建当前状态 / 建立当前索引流程。在最终图验证之前，再次运行同样的构建当前状态 / 建立当前索引流程。

1. 捕获当前 HEAD 和工作树的溯源信息。读取 gitnexus://repo/<name>/context，并使用其带类型的 index.commit 和 index.runner_identity 回执 —— 绝不要仅凭文字描述、 时间戳或路径来推断分析器身份。将 index.commit 与当前 HEAD 进行比较。 当前回执具有 schemaVersion: 4、已解析的运行时路径/版本、CLI 版本、被调用工件的路径/摘要、构建 类型/根/规范化/摘要，以及依赖运行时 清单/锁文件/规范化/包数量/工件数量/摘要。其 依赖规范化版本为 gitnexus-analyzer-dependency-runtime-v4。依赖运行时摘要 涵盖已解析的包元数据和完整可加载的包载荷， 包括 JavaScript、JSON、原生、Wasm 和解析器工件；schema-1、 schema-2 和 schema-3 回执属于旧版/过期（MCP 上下文将 它们标记为 runner_identity_schema_status: legacy-or-unknown）。要求 MCP index.incomplete_reasons: []。运行精确的候选 CLI 的 status --json 命令，并要求 index.runnerIdentityStatus: current、 index.incompleteReasons: []，以及顶层 status: up-to-date。 状态比较器检查每个语义字段，仅有意排除 诊断性的 invokedArtifact；因此，由 worker 写入的持久化回执和 CLI 的实时回执可能在该字段上不同，但不会因此变为 过期。缺失、格式错误、版本不同、语义不相等或 不完整的回执均属于未知/过期，而非匹配。
2. 影响关系的已提交和未提交编辑会在上一次成功的过程运行后 使新鲜度失效。这包括可能改变符号或边的已暂存、 未暂存、未跟踪、已删除或已重命名的分析器/源代码/配置更改。 步骤之间的任何此类编辑都需要在下次图查询之前进行 步骤间刷新，即使 HEAD 未移动也是如此。
3. 如果带类型的 runner 回执在分析器源代码检出中已过期或未知， 请使用经验证的包脚本构建当前本地源代码。在 本仓库中：cd gitnexus && npm run build。解析该包的 bin 目标，并运行该精确工件的 status --json 命令以捕获其 当前回执。源代码/构建时间戳是保守的重建 触发条件，而非工件为当前的证明。
4. 从目标仓库根目录调用该精确的新构建本地 CLI， 并启用 PDG 层。在本仓库中： node gitnexus/dist/cli/index.js analyze --index-only --pdg。 当持久化回执缺失、格式错误、 版本不同或不相等时，添加 --force，以便已是最新状态的快速路径不会 留下旧版/过期溯源信息。通常的项目运行器形式 node .gitnexus/run.cjs analyze，仅当其经证实的 runner 身份解析为同一新构建工件时才可接受。在解析/构建本地工件后， 不要回退到较旧的项目运行器、全局安装或包下载。
5. 重新读取索引上下文，重新运行精确被调用 CLI 的 status --json，并 证明刷新后的 index.commit 等于当前 HEAD、MCP index.incomplete_reasons 为空，且其完整的 index.runner_identity 等于 status 的 index.runnerIdentity（持久化 回执）。要求 status 的 index.runnerIdentityStatus: current、index.incompleteReasons 为空， 以及顶层 status: up-to-date；不要要求 与 current.runnerIdentity 原始相等，因为 invokedArtifact 是一个 诊断入口点，被有意排除在语义新鲜度之外。 记录本过程中建立索引的脏状态摘要，以便之后同 HEAD 的 未提交编辑可以使其失效。
6. 任何构建、刷新、元数据读取或身份验证失败都会阻止 依赖图的影响工作和最终完成。报告失败的命令和证据； 不要在较旧的图上继续。

阶段 3 — 执行实施序列

按顺序逐步执行计划 §7。对于每一步：

1. 编辑前重新评估影响。 在每次依赖图的 impact {target, direction: "upstream"} 查询之前，立即运行 Build-current/index-current 流程。然后逐一考虑每个直接（d=1）依赖方。HIGH 或 CRITICAL 风险 → 在继续之前向用户展示其影响范围（仓库强制要求 — 参见 AGENTS.md 中的 GitNexus 规则）。
2. 遵守约束。 pdg_constraints 条目说明了变更必须保持的顺序和依赖事实；avoid 条目是硬性禁止；architectural_patterns 指明了要模仿的形态（在自行发明之前先阅读示例位置）。
3. 最小化实现。 完成该步骤所需的最小变更，遵循周围代码的约定。
4. 根据计划中的场景进行测试。 每个 tests[] 场景（输入 → 操作 → 预期结果）都应在指定文件中成为真实的测试。如果该步骤的行为需要，补充计划遗漏的覆盖；绝不要为了让某个步骤通过而删除或削弱断言。证明新的回归测试具有区分能力：当失败模式较为隐蔽时，针对修复前的代码树运行一次（在修复之前编写测试，或暂存修复），观察其失败 — 一个无论修复与否都能通过的测试无法锁定任何行为。
5. 验证。 运行与步骤相关的 verification_commands（它们自带构建前置条件；按原样使用）。如果变更的任何部分从构建产物执行 — worker 入口点、随 dist 分发的 CLI、打包的资源 — 在每次验证运行之前重新构建该产物：针对过时构建产物的通过或失败都是噪声，而"修复不起作用"更多时候是"修复从未被加载"。
6. 原子提交。 在每次提交之前运行 detect_changes {scope: "staged"}，以确认只有预期的符号和流程受到影响（仓库强制要求）；然后每个步骤一次约定式提交。将 stage → detect_changes → commit 作为从仓库根目录开始的连续序列运行 — 在门禁和提交之间穿插其他工作是门禁被跳过的主要原因。出现意外受影响的流程 → 在提交前调查，而不是提交后。结果被标记为 partial（图查询失败）或 truncated（符号列表被截断）时同样会阻止提交：门禁没有看到所有变更的符号，因此应重新运行它，而不是将其视为干净通过。

影响关系的实施编辑或提交会使该流程先前的证明失效。下一步必须在其影响查询之前执行所需的步骤间刷新；最终验证在最后一次编辑后再次刷新。

各步骤可独立操作：任何提交之后，代码树都是一致的。如果某一步骤表明计划有误，停止该步骤，在 HEAD 上重新验证受影响的主张，然后要么适应（小的、范围内的偏差 — 记录在提交信息和最终总结中），要么转回 gitnexus-plan 的 Deepen 模式（结构性遗漏）— 当选择不明显时，向用户提出一句话的询问。

阶段 4 — 收尾

1. 在最后完整运行一遍 verification_commands 套件，即使每个步骤此前都已单独通过。
2. 逐项核对计划 §13（完成定义）与该包的 acceptance_criteria；任何未满足项要么现在就完成，要么明确报告为未满足 —— 绝不悄悄略过。
3. 验证最终知识图谱。 在最终图谱验证之前，于最后一次编辑后运行同样的 Build-current/index-current 流程，即使没有提交落地或 HEAD 仍等于最初的 pin 值。然后针对该已验证为最新的索引运行 detect_changes {scope: "all"}（或该仓库等效的最终图谱检查），并对每一个意外符号或流程作出说明。流程失败将阻断完成。
4. 报告：已完成的步骤、已产生的提交、与计划的偏差（及原因）、重新验证失败的假设、DoD 状态、最终索引提交与 runner 身份，以及任何推迟事项。测试失败需连同其输出一并报告，不得粉饰。

绝不

• 跳过阶段 3 的门禁：没有 impact 就不得编辑符号，没有 detect_changes 就不得提交。
• 将范围扩展到计划之外 —— §12 中推迟的后续事项仍保持推迟。
• 改动计划正文（在阶段 2 中逐字提交该文件不算改动）、削弱失败的测试，或将未经验证的工作呈现为已验证。

技能反馈（仅限 GitNexus 仓库）

如果本次运行暴露出本技能自身说明中的摩擦 —— 错误或缺失的指引、浪费的工具预算、某个阶段误入歧途 —— 且该仓库带有 eval/workflow_bench/，则向 eval/workflow_bench/learnings.jsonl 追加一行 JSON（若文件不存在则创建）： {"skill": "gitnexus-work", "date": "YYYY-MM-DD", "task": "<one line>", "friction": "<one line>", "suggestion": "<one line>"}。 绝不要从实时任务中编辑本技能文件本身：改进需通过离线候选循环（eval/workflow_bench/README.md § Prompt and skill evolution loop）进行，候选版本必须在配对基准上击败现有版本后，才能由人工合并。