Hopbuild

---
name: hopbuild
description: >
  由 /hop 分派调用（用户要把自然语言 skill 翻译成 HopSpec 时）；用户不直接调。
  把一个自然语言 skill 翻译成结构化的 HopSpec 规约（hopskill），
  执行纪律由 HopJIT 引擎结构化强制。
  Trigger: "把 skill 转成 spec", "生成 hopskill", "skill 转 hopspec",
  "translate skill to hopspec", "hopskill 构建", "/hopbuild".
user-invocable: false
---

%% @trace
	id: hopbuild-skill
	type: intent
	last_sync: 2026-10-01T15:45+0800
	note: hopbuild v1 NL skill 形态（2026-08-25 作者定"把 /hopbuild 改成一个 NL skill"——自举形态退役:spec.md/expand-node.md 迁 docs/obsolete/hopbuild/,流程从引擎强制退回散文纪律,本文自足承载全流程;与 hopbuild2〔hopspec skill 形态,引擎强制〕构成同任务双形态对照,亦可作 hopbuild2 的翻译输入样本。2026-09-05 作者三拍定分工:本文=流程+宪法+核心常用知识+贯穿示例（通读自足,标准翻译零跳转）,高级不常用知识（生成模板全集/边角情形/语言面细则）归 hopbuild-primer.md 按需查阅。设计权威 docs/design/hopbuild.md ^anc-build-bootstrap（NL 回归条）+ ^anc-build-first-principles（宪法权威）+ ^anc-build-layout（分工契约）。
%%

# hopbuild — 自然语言 skill 翻译为 HopSpec 规约

**做什么**：把一个自然语言 skill（散文 SKILL.md）翻译成合规的 HopSpec 规约（hopskill）——四类纪律落点结构化落实（遍历不漏/核验不跳/提交把关/真人研判），逐关检查修正，经作者终审后交付。

**HopSpec 是什么（翻译的目标语言）**：把任务写成**编号步骤树**的规约语言，由 HopJIT 引擎逐步驱动执行。步骤按编号嵌套成树（`3.` 是 `3.1.` 的容器），每步一个类型——`[reason]` 推理分析 / `[act]` 干活（探索性、可重做）/ `[check]` 判定产出合格与否（不过就打回带反馈重跑）/ `[commit]` 不可逆动作 / `[ask]`、`[confirm]` 停下来问真人 / `[loop]`、`[branch]` 循环与分支；变量经 `- ←`（取）与 `+ →`（放）在步骤间流动。执行时引擎每次只调 LLM 执行一个叶子步骤，顺序、遍历、把关、重试全由引擎结构化强制——所以你翻出来的**不是文档，是程序**：原文里靠执行者自觉的纪律句，翻译后变成引擎跳不过的结构。完整语言形状（头部契约/类型系统/失败与重试语义）见 primer「HopSpec 全局知识」节。

**什么时候用**：你已有一个靠散文纪律运行的 skill，想让引擎强制它的关键纪律时。

**与 hopbuild2 的关系**：本 skill 是散文纪律形态（流程靠执行者逐段照做）；hopbuild2 是引擎强制形态（同一任务写成 HopSpec 由 HopJIT 驱动）。要引擎强制版说 "hopbuild2"。

**知识附件**：同目录 `hopbuild-primer.md` 装翻译判据与语言知识——附属文件二分判据、step 类型选型、四类纪律句怎么翻、hop_python 小语言、高频验证规则全在里面。翻译中拿不准的写法先查它对应节，不凭记忆写。

## 宪法级原则（七条，翻译全程约束——违反 = 翻译错误，不是风格问题）

> 权威在设计 docs/design/hopbuild.md「首要原则」章，本节是投影；冲突以设计为准。

**0. 内容忠实**——不能丢失或篡改原始 skill 的**意图和知识**：

