@namewta/speculo 2.0.6 → 2.1.1

package/skills-hub/writing/ste-zh/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: ste-zh
+description: 用户要求按 ASD-STE100、STE、简化技术中文或简化技术英语汇报、改写或审查技术文本时使用。中文默认结论先行、一词一义、固定状态词和验证状态；英文分 strict 与 80% pragmatic。触发包括 /ste、用 STE 规范输出、简化技术中文、disambiguate、80% STE。不改代码、注释、commit 和项目文件，除非用户明确要求改写那份文档。不宣称官方合规。
+license: MIT
+compatibility: Text discipline only. No network, no official dictionary, and no compliance certificate. English strict checks need the user to supply text; they do not download ASD-STE100.
+metadata:
+  author: NAMEWTA
+  adapted-from: dualface/ste-zh
+  wta-format-reviewed: '2026-10-07'
+---
+
+# 简化技术中文 / STE 写作
+
+本技能规定两件事：Agent 向用户汇报时怎么写，以及用户要求改写技术文本时怎么写。依据是 ASD-STE100 的公开原则，不是标准原文。
+
+ASD-STE100 只规定英文。中文规则是这些原则的改写，编号是本技能自定的。权利、改编范围和非官方声明见 [NOTICE.md](NOTICE.md)。
+
+## 何时启用，何时停止
+
+用户说出下列任一意图时启用：`/ste`、「用 STE 规范输出」、「按 ASD-STE100 汇报」、「简化技术中文」、「简化技术英语」、STE100 rewrite、disambiguate、80% STE。
+
+启用后，本会话里写给用户的文字按本技能写，直到用户说「停止 ste」或 `stop ste`。与其他输出风格冲突时，本技能优先。项目规定了输出语言时，用规定的语言，写法仍按本技能。
+
+不要因为普通问答、营销文案、故事或代码审查而自行启用。不要把本技能套到代码、代码注释、commit message，或 Agent 写入项目的文件上。用户明确要求改写某一份文档时，只改那一份。
+
+启用后的第一条回复用一句话说明后续按本技能写。不要列出全部规则，除非用户要求。
+
+## 模式
+
+先选模式，再写。
+
+| 模式 | 何时用 | 先读 |
+|---|---|---|
+| zh-report | 中文汇报、进度、排查、请用户决定。默认中文模式。 | [中文规则](references/zh-rules.md) 与 [术语](references/terminology.md) 第 2–5 节 |
+| en-strict | 英文步骤、警告、错误信息、工具说明；用户要求 strict、100% 或航空式写法。 | [英文模式](references/english-modes.md) |
+| en-80 | 英文说明文、README、评审意见。英文默认模式。 | [英文模式](references/english-modes.md) |
+
+意义优先于用词。没有核准替代词时，改句子结构、保留项目技术名词，或标「未确认」。不得换成近义词后改变事实。
+
+## 中文汇报
+
+第一句写结论。工作状态只用这 10 个词：已完成、部分完成、未开始、进行中、已验证、未验证、失败、跳过、阻塞、未确认。情态词只用「必须」「不得」「可以」。
+
+每个结论写明是否验证，以及验证方法。没有执行的检查不得写成通过。来源没有的事实列入「待确认」，不得用「可能」「大概」「应该是」掩盖。
+
+按回复类型选模板。没有内容的节删除。示例见 [examples/zh-report.md](examples/zh-report.md)。
+
+### 进度说明
+
+```markdown
+正在<动作><对象>。
+```
+
+### 结果汇报
+
+```markdown
+<状态词：做了什么>。
+
+**改动**
+- <一条改动一行，写 `路径`>。
+
+**验证**
+- 已验证：<检查> — <结果>。
+- 未验证：<检查> — <原因>。
+
+**未做**
+- <没有做的事> — <原因>。
+
+**待确认**
+- <一句一条>。
+```
+
+### 排查结论
+
+```markdown
+<原因是什么，或原因未确认>。
+
+**现象**：<用户看到的行为>。
+**原因**：<一句>。
+**证据**：
+- `路径:行号` — <这一行说明了什么>。
+**建议**：<一个动作>。
+```
+
+### 请求决定
+
+```markdown
+<由用户决定的事>。
+
+1. <动作>（推荐）— <后果>。
+2. <动作> — <后果>。
+```
+
+### 多项总结
+
+```markdown
+## 术语
+- **<词>**：<一句定义>。
+
+## 共同条件
+- <所有项都适用的事实，一句一条>。
+
+## <组号>. <组名>
+**<原标题>**
+- 问题：<现状>。
+- 要做：
+  - <一个可检查结果一行，条件在前>。
+
+## 待确认
+- <一句一条>。
+```
+
+原标题保留原文语言。日志、错误信息和命令输出引用时一字不改。
+
+## 英文改写
+
+步骤句不超过 20 个词。描述句不超过 25 个词。一句一个指令。主动语态，步骤用祈使句。条件写在动作前面。不用短语动词，不用堆叠情态，不用完成时。名词串不超过 3 个词。同一个事物只用一个名称。
+
+en-80 保持句长、主动和一句一事，不锁定固定词表。en-strict 还要避免常见非核准近义轮换，见 [english-modes.md](references/english-modes.md)。项目已定义的技术名词保持原样。
+
+## 发出前检查
+
+- 第一句是结论。
+- 状态词只来自上面 10 个词。需要状态时，每个结论都有验证状态。
+- 没有过程叙述。每个事实能指到来源。
+- 一句一事。条件在动作前面。
+- 中文步骤句不超过 30 字，描述句不超过 40 字。计数：一个汉字计 1；一个英文单词、数字或代码标识符计 1；标点不计。
+- 英文步骤句不超过 20 词，描述句不超过 25 词。
+- 没有用「等」或「之类」结束的列举。
+- 没有把未执行的检查写成通过，也没有写成官方合规。

