用途
gm-hop 是 lean 走查流程中的单个执行单位(hop)。它把书中(lean,AnEntrypoint/lean)的一条具名原则应用到某个代码表面(surface)上,并在一次执行内处理该原则管辖的所有范围内实例,然后命名下一个节点。它不是 Orchestrator(编排器),只负责一条“车道”,不做整个节点池的工作。
输入参数
调用参数为一个 JSON 对象:{"node":{"id":"<id>","label":"<Author - Title>","advocate":"<advocate spec>","links":[{"to":"<id>","guards":["<guard>"]}]},"surface":"<path>","session":"<SESSION_ID>","wave":"<wave>","depth":<n>,"rhetoric":""}。links 按 to 字段字典序排列。该负载是跳跃收到的唯一图数据,不加载 gm-graph.json;links 不带方向、位置或边类型。rhetoric、max_depth(默认 6,即该波次上限)和 wave(对应 .gm/pool/ledger-<wave>.txt)为可选,其中 wave 是写入账本行所必需的。缺少 node、surface 或 session 时判定为 NOT-APPLICABLE,不执行任何写入。
主要能力与使用方式
- 运行 node.label 所指的纪律(如 Meyer - Design by Contract)作用于 surface,并以 node.advocate 为规格;只有当某条 link 的全部 guard 在该表面上成立时,其 to 才可被提名,且提名必须在纪律运行之后。不得重命名节点 id。
- 用一段话论证 rhetoric 提出的开放问题(为空则论证该原则最弱的论断)。
- 列出可检验断言:每条为一句可核查的话并附对应测试;用 codesearch 检索该断言管辖的每个实例并打印引用行,缺失文本则丢弃。
- 若表面涉及原因、缺陷或修复的断言,先运行 ACH(gm-config/prose/ach.md):至少两个对立假设、基于 dispatch 证据的 C/I/N 矩阵、按 I 单元最少排序、用一次探测区分领先者与次位者;后续步骤只针对领先假设,被拒绝的假设不做编辑。
- 用一次精确匹配编辑收敛该编辑能闭合的内容(前提是文件不被其他写入者持有,用 git_status 带路径确认),并保留对应 dispatch id 进行实时见证;无实时见证的改动需回退。
- 每次 prd-add 前,先对 .gm/prd/ 做一次 codesearch 检索该发现的原因字面量(动词名或文件路径);命中且该行归本跳跃所有则追加见证,否则在回执中引用其 id 且不新增。否则以 <principle>-<SESSION_ID>-<n> 形式登记(使用完整 SESSION_ID,绝不用后缀)。id 已存在时 prd-add 会拒绝,除非 overwrite:true,因此被拒的 id 取下个 <n>;绝不对其他会话的行发送 overwrite。每新增一行,需退役或合并一条陈旧行。输出为顺序、排名或选择类结果的纪律(PERT、MoSCoW、Pugh、Wardley)不单独登记行,而是把该排序写成 blockedBy 边或目标行上合并的 acceptance_criteria,也不把计划登记为待处理行。
- 用一句话指出最大需求,然后从第 0 步中攻击该需求的可用 link 提名下一个节点;任意可用 link 均可提名,不限位置与历史。depth ≥ max_depth(默认 6)时 next: none(深度限制);否则 next 给出 link 的 to 与 depth+1,rhetoric 为 next_choice.why 原文(最多三句)。后续子负载由编排器根据私有图构建,并追加 launch 行、生成子会话。
- 最终动作向同一账本追加 done <session>,无论何种判定,均以 fs_write {"path":"<path>","content":"done <session>\n","append":true,"run_end":true} 形式;run_end 时间戳是运行结束标记。所有账本与新节点行都是追加写入,整文件写入共享日志会被拒绝。
- 在回执前关闭本跳跃的 Dream-RSI 周期:dispatch dream-replay-cycle 并记录其 dispatch id 和状态(replayed 或带原因的 deferred)到回执的 CYCLE 行。无见证改动或已验证行时 next: none 并说明原因。
节点输出
每次判定(包括 NOT-APPLICABLE)都必须写出固定结构文件 .gm/lean-walk/<NODE>.<SESSION>.json,按节点和所属会话命名,避免并行访问互相覆盖;字段包含 node、applied、changes、witness、prd_ids、unknown_ids、next_choice{to,why}、links_offered、link_taken、session、witness_dispatch_ids、verified_by、verified_dispatch_ids、findings[{prd_id,owner,disposition}]、inspector。links_offered 为负载中 node.links 各项的 to 原文;link_taken 为 next 中提名的 to 或 null,不得为第三种值。applied:true 仅在至少一处改动落地且 witness 指向自己持有的 dispatch 时成立;witness_dispatch_ids 列出见证引用的全部 dispatch id。
独立验证与约束
本跳跃不得见证自己的编辑:在设置 applied:true 前,需派发会话为 <session>-v1 的验证子代理,仅接收变更契约(文件、预期编辑、见证命令)并实时重跑见证;记录 verified_by 为 <session>-v1 及其 dispatch id。无验证通过则写 applied:false、verified_by:null。dispatch 需打上 lean_node 标记。若表面需要但 links_offered 中不存在的纪律,应作为新节点以一行 JSON 追加到 .gm/lean-walk/new-nodes.jsonl,而非丢弃;id 为书名大写短横线形式,已存在于 nodes[] 则改加入该节点;不得编辑 gm-graph.json。
适用场景与限制
适用于 lean 走查中按原则逐节点推进、需要可核查证据与回执的代码审查式工作流。限制:必须作为独立子代理运行并拥有自己的 SESSION_ID;编排器不内联执行跳跃工作;每个跳跃至多发起两个 git 动词(一次 git_status{paths}、一次 git_commit{paths});跳跃只提交不推送不拉取;上下文超限而终止的跳跃以精简方式重启而非恢复;受并发子代理上限拒绝的子代理应停放而非丢弃;.gm/lean-walk/ 为 gitignored 运行时状态,不提交不推送;节点文件需保持在 4 KB 以内,大数组移至单独文件。
交付回执
回执最多 120 词,包含 VERDICT(HOLDS | VIOLATED | NOT-APPLICABLE)、PRINCIPLE/SURFACE/WITNESS、CHANGED、ACH、ROWS 与 FINDINGS、EMITTED、CYCLE、NEED 及 next(含 depth 或 none 与原因)。回执必须指明已执行的见证(命令、抓取结果或 codesearch 输出),否则被拒绝。