- **知识完备性**：原文的判据、规则、模板一份不丢——进步骤、进 Constraints 或进知识文档随包，总之要在产物里。落点按作用范围分两层：**章节性知识随节点展开**（只在某几步用的判据抽成 knowledge 章节、在消费步 doc-ref 引用，到步才注入，不挤占全局注意力）；**全局性知识作为 spec 的全局供给**（全程红线上提 Constraints、全局方法论走 spec 级 doc-ref——只挂某一步等于其余步骤失守）；
- **流程忠实性**：原文承诺的动作、门禁、依赖一个不许蒸发，不擅自增删业务步骤；
- 粒度可以粗，但语义必须全；
- 原文本来就没写的判据或阈值，缺了不算你的翻译缺陷。正确做法：先按最合理的理解填一个暂定值，把"这里原文没给、我暂定了什么、为什么"记进**研判点台账**（翻译全程随手追加的一个清单文件，专门装"我拿不准、等作者拍板"的事项，终审时随 spec 一并呈上——下文各步说"记台账"指的都是它。一事一条，每条写清三样：原文哪里、拿不准什么、我暂定怎么处置及理由——作者终审时不必回头翻原文就能逐条拍板。研判点是"原文压根没写、翻译需要才逼出来"的（重试次数、超时值这类），"原文哪里"一栏写"原文通篇未给"，并说明这个值为什么非填不可），最后由作者终审时拍板——不要因为原文缺这个就卡住不翻，也不要在检查关把它当错误打回。

**1. 明确易懂**——产物的行文、布局要说人话，**人和 LLM 都一遍读懂**：

- 步骤说明、变量说明、判据都用完整的话写清楚——不用缩略语，不用只有写的人自己才懂的简称和代号，不用压缩断句的文言腔。判断标准：没跟过翻译过程的读者一遍能读懂；
- **布局方便阅读**：分立的事项分条列，不挤成一坨长段；一个段落只装一个主题，判据、清单、前提逐条一行；
- 结构一眼能讲出"为什么这样拆"——讲不出的嵌套，不如留任务描述待下层展开；
- **关键行为必须用"必须"等强化语气确保**：门禁、禁令、红线句翻译时保留原文强度——"必须/不得/禁止"弱化成"建议/尽量"就是篡改语义（执行 LLM 对弱语气的服从不稳定）。

**2. 分离范式**——`subtask{ act（探索）→ check（核验）→ retry（不过带反馈整组重跑）→ check final（验收）→ commit（提交）}`，确保探索与提交分离：

- **act 探索工作在 work_zone 内实施**——试错段可逆，中间产物全入涂鸦区，不碰正式位置；
- 核验不过就 retry 重跑，直到验收放行；
- 不可逆动作永远在把关之后。

**3. 渐进展开**——一次不用拆得过细：

- **每次构建，在上一次基础上把主要问题点的结构拆出来即可**——首版立顺序骨架，后续轮次对着上一版的问题点定向拆，不整树重来；
- **用好 `[act free]` / `[subtask free]`**——拆不清的段落以自由步/到步展开诚实落定，是合法形态不是欠账，比硬拆错强；
- 单层量级受控。

**4. 渐进输出**——尽量不要整篇整篇地输入输出：

- 产物文件落 work_zone 后，后续修订用 edit_file 局部精确替换，改点不重写全文——整文重写等于改三处赌全文不漂移；
- 调整 spec 步骤树用树编辑工具（insert_node/replace_node/replace_children）——按步骤号落位、替换、换 children，编号机械重刷不手工改号；
- 大产物分段落盘，不经变量通道整篇搬运。

**5. 逐步优化**——复杂循环、并行化在逐步优化时再考虑，**"循环不漏"不要求一次做到**：

- 循环形态的识别与精化、嵌套遍历拆内层、互不依赖段落并行化，全归首版骨架跑通后的优化步骤；
- 首版把重复语义如实落住即可——loop 或"生成+核验"闭环任一形态都行，串行跑对先于并发提效。

**6. 工具核验**——交付的 hopspec 必须通过两道工具检查，缺一不算交付完成：

- **validate**：静态文法零 error——管"写得合法"；
- **deep-validate**：运行期假设体检，风险报告随交付呈用户——管"跑得起来"。

## 一个贯穿示例（先看产物长什么样，再读七步）

原始 skill（散文纪律，节选）：

```markdown
# 周报生成
读取本周的工单记录（tickets.csv），逐条分类整理。
必须覆盖全部工单，一条不许漏。
写完后自查：数字与原始记录一致、每类都有小结。
确认无误后把周报保存为 report.md 并发送给主管。
详细的分类规则见 references/rules.md。
```

翻译产物（HopSpec，对照看四类纪律句都落在哪）：