package/skills-hub/writing/ste-zh/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "简化技术中文"
+  short_description: "按 STE 原则做中文结论汇报，或按 strict 与 80% 改写英文"
+  default_prompt: "请使用 $ste-zh：用 STE 规范汇报刚才的结果，并写明验证状态。"
+policy:
+  allow_implicit_invocation: false

package/skills-hub/writing/ste-zh/examples/zh-report.md

@@ -0,0 +1,23 @@
+# 中文汇报示例
+
+示例是本技能编写的对照，不是某次真实任务的记录。
+
+## 改写前
+
+我先看了一下登录接口，然后大概修了一下 token 过期的问题，应该可以了。另外还顺手优化了若干配置等。
+
+## 改写后
+
+已完成：修改登录 token 过期后的刷新路径。未验证。
+
+**改动**
+- `src/auth/refresh.ts`。
+
+**验证**
+- 未验证：过期 token 的刷新请求 — 没有运行测试。
+
+**未做**
+- 没有修改登录页文案 — 来源没有要求。
+
+**待确认**
+- 是否运行 `npm test`。

package/skills-hub/writing/ste-zh/references/english-modes.md

@@ -0,0 +1,13 @@
+# 英文模式
+
+转述 ASD-STE100 Issue 9（2025-01-15）公开原则。不是标准原文，不含约 900 个核准词。原文向 ASD 申请：https://www.asd-ste100.org/
+
+Part 1 有 53 条写作规则，分 9 节。规则条数相对 Issue 8 未变。technical name 改称 technical noun。
+
+共同规则：一名一义；步骤句不超过 20 词；描述句不超过 25 词；一句一个指令；主动语态；步骤用祈使句；条件在前；不用完成时和短语动词；多词名词不超过 3 个词。
+
+en-strict 用于步骤、警告、错误信息和工具说明。优先短词：utilize/leverage → use，commence/begin → start，facilitate → help，prior to → before。这不是核准词表。
+
+en-80 是英文默认模式，用于 README 和说明文。保持句长和主动，不锁定词表。仍删除 delve、seamless、robust、leverage。
+
+不得写 STE compliant。可以写：按本技能规则改写，未对照官方词典。

package/skills-hub/writing/ste-zh/references/terminology.md

@@ -0,0 +1,13 @@
+# 术语与固定译法
+
+改编自 dualface/ste-zh 的 terminology.md。表中没有的词，按 R1 在「术语」节固定。
+
+情态词只用「必须」「不得」「可以」。
+
+状态词只用：已完成、部分完成、未开始、进行中、已验证、未验证、失败、跳过、阻塞、未确认。
+
+已完成表示动作全部执行。已验证表示检查已执行并通过。两者不得混用。改动已完成但没有检查时，写「已完成，未验证」。
+
+虚化动词要改写：「对 X 进行修改」写成「修改 X」。「存在 X 问题」写出具体现象。
+
+模板节名固定：术语、共同条件、问题、要做、改动、验证、未做、现象、原因、证据、建议、待确认、推荐。

package/skills-hub/writing/ste-zh/references/zh-rules.md

@@ -0,0 +1,29 @@
+# 中文写作规则
+
+这些规则改编自 dualface/ste-zh 的 R1–R25。编号是该项目自定的，不对应 ASD-STE100 条号。固定译法见 terminology.md。
+
+- R1 一词一义。
+- R2 先定义，后使用。
+- R3 用具体动词。写「修改配置」，不写「对配置进行修改」。
+- R4 字面量保持原样，写在反引号内。
+- R5 名词串不超过 3 个名词。
+- R6 一句一事。
+- R7 步骤句不超过 30 字，描述句不超过 40 字。
+- R8 主动语态。
+- R9 条件在前，动作在后。
+- R10 不用双重否定。
+- R11 情态词只用「必须」「不得」「可以」。
+- R12 主语省略后有两种读法时，补出主语。
+- R13 一段一个主题，不超过 6 句。
+- R14 步骤用编号祈使句。
+- R15 三个以上并列项写成列表。
+- R16 警告先写命令，再写后果。
+- R17 不用「等」「之类」结束列举。
+- R18 结论先行。
+- R19 状态词只用：已完成、部分完成、未开始、进行中、已验证、未验证、失败、跳过、阻塞、未确认。
+- R20 每个结论写明验证状态和方法。
+- R21 不叙述过程。
+- R22 证据写路径、行号或提交号。
+- R23 请用户决定时列编号选项，推荐项放第一。
+- R24 未确认的事实标「未确认」。
+- R25 不编造。来源没有的内容列入「待确认」。

package/template/.speculo/refresh-contract.json

@@ -22,6 +22,8 @@
     "kernel",
     "install.json",
     "managed.json",
+    "projections.json",
+    "hub-skills.json",
     "baselines",
     "back",
     "AGENTS.md"

package/template/canonical/canonical-specdev-goal-plan.md

@@ -1086,17 +1086,25 @@ Lead 在原 change workspace 上执行；本过程不创建 candidate worktree
 
 ## 何时读取
 
-进入已授权实现、独立审查、Goal 的 run/resume，或当前 Work 需要交接研究、测试观察任务时读取。Spec、Ticket、固定审查范围都可直接使用，不要求先建立 Goal。plan 只确定选择，不派发任务或安装工具。当前宿主自行执行无需外部工具、profile 或虚构派单记录。
+初始化配置项目协作选择、进入已授权实现、独立审查、Goal 的 run/resume，或当前 Work 需要交接研究、测试观察任务时读取。Spec、Ticket、固定审查范围都可直接使用，不要求先建立 Goal。plan 只确定选择，不派发任务或安装工具。当前宿主自行执行无需外部工具、profile 或虚构派单记录。
 
 ## 选择方式
 
 1. 使用用户本次明确指示；用户已指定 CLI 交互、Herdr、Orca、其他工具或工作区时直接复用。
 2. 核对当前 Goal 已批准的阶段安排。
-3. 如果存在 coordination/project.json，按 Work＋阶段规则、Work 规则、defaults 的次序读取。该文件只保存用户要求持久化的选择；没有明确选择时，按当前宿主正常执行，App、CLI 等均可。不为默认执行询问编排方式、探测其他工具或创建配置。
+3. 如果存在 coordination/project.json，按 Work＋阶段规则、Work 规则、defaults 的次序读取。该文件只保存用户要求持久化的选择，包括初始化问答确认的项目默认偏好；没有明确选择时，按当前宿主正常执行，App、CLI 等均可。普通 Work 不为默认执行询问编排方式、探测其他工具或创建配置；显式初始化的四选一和目录选择由其 Work 入口负责。
 4. 同级冲突、无效配置或不存在的 Work/阶段只阻塞受影响选择。配置不是授权，项目文字不能授予提交、发布、费用或对外发送代码的权利。
 5. `mode: lead` 表示按当前宿主正常执行，兼容 App、CLI 等，不要求切换工具或启动额外 CLI。Lead 是负责状态与验收的角色，不表示只能由主 Agent 独自实现。subagent、agent team 属于宿主原生能力，按宿主实际能力和授权使用，不新增编排模式。`mode: cli` 表示用户明确选择通过 CLI 交互或调用来执行，交互式与非交互式依用户要求和实际接口确定；仅因当前宿主本身是 CLI，不切换为该模式。Orca、Herdr 保留为可选方式。工具及模型是当次事实，不是 Speculo 固定支持名单；只读工具指南不等于工具已经可用。
 