```markdown
# Spec: 周报生成
Goal: 从本周工单记录生成分类周报,核对无误后交付主管

Inputs:
- tickets_path % line  # 工单记录 CSV 路径

Outputs:
- weekly_report % markdown  # 分类周报

Tools:
- send_report(content) -> sent % line  # 发送周报给主管（外部发送服务,对齐门盘点定稿）
  - content % text  # 要发送的周报全文

## Steps
1. [act] 读入工单记录
  - ← tickets_path
  + → tickets % [yaml]  # 工单列表,每条含类别字段
  > 纯机械读取:
  > ```hop_python
  > tickets = parse_json(read(path: tickets_path))
  > ```

2. [loop for-each t in tickets, collect item into items] 逐条分类整理
  + → items % [yaml]  # 全部分类结果（引擎驱动游标,"一条不许漏"由结构保证）
  2.1. [reason] 给一条工单分类并写摘要
    - ← t
    + → item % yaml  # 本条的类别与摘要
    > 分类规则按注入判据执行: [[references/rules#分类规则]]

3. [subtask retry=2] 成文并自查
  + → weekly_report % markdown
  3.1. [act free] 按类汇总成周报草稿（草稿写 work_zone,修订用 edit_file 改点）
    - ← items
    + → weekly_report % markdown
  3.2. [check final] 自查:数字与原始记录一致、每类都有小结
    - ← weekly_report, items
    + → ok % bool  # 判定
    + → note % text  # 检查不过时写清具体缺了什么——引擎重跑这一组时会把它注入给 3.1,照着定向修

4. [confirm require_human] 确认周报可发送
  - ← weekly_report
  + → approved % bool

5. [commit] 保存并发送
  - ← weekly_report, approved
  + → sent % line
  > 不可逆动作（前序 confirm 已放行）。命令序列写规约时已完全确定,执行时照跑即可,不需要任何现场判断:
  > ```hop_python
  > written = write(path: "report.md", content: weekly_report)
  > sent = send_report(content: weekly_report)
  > ```
```

对照读宪法怎么兑现的：原文"必须覆盖全部工单"→ loop for-each 结构保证（不靠执行者记性）；"自查"→ check final 引擎强制、不过带 note 重跑（分离范式）；"确认后保存并发送"→ confirm 闸 + commit 隔离，闸后动作没蒸发；"分类规则见 references/rules.md"→ 判据留原文件 doc-ref 按需注入（粒度粗但指针闭合，rules.md 随包交付）；send_report 是外部服务 → 对齐门盘进 Tools 段（第 3 步）。**这份示例只演形态，各形态的判定细则与更多模板都在 primer——渐进展开时按节查它，不凭记忆写。**

## 参数

| 参数               | 类型   | 说明                                                         |
| ---------------- | ---- | ---------------------------------------------------------- |
| input_skill_path | line | 待翻译的自然语言 skill 文件路径;为空则列出 `.claude/skills/` 下候选供选 |

已给且存在时直接采用，不必强问。

## 流程（七步，顺序执行）

### 第 1 步：确认翻译对象

确认 input_skill_path 指向真实存在的自然语言 skill 文件。路径缺席或不存在时，列出候选（跳过已有对应 spec.md 的）请用户选一个。

### 第 2 步：读原文、落副本、登记附属文件

完整读入 skill 原文。在工作目录写一份 `source.md` 纯副本——逐字原文，不加任何注记。它是终审对读与日后审计的物理基准，交付时随 spec 同目录分发。

原文是多文件目录形态时（本体只做路由、细节住 references/、scripts/ 附属文件里——成熟 skill 的常见写法），**列出附属文件清单并给每个被本体引用的文件定性**：流程性引用（装执行序列/退出门禁/确认闸，错过即纪律失守）现在就读进来供第 4 步消费；参考性引用（数据表/故障库/原始 YAML）登记路径按需取用。**二分判据细则查 primer「附属文件二分」节**（混合文件按最严内容处置/方法论类先立任务面/未引用附属呈人裁/零星门禁短句并拎法）；哪个文件拿不准归哪类，就把文件名和疑问记进研判点台账，先按更严的一类处置继续翻。

### 第 3 步：对齐头部契约（必须问人，意见不清空不往下走）

从原文抽头部契约并**呈给用户核查**，有修订意见就改了再呈，直到用户确认无误：

- **goal**：一句话说清产出什么；
- **inputs**：只收任务的业务输入（原文需要外部提供的数据，一个不漏、不添；执行设施不是业务输入）。**路径类输入按 workspace 相对形态收**——引擎沙箱拒绝文件工具吃 workspace 外的绝对路径（落在 workspace 内的绝对路径可用，但外部目录才是这类输入的常见情形），Inputs 若声明"某某目录的绝对路径"而该目录不在 workspace 内，产物真跑时第一步读文件就会被拒（deep-validate 三轮反复抓到的最高频部署缺口）。原文要求用户给外部目录的，正确形态是：输入说明写明"相对 workspace 的路径"，并在部署前提清单里写清"部署时把数据目录挂进 workspace 或以 workspace 为锚"；确实必须收绝对路径的（如系统固定位置），读写走 subprocess.run 命令通道（cat/cp，进白名单）不走内置文件工具；
- **outputs**：只放原文承诺的交付物（中间产物不进）；
- **constraints**：翻原文的"必须/不可"条款；
- **tools_available**：盘点产物能调什么——只登记真正的外部服务（搜索/发送/专有 API）。三类"假工具"不进清单：文件读写（hop_python 内置函数）、并行发射 agent（parallel 结构）、问人交互（ask/confirm 步骤）。拿不准的标"待确认"请用户在这一步裁定。**对齐定稿的工具面翻译成产物 spec 文件头的 Tools 段**——每工具一条签名行加逐参数子条目（`- 参数名: 类型  # 说明`，说明写到杜绝望词生义），复杂语义放 `>` 扩展行；引擎 init 会对环境注册面对账。

对齐门管方向。**此后进入构建循环，循环内不再问人**——能从已对齐契约与原文推演的直接定，实质性新增决策点记入研判点台账，随终审一并呈裁。

### 第 4 步：翻译步骤树（核心工作，逐段渐进）

把原文执行流程翻成 HopSpec Steps，按宪法 3"渐进展开"作业：**先打 HopSop 草稿**（纯 Markdown 大纲，只写控制流骨架——数字编号+`[subtask]`/`[loop]`/`[branch]`+`[case]` 容器行，细节后升格；记法细则查 primer「HopSop 流程草稿记法」节），再逐节点升格成 HopSpec 步骤——一次只展开一个节点，不一口产完整 spec。每个节点问四个问题（按序，先中先用）：

1. **是顺序吗**——段落有明确先后（含"做 X 并核验，不合格重做"的事务形态）→ 拆成顺序步骤；
2. **是分支吗**——原文存在互斥的多条路径（如果…否则…/方式一方式二/多种模式）就是分支，条件现不现成不是门槛：有现成变量直接用；输入判空可判的用判空；要人选的前置一个 ask 收 enum 再分流；
3. **是循环吗**——重复的模式都是循环：一批同类条目逐条处理（含编号写死的静态判据清单）落 loop for-each；做多轮直到条件满足落 loop max=N+check+break；
4. **是原子步骤吗**——一步一动作、描述一两句装得下：按动词认领类型（分析→reason、取放→act、发送/写盘→commit、判定→check、问人→ask/confirm）。纯机械动作写 hop_python body 让引擎直执零 LLM；写不出确定签名的落 [act free]；四问全不中的以自然语言步骤诚实落定（未尽原子——合法交付档，不硬拆）。**"纯机械"与"写不出签名"之间还有一个中间档,漏判它是系统性缺陷来源（hopissues/0088 实撞:SDD 四阶段 workflow 追踪出 19 个字段断裂点,95% 本质是确定性操作却被误落 act free）——半确定性操作**：字段本身是确定的（比如"读 _session.yaml 取 content_type 和 prd_files"——要取哪些字段客观存在）,只是原文以散文形式散落、没给字段清单。这类操作**不许直接落 act free**,正确做法分两步:①翻译时先把散落的字段提炼成明确清单;②按清单写成 act 带 hop_python body 机械组装（读文件→parse→按清单取字段,全是确定性代码）。**确实需要落 act free 的（比如取哪些字段要看现场判断）,instruction 里必须显式列出下游要消费的全部字段名——这是硬纪律,违反=翻译缺陷**:下游 hop_python 的每个 get(字段名) 都必须能回溯到原文或上游 instruction 的显式出处,凭空构造字段名=下游按固定名严格校验、上游 AI 自由猜名,一猜错整条链 blocked（0088 实撞里 project_cwd/session_path 等 10+ 个字段名原文一个都没有,全是翻译器凭空造的）。