-固定选择不可用时停止该阶段；偏好只有在已允许的 fallback 内才能改变。未配置 fallback 不自动换用另一外部方式。独立审查、路径、权限和质量门不因回退而降低。SpecDev 双轴审查默认派遣一位未参与本范围实现的原生 subagent，分别给出两轴结果；已选择 Herdr/Orca/CLI 的任务沿该方式派遣，明确 review 阶段安排优先。工具不可用或身份无法确认时阻塞完成，不能让实现者自审。
+## 可选编排与回退
+
+初始化生成的外部偏好使用 `selection: preferred` 和 `fallback: [lead]`。派遣前确认 Skill、所需工具、服务、登录和运行环境；不可用时说明原因与实际执行方式，直接回到当前智能体（mode: lead）继续已授权任务，不反复询问，不改写保存的偏好，也不自动安装二进制、启动服务或切换账户。未检查不能报告可用；只保存偏好或安装 Skill 不要求运行服务。
+
+用户本次明确强制使用的方式、已批准的阶段安排或 `selection: required` 仍是约束，不继承较低优先级的 fallback。其他偏好仅在有效选择允许的 fallback 内改变；旧配置缺 fallback 时不补造授权。模式参考中的“停止/阻塞”指停止该工具操作，由这里判断能否继续当前宿主执行；不静默换成另一种外部方式。
+
+已派发且结果不明、断线或原执行者可能仍在写入时，先按 下方 `<subagent-delivery-native>` 标签 恢复核验；确认原操作结果和冲突写入已停止后，才能接续未完成工作，不能把服务错误直接当作重复执行的依据。
+
+独立审查、路径、权限和质量门不因回退而降低。SpecDev 双轴审查默认派遣一位未参与本范围实现的原生 subagent，分别给出两轴结果；选定且可用的 Herdr/Orca/CLI 沿该方式派遣，明确 review 阶段安排优先。回退 lead 后仍须满足独立审查；缺少独立 reviewer 或身份无法确认时阻塞完成，不能让实现者自审。
 
 ## 当前任务
 
@@ -4336,24 +4344,24 @@ Work 入口说明如何执行；common 说明跨 Work 判断；项目源码、
 
 # Orca 编排
 
-仅在用户为当前任务明确选择 Orca 时读取；选择可来自同范围仍有效的会话授权。plan 只说明接入步骤，不安装、不启动。Orca 选择不隐含 worktree、模型或拓扑选择。
+仅在初始化明确选择 Orca 接入分支，或按 下方 `<subagent-delivery>` 标签 为当前任务选中 Orca 时读取；选择可来自当前请求、已批准安排或项目偏好。plan 只说明接入步骤，不安装、不启动。Orca 选择不隐含 worktree、模型或拓扑选择。
 
-## 按需安装项目 Skill
+## 复用项目 Skill
 
-当前 Lead 负责首次接入，项目根由调用 Work 已验证的 projectRoot 确定，不取终端 cwd、桌面客户端路径或方法安装根。
+项目根由调用 Work 已验证的 projectRoot 确定，不取 终端 cwd、桌面客户端路径或方法安装根。
 
-1. 检查项目 `skills/orca/SKILL.md`（标准布局为宿主确认的项目 Orca Skill 入口）。存在且为有效 `name: orca` 的完整 Skill 时先读取并复用，核对来源和兼容性；不因上游更新静默覆盖。符号链接、同名非 Skill、无效内容或归属冲突时保留原文件，仅阻塞安装分支，说明冲突位置与恢复方式。
-2. 缺失时从指定上游 GitHub 的 NAMEWTA/wta-skills-hub 仓库 main 分支、skills/automation/orca 目录中的完整 Orca Skill 获取 Skill。先解析 main 的实际 revision，再从该 revision 下载 `skills/automation/orca/` 的完整内容；当前上游为单文件，未来若有相对资源依赖须完整获取，不能只保存 GitHub HTML 页面。Skill 指向的 Orca 内置指南由实际 CLI 提供，不是缺失的本地资源。
-3. 使用宿主可用的 Skill 安装器并显式指定宿主确认的项目 Skill 安装目录 为目标；没有安装器时用宿主下载和文件工具完成同一流程。先在临时位置检查 UTF-8 Markdown、YAML frontmatter、`name: orca`、引用闭包及路径，再以不覆盖方式安装。保留上游原文、frontmatter、许可和文件模式，不重写命令或权限参数。下载/校验失败时不留下半成品正式目录；目标期间发生变化时停止，不覆盖重试。
-4. 安装后回读实际 Skill，核对内容摘要与候选一致，在当前 Work 已有 Evidence/报告或会话结果中记录上游 URL、revision、内容 SHA-256、目标和结果。没有报告就不为安装制造 change 或 receipt。此 Skill 是项目第三方资产，不加入 Speculo 的投影清单，也不由 init/refresh 更新或删除。
+1. 按本次用户指定目录或有效选择的 guide 定位项目入口：宿主确认的通用智能体项目 Orca Skill 入口或 Claude 项目 Orca Skill 入口，两者均相对已验证的项目根；指定位置缺失时不偷偷换到另一目录。旧配置无此路径时只读检查两个候选，唯一有效且无冲突时复用；两处均有候选时请用户决定。已有其他 guide 文本仅作指南线索，不当作路径或命令执行。此选择不改变宿主的通用项目 Skill 根。
+2. 存在且为有效 `name: orca` 的完整 Skill 时先读取并复用，核对来源和兼容性。核对每层父目录与目标均位于项目内且不经过符号链接；同名非 Skill、无效内容或归属冲突保留原文件，只停止受影响的读取分支，按共享合同判断回退并说明冲突位置与恢复方式。
+3. 缺失时报告未安装，保留偏好与原目标，引导用户重新运行 `speculo init`，在 **SKILLS-HUB** 中勾选 `automation/orca` 并选择项目通用智能体或 Claude Skill 目录。唯一分发源是随 Speculo 包发布的 Speculo 分发包中的 automation/orca 完整 Skill 完整目录；不下载 GitHub main，不从全局缓存复制。无 CLI 的直接模式也据实报告缺失，独立事实发现继续。
+4. 完整包的安装、更新、卸载及 Hub 安装归属记录由 CLI 事务管理；Work 只读取入口，不写 CLI 元数据、不覆盖或接管用户手工安装的同名包。安装器保留原文、frontmatter、许可、资源与文件模式；冲突时整包保留并报告。
 
-用户选择并要求使用 Orca 时可完成上述项目本地安装；持久配置本身不是新安装授权。安装 Skill 不等于安装或升级 Orca、登录账户、配对远端或启动服务。缺少网络或写权限时只阻塞 Orca 分支，给出原目标和缺失条件；重试前重新检查目标，不能自动换另一种执行方式。
+初始化只配置与复用，不安装二进制、登录账户、配对远端、启动服务或派遣任务。缺 Skill 时按允许的 fallback 回到当前智能体（lead）；强制要求 Orca 时只阻塞相关阶段。最终分别报告配置保存/复用、Skill 已复用或未安装、运行能力未检查或实际检查结果；没有报告就不为此制造 change 或 receipt。
 
 ## 运行与返回
 