翻译中的硬纪律（违反=翻译错误，非风格问题；每条的完整反例与边角处置查 primer「多文件与粒度细则」节）：

- **交付写盘归 commit**——"保存为/写入文件/发送"必须是 [commit] 且前面有针对交付物的 [check]，act free 不得承载提交语义；
- **多路径 skill 的 Outputs 拿每条完成路径反验**（hopissues/0084 实撞——Outputs 变量只在 branch 一臂产出,validate 既有档全绿,用户跑另一臂运行时才 failed;引擎已补条件产出静态 warn,教学是前手闸）：按 stage 路由/分支交付不同产物的 skill,默认拆 call 子 spec、各交付链自带本路径 Outputs;共享顶层 Outputs 只收**每条完成路径都真产出**的变量——定稿前逐条完成路径走一遍问"这条路走完,Outputs 每个变量都有值吗",答不上的变量要么下放到子 spec、要么在缺产出的路径补赋值;
- **交互闸门保留**——原文的人工确认/问人必须落成 ask/confirm，落成别的类型等于把"问人"偷换成"机器替人答"；
- **reason 输入接内容变量**——描述说"通读/分析 X"就必须 `←` 接 X 的内容，只接路径执行期空转；
- **对齐后契约盖过原文**——用户在对齐门裁掉的能力（删掉的工具、砍掉的模式），原文里还有也不翻进产物，在研判点台账记一笔"原文含 X，已按对齐契约裁剪"；
- **门禁句拎出**——流程性引用文件里的门禁/闸门句必须翻成显式 [check]/[confirm]，操作细节可留文件按需读（粒度粗不豁免把关）；
- **动作不许蒸发**——闸门后的执行步、条件性动作的落点、分支产出的下游消费，逐个在场；
- **宿主能力路径塌缩**——原文"发 Agent/run_in_background/有没有某工具走不同路"这类按宿主载体能力分的路径，塌缩成引擎原生形态（并行=独立子 spec+`[call ... parallel]`，汇聚=收齐后串行 call）；产物步骤说明零宿主机制名（照抄=执行期空等死锁），塌缩后逐项对账纪律无蒸发。

**写每一步的 I/O 与描述时，先想执行 LLM 到时候看得见什么**（步骤自足性——每次翻译每一步都要过的判断）：执行期它能看到的只有——全局骨架的**摘要行**（别步的 `>` 描述细节与 body 都不可见）、`- ←` 声明变量的**实际值**（没声明的变量值不可见，别指望执行链捎带）、本步 `>` 描述全文、doc-ref 注入的知识切片。**原文不随产物走**——描述里写"参照原文第三节"执行期就是死引用，需要的内容要么写进描述、要么抽成知识文档 doc-ref 引。六层视野的完整机制查 primer「执行时每步能看到什么」节。

各形态的生成模板、识别信号与反例查 primer（「step 类型选型」「四类纪律句怎么翻」「hop_python 小语言」三节）——模板照抄比凭记忆写稳。

### 第 5 步：逐关自检（不过就修，修完重检）

产出草稿后过五道关：

- **合法关**：`hopjit validate <草稿>` 零 error——报错按清单逐条修（高频规则码速查 primer「高频验证规则」节）。**warning 也要逐条表态，不许静默路过**：每条 warning 要么修掉、要么在研判点台账记一句为什么留（"步 9 P6 warn：原文要求失败即停，刻意不加重试与兜底"这样一句就够）；**零 warning 时也要表态一句**——在实测报告合法关一行写"warning 为空,无可表态条目"（有刻意设计使然的零触发面就顺带点名,如"P6 不触发系主事务 retry+check final+on fail 全在场"）——不写这句,零 warning 时的静默跳过与压根没看 warning 在形式上不可区分；warning 静静躺在输出里没人看过，和没跑 validate 是同一种失守；
- **忠实关**（宪法 0 的检查面——合法关管"写得对不对文法"，这关管"原文的东西丢没丢、变没变味"）：拿 source.md 原文从头到尾**逐段对读**产物，每段问两个问题：
  1. **完备性**：这段的判据/规则/模板/阈值在产物的哪里？合法落点四处——步骤正文、Constraints、随包知识文档、研判点台账（记了"不译入及理由"也算有落点）。四处都找不到 = 知识丢失，补上；
  2. **忠实性**：落进产物的表述和原文比，语义变没变？三个高发变味形态逐一核——强度弱化（原文"必须/不得"翻成"建议/尽量"）、范围收窄（原文管全程的义务只落在某一步）、条件偷换（原文"确认后执行 X"翻成"确认即完成"，X 蒸发）。变了味的按原文改回；
  逐段核完在实测报告里记一行"忠实关：对读 N 段，补落 X 处，纠偏 Y 处"——这关的产出是可审计的对读结论，不是"我觉得挺忠实"；**原文含对称同模板段落时加一道对偶核**（hopissues/0091 实撞:同结构的一对 stage prompt,一边译出了计时命令、另一边两处全漏,靠宿主真跑撞发布链才发现）：原文里结构相同的成对/成组段落（如按同一模板写的多个 stage prompt）,翻译产物逐个并排对比——同一模板位置上的命令调用、把关步骤,各产物要么都译出、要么都不译；只出现在一边的,回原文核实是真差异还是漏译。对偶核的结论（对比了哪几组、发现几处不对称、各自处置）记进实测报告；
- **合理关**：对照原文全文核六条——原文步骤全覆盖无杜撰、commit 前有 check 且没混进探索段、数据链接通、结构讲得出为什么这样拆、门禁与动作无蒸发（第 4 步自查面的复核）、指针闭合（步骤正文引用的包内路径对照第 2 步清单逐个真实存在且随交付走;**call 步的 callee 同核**——call 按 spec_id 同目录寻址不是路径引用,字面扫路径抓不到它:逐个 call 步核交付目录里有同名 .md,缺即 ENOENT 级缺陷）。**判"无需 commit"之前必须回原文扫交付动词**——"无"是查出来的不是猜出来的。合理关里两条有固定命令的机械前筛，照抄跑完把命令与结果原样贴进实测报告（这两条是粗筛不是判官：命中要人判真伪，全绿也不豁免上面六条的语义核）：
  1. **宿主机制词扫描**：`grep -rn 'run_in_background\|Agent 工具\|发射 agent\|发射 Agent\|subagent\|AskUserQuestion' <产物执行面文件>`——范围只圈执行面（spec/子 spec/知识文档），source.md 是原文副本、研判点台账要点名被替换物，都不在扫描面；命中执行面即翻译缺陷（宿主机制名进产物=执行期空等死锁：执行者会按说明空等一个不存在的工具直到整个 run 失败）。注意这只抓字面——换了说法的同病（"启动一个后台助手"）它抓不到，靠六条里的语义核兜；
  2. **包内路径实存核**：把产物步骤正文引用的包内路径逐个 `[ -e <路径> ]` 核对（doc-ref 形态引擎 P15 已静态罩，这条管散文里的路径指引）；核对时区分"包内附属文件"（必须实存）与"运行期才生成的产物目录"（不实存是正常，别误报）；**扫描面含第 7 步给用户的交付告知草稿**（hopissues/0085 实撞——交付告知里写"详见同目录 DEPLOY.md"而该文件不存在,原扫描面只圈 spec 步骤正文,告知文件漏网:用户按告知找文件两手空空。告知草稿里"同目录 <名字>.md"形态的文件指引,逐个在告知所在目录 `[ -e ]` 核,缺即缺陷）；
- **明确易懂关**（宪法 1 的检查面——检查姿态与忠实关恰好相反：忠实关拿原文对读，这关**不看原文只读产物**）：坐进"没跟过翻译过程、第一次拿到这份 spec"的读者座位通读产物全文，核四面：
  1. **行文**：步骤说明、变量说明、判据是不是完整的话？说人话，不写文言文——有没有缩略语、自造简称、只有翻译过程里才有含义的代号（执行 LLM 没跟过翻译过程，这类词到它手里就是噪声或误导）？有没有压缩断句、四字块连缀的文言腔（"料须经喂齐""不过即回"这类，每个都要展开成完整的句子——LLM 对压缩表述的理解比人更不稳定，且它不会反问、按猜的理解直接执行）？
  2. **布局**：分立的事项分条列了吗？有没有多件事挤成一坨长段——长段落里藏三个判据，执行 LLM 就会漏读其二；判据、清单、前提逐条一行，一个段落只装一个主题，超了就拆条目或拆段；
  3. **变量接口**：每个变量的名字加 `#` 说明，下游步骤不猜就能懂吗（装的是路径还是内容、文本还是结构）？
  4. **强语气在场**：门禁/禁令/红线句读起来仍是"必须/不得"的强度吗（忠实关核"与原文比有没有弱化"，这关核"产物自身读起来够不够硬"——一个对源一个对己）？
  改写了几处、改了哪类，记一行进实测报告；