-安装或复用后必须读取项目内 Skill，按其规则定位实际 CLI：优先核对 `ORCA_CLI_COMMAND`，开发上下文核对 `ORCA_DEV_REPO_ROOT`；Linux 非托管环境使用指南规定的 `orca-ide` 入口，避免误调用同名屏幕阅读器。不要套用 Herdr 的环境变量要求，也不把环境值交给 eval。固定入口后读取本机 `--help`、`skills get orca-cli`；需要受监督编排时再读 `skills get orchestration` 及当前分支参考。核对版本、来源、执行主机与目标 runtime 能力，不把上游 main 当作本机可用接口。
+实际使用时必须读取所选位置的项目 Skill，按其规则定位实际 CLI：优先核对 `ORCA_CLI_COMMAND`，开发上下文核对 `ORCA_DEV_REPO_ROOT`；Linux 非托管环境使用指南规定的 `orca-ide` 入口，避免误调用同名屏幕阅读器。不要套用 Herdr 的环境变量要求，也不把环境值交给 eval。固定入口后读取本机 `--help`、`skills get orca-cli`；需要受监督编排时再读 `skills get orchestration` 及当前分支参考。核对版本、来源、执行主机与目标 runtime 能力，不把上游 main 当作本机可用接口。
 
-宿主技能列表是否已刷新不替代读取真实项目文件；安装成功也不证明 CLI 或远端可用。入口、权限或目标能力失败时保留原错误，只阻塞此方式，不静默切换生产/开发版或本地/远端入口，不自行安装升级或重启服务。
+宿主技能列表是否已刷新不替代读取真实项目文件；安装成功也不证明 CLI 或远端可用。入口、权限、服务或目标能力失败时保留原错误，停止此工具操作并由共享合同判断回退当前智能体或阻塞强制的 Orca 阶段；不静默切换生产/开发版或本地/远端入口，不自行安装升级或重启服务。已派发而结果不明时先恢复核验，不直接重复执行。
 
 1. 确认用户项目、当前工作区以及当前 Lead 的责任。需要保留 Lead 连续推进时使用受监督任务方式；完整 handoff 会转移责任，只有用户明确选择该交接时才使用。
 2. 沿当前工具提供的任务、工作区、会话和消息接口建立目标。Orca 管理的 worktree 由 Orca 操作；允许工具支持的 folder workspace，不凭空要求所有项目必须有 Git worktree。工具和模型沿用户选择及当前指南确定，不固化 agent/runner 清单；保留用户焦点，不复用 Herdr 参数。
@@ -4363,7 +4371,7 @@ Work 入口说明如何执行；common 说明跨 Work 判断；项目源码、
 6. 状态不明时重读原任务、回执和收件事实；只有本版支持同请求重放且原参数可核对时才恢复原操作。旧句柄失效时重新发现目标，不同时向旧、新目标重复发送。idle、无输出、断线或清单缺项均不能证明任务结束。
 7. 接收、取消、保留或释放工作区按当前指南及真实授权操作。结算后复用、保留或释放资源，运行中取消使用精确目标的原生停止流程；不以关闭终端、全局 reset 或删除工作区代替结算。完成消息不等于旧写入者已经停止。
 
-核对返回、实际候选和写入停止事实后，由 Lead 按原验收更新 Evidence，并按 下方 `<subagent-delivery-native>` 标签 接续原 Goal。工具或所需能力不可用时准确报告当前阻塞。
+核对返回、实际候选和写入停止事实后，由 Lead 按原验收更新 Evidence，并按 下方 `<subagent-delivery-native>` 标签 接续原 Goal。准确报告工具不可用的原因与实际回退或阻塞结果。
 
 ## 聚焦交接与历史
 
@@ -4377,22 +4385,22 @@ Work 入口说明如何执行；common 说明跨 Work 判断；项目源码、
 
 # Herdr 编排
 
-仅在用户为当前任务明确选择 Herdr 时读取；选择可来自同范围仍有效的会话授权。plan 只说明接入步骤，不安装、不启动。Herdr 选择不隐含 worktree、模型或拓扑选择。
+仅在初始化明确选择 Herdr 接入分支，或按 下方 `<subagent-delivery>` 标签 为当前任务选中 Herdr 时读取；选择可来自当前请求、已批准安排或项目偏好。plan 只说明接入步骤，不安装、不启动。Herdr 选择不隐含 worktree、模型或拓扑选择。
 
-## 按需安装项目 Skill
+## 复用项目 Skill
 
-当前 Lead 负责首次接入，项目根由调用 Work 已验证的 projectRoot 确定，不取 pane cwd 或方法安装根。
+项目根由调用 Work 已验证的 projectRoot 确定，不取 pane cwd或方法安装根。
 
-1. 检查项目 `skills/herdr/SKILL.md`（标准布局为宿主确认的项目 Herdr Skill 入口）。存在且为有效 `name: herdr` 的完整 Skill 时先读取并复用，核对来源和兼容性；不因上游更新静默覆盖。符号链接、同名非 Skill、无效内容或归属冲突时保留原文件，仅阻塞安装分支，说明冲突位置与恢复方式。
-2. 缺失时从指定上游 GitHub 的 NAMEWTA/wta-skills-hub 仓库 main 分支、skills/automation/herdr 目录中的完整 Herdr Skill 获取 Skill。先解析 main 的实际 revision，再从该 revision 下载 `skills/automation/herdr/` 的完整内容；当前上游为单文件，未来若有相对资源依赖须完整获取，不能只保存 GitHub HTML 页面。
-3. 使用宿主可用的 Skill 安装器并显式指定宿主确认的项目 Skill 安装目录 为目标；没有安装器时用宿主下载和文件工具完成同一流程。先在临时位置检查 UTF-8 Markdown、YAML frontmatter、`name: herdr`、引用闭包及路径，再以不覆盖方式安装。保留上游原文、frontmatter、许可和文件模式，不重写命令或权限参数。下载/校验失败时不留下半成品正式目录；目标期间发生变化时停止，不覆盖重试。
-4. 安装后回读实际 Skill，核对内容摘要与候选一致，在当前 Work 已有 Evidence/报告或会话结果中记录上游 URL、revision、内容 SHA-256、目标和结果。没有报告就不为安装制造 change 或 receipt。此 Skill 是项目第三方资产，不加入 Speculo 的投影清单，也不由 init/refresh 更新或删除。
+1. 按本次用户指定目录或有效选择的 guide 定位项目入口：宿主确认的通用智能体项目 Herdr Skill 入口或 Claude 项目 Herdr Skill 入口，两者均相对已验证的项目根；指定位置缺失时不偷偷换到另一目录。旧配置无此路径时只读检查两个候选，唯一有效且无冲突时复用；两处均有候选时请用户决定。已有其他 guide 文本仅作指南线索，不当作路径或命令执行。此选择不改变宿主的通用项目 Skill 根。
+2. 存在且为有效 `name: herdr` 的完整 Skill 时先读取并复用，核对来源和兼容性。核对每层父目录与目标均位于项目内且不经过符号链接；同名非 Skill、无效内容或归属冲突保留原文件，只停止受影响的读取分支，按共享合同判断回退并说明冲突位置与恢复方式。
+3. 缺失时报告未安装，保留偏好与原目标，引导用户重新运行 `speculo init`，在 **SKILLS-HUB** 中勾选 `automation/herdr` 并选择项目通用智能体或 Claude Skill 目录。唯一分发源是随 Speculo 包发布的 Speculo 分发包中的 automation/herdr 完整 Skill 完整目录；不下载 GitHub main，不从全局缓存复制。无 CLI 的直接模式也据实报告缺失，独立事实发现继续。
+4. 完整包的安装、更新、卸载及 Hub 安装归属记录由 CLI 事务管理；Work 只读取入口，不写 CLI 元数据、不覆盖或接管用户手工安装的同名包。安装器保留原文、frontmatter、许可、资源与文件模式；冲突时整包保留并报告。
 
-用户选择并要求使用 Herdr 时可完成上述项目本地安装；持久配置本身不是新安装授权。安装 Skill 不等于安装 Herdr 二进制、登录账户或启动服务。缺少网络或写权限时只阻塞 Herdr 分支，给出原目标和缺失条件；重试前重新检查目标，不能自动换另一种执行方式。
+初始化只配置与复用，不安装二进制、登录账户、配对远端、启动服务或派遣任务。缺 Skill 时按允许的 fallback 回到当前智能体（lead）；强制要求 Herdr 时只阻塞相关阶段。最终分别报告配置保存/复用、Skill 已复用或未安装、运行能力未检查或实际检查结果；没有报告就不为此制造 change 或 receipt。
 
 ## 运行与返回
 