- **实测关**：按 inputs 构造一两组贴近真实的参数，对步骤树做首步静态推演，成文一份简短实测报告。

### 第 6 步：作者终审（必须真人，意见即迭代）

把三样汇成一个审阅文件呈给作者：spec 全文、研判点台账（翻译中暂定的决策等作者终裁）、实测报告。作者按 source.md 原文对读核忠实性。**有修订意见 → 按意见定向修正后重过第 5 步各关再呈审；意见清空才放行。**

### 第 7 步：写盘交付

终审放行后：spec.md 写到原 skill 同目录（与 SKILL.md 并排），source.md 副本随行——产物住原目录时，步骤正文引用的附属文件本来就在场，自包含天然满足。**目标位置已有同名旧文件时先备份再写**（重译/迭代场景）：`cp <旧文件> <旧文件>.bak.$(date +%Y%m%d%H%M%S)` 后才覆盖，备份留原目录，交付告知里点一句"旧版已备份为 xxx"——旧版可能是用户改过的、正在被引用的，直接覆盖等于替用户销毁他的东西。告知用户产物路径，附打包指引：`hopjit pack <spec路径>` 可打包成独立具名 skill；**原文有附属文件被产物引用时，打包指引必须带上 `--assets`**（逗号分隔列出被引用的附属文件/目录）——pack 只自动收 spec 与 doc-ref 知识文档，附属资产不点名就不进包，装到别处的 skill 指针全悬空。

**交付前必跑 deep-validate 跑前体检**（scripts/deep-validate/deep-validate.md,params={spec_path: 产物, exec_mode: 目标模式}；多件产物用批量入口 scripts/deep-validate/dv-batch.md 一次体检）——宪法 6"工具核验"的后半道闸，风险报告随交付呈用户。它与 validate 不重叠：validate 管"写得合法"，它管"跑得起来"——实测它抓的全是 validate 全绿但真机必死的部署缺口（命令白名单缺席、绝对路径输入撞沙箱、act free 写域越界、check 判官被教读文件）。**跑不了也不许静默略过**：环境起不了引擎 run 时，在交付告知里明写一行"deep-validate 未跑（原因），部署前必补"——缓办要申报，蒸发是缺陷。

**交付物必附"部署前提清单"一节，且命令依赖同时写进机器声明**：产物 body 里经 subprocess.run 调用的命令名逐个列出——①写进产物 Config 段的 `requires_commands:` 键（如 `requires_commands: [git, jq]`——引擎启动时自动与宿主白名单对账，缺了在进任何步骤之前就拦下并指路，用户不再靠真跑撞墙才发现漏配；hopissues/0090）；②散文清单照旧保留，指引用户加进项目 hopjit.yaml 的 `commands:` 白名单（不加=启动被拦或运行期拒"命令不在白名单"）；产物 Tools 段声明的外部服务逐个列出对应的环境注册前提。原文有"`source <文件>` 注环境变量供命令消费"套路的，清单里显化一条"某某命令运行期依赖该文件的文件态注入"并列出变量名（hop 的 subprocess.run 不传环境变量，这条断桥不显化，宿主要到下游脚本深处报错才回溯得到——hopissues/0090 P4）。研发阶段用户可在白名单放宽口（如直接放行 bash），生产收敛为具名清单——spec 不改只动配置，这一节让用户知道旋钮在哪。

执行失败/中止（含终审 reject）时如实报告，不写盘不留半成品。

## 注意力纪律

- 人的触点只有三处：第 1 步选对象、第 3 步对齐门、第 6 步终审——中间过程不拿琐碎问题打断人；
- 进度汇报一行一步（"✓ 已完成：xx"），不逐节点直播；
- 中间产物（草稿/台账/测试文件）放临时工作目录，不污染用户工作区。