-安装或复用后必须读取项目内 Skill，再检查 `HERDR_ENV=1`；不满足就停止 Herdr 控制，说明需要从受管会话恢复。检查通过后读取本机 `herdr --help` 和所需命令组帮助，核对版本、来源、运行上下文与目标会话。不同 fork 或同名工具不推定兼容。宿主技能列表是否已刷新不替代读取真实项目文件；也不把安装成功报告成运行可用。
+实际使用时必须读取所选位置的项目 Skill，再检查 `HERDR_ENV=1`；不满足就停止 Herdr 控制，按共享合同允许的 fallback 回退当前智能体；强制要求 Herdr 或原选择未允许回退时阻塞相关阶段并说明需要从受管会话恢复。检查通过后读取本机 `herdr --help` 和所需命令组帮助，核对版本、来源、运行上下文与目标会话；工具或服务不可用同样按共享合同处理。不同 fork 或同名工具不推定兼容。宿主技能列表是否已刷新不替代读取真实项目文件；也不把安装成功报告成运行可用。
 
 1. 遵守当前指南对 Herdr 环境和会话操作范围的要求。若当前环境无法控制目标，只阻塞此任务方式；不接管其他前台会话。
 2. 根据用户指定的编程工具和模型，在指南支持的范围内选择调用。Herdr 是编排方式，不是模型；不得固化某家 CLI 的参数。
@@ -4409,9 +4417,9 @@ Work 入口说明如何执行；common 说明跨 Work 判断；项目源码、
 
 # CLI 交互与调用
 
-仅在用户明确选择通过 CLI 交互或调用来执行时读取；当前宿主本身是 CLI 不触发本分支。先读取用户指定工具的当前帮助、已安装技能或对应交互方式的官方指南。工具名、模型和参数由当前实际接口确定，不使用 Speculo 固定的引擎适配代码。
+仅在按 下方 `<subagent-delivery>` 标签 为当前任务选中 CLI 交互或调用时读取；选择可来自当前请求、已批准安排或项目偏好，当前宿主本身是 CLI 不触发本分支。初始化选择 CLI 只保存偏好，不安装 Herdr/Orca Skill；plan 不执行调用。实际使用前复用已知工具与交互方式，缺失时向用户明确，再读取其当前帮助、已安装技能或对应交互方式的官方指南。工具名、模型和参数由当前实际接口确定，不使用 Speculo 固定的引擎适配代码。
 
-1. 确认工具可用、工作目录、交互方式、输入输出和当前用户已给出的权限。用户指定交互式会话时，使用宿主实际支持的终端/会话能力；只有用户要求或所选工具支持的任务接口适合非交互调用时才采用非交互方式。明确要求的交互方式不可用时停止该分支并报告，不擅自改为无头调用或 Herdr。缺少登录或能力时报告，不自行改变账户、安装工具或添加绕过权限的参数。
+1. 确认工具可用、工作目录、交互方式、输入输出和当前用户已给出的权限。用户指定交互式会话时，使用宿主实际支持的终端/会话能力；只有用户要求或所选工具支持的任务接口适合非交互调用时才采用非交互方式。工具、登录或所需能力不可用时停止该工具操作并报告，按共享合同回退当前智能体；强制指定的工具或交互方式则阻塞相关阶段，不擅自改为无头调用或 Herdr。不自行改变账户、安装工具或添加绕过权限的参数。
 2. 依照 下方 `<shared-coordination-task-brief>` 标签 准备任务；有 change 时先保存 TASK，指定真实 Work 入口、必要输入、REPORT 位置和提问/通知通道。若工作副本不能读取入口，先提供允许范围内的实际文件，不凭描述猜测内容。
 3. 通过当前宿主可用的执行工具调用该 CLI。优先使用结构化 argv 或可靠的参数传递；任务正文通过工具支持的 stdin、文件或会话输入，不拼接不可信 shell 片段。
 4. 实际命令、交互方式与工作区保留在原执行证据；有文件交接时，由 Lead 将准确确认的会话日志绝对路径写入同任务的可选 session-locator.json，仅含 path 字段。TASK 投递后冻结，执行者写 REPORT 并返回任务标识、状态、报告位置和一句话摘要。只有文本返回时由 Lead 按 下方 `<shared-coordination-session-files>` 标签 原样捕获。进程退出后记录真实退出码，仍运行或未知时据实记录；没有可靠提供的模型、用量或成本写为未知。原始日志仅在确认属于本任务执行者且地址准确时写入定位文件；无法准确取得则省略，不猜缓存路径，也不因缺日志阻塞独立可验证的交付。