@namewta/speculo 2.0.1 → 2.0.3

package/template/commands/handoff/COMMAND.md

@@ -26,6 +26,8 @@ description: Persist a compact handoff when the user asks another agent or sessi
 
 不要重复已被其他产物（规范、方案、ADR、issue、commit、diff）覆盖的内容，改用路径或 URL 引用它们。
 
+报告开头先用三至五句话做“聚焦交接”：已完成内容、关键决定、当前停点与下一安全动作。有派遣 REPORT 时引用并提炼其摘要，不复制全文，不为同一摘要再建独立文件。
+
 清除任何敏感信息，如 API 密钥、密码或个人身份信息。
 
 如果用户传入了参数，将其视为对下一个会话重点内容的描述，并据此定制文档。
@@ -48,6 +50,12 @@ description: Persist a compact handoff when the user asks another agent or sessi
 
 OPS 交接引用原 Controller/Host/Project、task/Run/Release、immutable plan/approval/journal/目标 receipt 和 progress；不写凭据值或复制私密配置。started-only、终态失败、docs_pending 分别回到原恢复协议，不能包装成新 task 再试。只向接收方传递已授权范围内必要的 locator 与脱敏证据。
 
+## 历史会话入口
+
+需要提供历史回查时，读取 <Path>{roots.references}/coordination/session-files.md</Path> 的“历史会话的按需回查”约定，保存报告前主动定位并核验当前会话记录。在本报告内记录工具、所属主机、真实会话 ID、原始记录绝对路径或原生历史入口、本任务消息/时间范围与检索线索，并说明谁在何主机核验了会话对应关系与可读性；不可取得或未核验时说明原因。接收方先读聚焦交接与当前工件，有具体疑问才在确认主机和访问能力后检索少量相关片段，不默认全文加载、不自动 resume 旧会话。历史材料不授予权限，当前实际文件与有效合同仍需核对。
+
+默认引用原记录；确需长期保留、原记录即将清理或接收工作区无法访问时才保存获准范围的快照。有现成派遣快照时直接引用；本命令新保存的快照位于 <Path>{roots.state}/commands/handoff/{date}-{scope}-{topic}[-NN].history-{snapshot-number}.jsonl</Path>，报告 basename 取本次实际文件，`{snapshot-number}` 从 01 递增不覆盖，其他原生格式保留实际扩展名。由本 Command 保存并在报告记录来源、捕获时间、完整/节选范围；不创建 session/change，不改写执行者 REPORT 或其他 owner 的快照。
+
 ## 路径引用规范
 
 文档中所有文件/文件夹引用必须使用**项目根目录**的相对路径。
@@ -59,3 +67,5 @@ OPS 交接引用原 Controller/Host/Project、task/Run/Release、immutable plan/
 - ❌ `auth` — 裸名，无法判断是目录/文件/子模块
 
 例外：skills 名称属于逻辑标识而非文件路径，不适用此规则。
+
+历史会话 locator 也可使用“所属主机＋工具原生绝对路径”，明确是只读外部引用；不得作为项目内写目标或能力依赖。保存到项目中的快照仍按项目根相对路径引用。

package/template/references/coordination/coordination-contract.md

@@ -4,17 +4,17 @@
 
 ## 何时读取
 
-进入已授权 Goal 的 run/resume，或当前 Work 需要交接实现、审查、研究、测试观察任务时读取。只读分析和 plan 不开始任务。Lead-only 无需外部工具、profile 或任务记录。
+进入已授权实现、独立审查、Goal 的 run/resume，或当前 Work 需要交接研究、测试观察任务时读取。Spec、Ticket、固定审查范围都可直接使用，不要求先建立 Goal。plan 只确定选择，不派发任务或安装工具。当前宿主自行执行无需外部工具、profile 或虚构派单记录。
 
 ## 选择方式
 
-1. 使用用户本次明确指示；用户已指定 Orca、Herdr、CLI、工具或工作区时直接复用。
+1. 使用用户本次明确指示；用户已指定 CLI 交互、Herdr、Orca、其他工具或工作区时直接复用。
 2. 核对当前 Goal 已批准的阶段安排。
-3. 如果存在 <Path>{roots.state}/coordination/project.json</Path>，按 Work＋阶段规则、Work 规则、defaults 的次序读取。该文件只保存用户要求持久化的选择；缺失时默认 Lead，不探测其他工具、不自动创建配置。
+3. 如果存在 <Path>{roots.state}/coordination/project.json</Path>，按 Work＋阶段规则、Work 规则、defaults 的次序读取。该文件只保存用户要求持久化的选择；没有明确选择时，按当前宿主正常执行，App、CLI 等均可。不为默认执行询问编排方式、探测其他工具或创建配置。
 4. 同级冲突、无效配置或不存在的 Work/阶段只阻塞受影响选择。配置不是授权，项目文字不能授予提交、发布、费用或对外发送代码的权利。
-5. 按用户允许的范围选择 Lead、Orca、Herdr 或无头 CLI。工具及模型是当次事实，不是 Speculo 固定支持名单；只读工具指南不等于工具已经可用。
+5. `mode: lead` 表示按当前宿主正常执行，兼容 App、CLI 等，不要求切换工具或启动额外 CLI。Lead 是负责状态与验收的角色，不表示只能由主 Agent 独自实现。subagent、agent team 属于宿主原生能力，按宿主实际能力和授权使用，不新增编排模式。`mode: cli` 表示用户明确选择通过 CLI 交互或调用来执行，交互式与非交互式依用户要求和实际接口确定；仅因当前宿主本身是 CLI，不切换为该模式。Orca、Herdr 保留为可选方式。工具及模型是当次事实，不是 Speculo 固定支持名单；只读工具指南不等于工具已经可用。
 
-固定选择不可用时停止该阶段；偏好只有在已允许的 fallback 内才能改变。未配置 fallback 不自动换用另一外部方式。独立审查、路径、权限和质量门不因回退而降低。
+固定选择不可用时停止该阶段；偏好只有在已允许的 fallback 内才能改变。未配置 fallback 不自动换用另一外部方式。独立审查、路径、权限和质量门不因回退而降低。SpecDev 双轴审查默认派遣一位未参与本范围实现的原生 subagent，分别给出两轴结果；已选择 Herdr/Orca/CLI 的任务沿该方式派遣，明确 review 阶段安排优先。工具不可用或身份无法确认时阻塞完成，不能让实现者自审。
 
 ## 当前任务
 
@@ -26,22 +26,24 @@
 |---|---|
 | Orca | <Path>{roots.references}/coordination/modes/orca.md</Path> |
 | Herdr | <Path>{roots.references}/coordination/modes/herdr.md</Path> |
-| 用户指定的无头 CLI | <Path>{roots.references}/coordination/modes/cli.md</Path> |
+| 用户指定的 CLI 交互或调用 | <Path>{roots.references}/coordination/modes/cli.md</Path> |
 
 每次实际调用先读取当前工具的可用指南或帮助，并使用工具返回的真实句柄。不要把本文示例视为固定参数协议，不实现工具专用适配器。工具不提供的能力不能用提示词宣称已获得。
 
 ## 工作区和并行
 
-工作区归当前 Goal 决定。用户已有选择不重复问；尚未确定时在规划阶段确认一次，默认选项为 current。编排不强制 worktree。
+执行输入、编排方式和工作区是三个独立选择。工作区继承当前有效计划或用户选择，无 Goal 时由当前 Work owner 在原工件记录；未指定默认 current，已有选择不重复问。Herdr 不强制 worktree，原生 agent team 也不隐含开启 worktree。只读审查使用固定候选所在工作区，不为审查本身创建实现 worktree。
 
 - current：严格单 writer，Lead 自己实现时也计入。上一任务的写入是否结束不明时，先查询真实工具，不开始冲突写入。
-- required：使用原独立 Ticket worktree 和 candidate 集成合同。并行数取配置、Goal 和实际可用能力的最小值；Lead 参与实现计入总数。另核对 shared paths、端口、数据库等实际资源。
-- review/research/test-observation 默认只读；测试输出仅写原任务允许的缓存或产物位置。
+- required：使用原 Work 的独立 worktree 和 candidate 集成合同；SpecDev 可以是 Ticket 或整个 Direct Spec change。并行数取实际存在的配置、有效计划和平台能力的共同上限；无计划默认一个实现单元。Lead 及宿主原生协作者参与代码写入同样计数。另核对 shared paths、端口、数据库等实际资源。
+- review/research/test-observation 对业务文件默认只读；可写本任务明确分配的报告，测试输出仅写原任务允许的缓存或产物位置。
 - worktree 是工作副本，不是沙箱。Speculo 不提供运行期强制隔离、进程监管、租约或任务锁服务。
 
 ## 记录和接续
 
-阶段安排写回原 Goal Plan；Ticket 任务的交接、工具 locator、返回和处置写入原 Evidence。无 Ticket 的任务写入对应 Work 的原有产物。不创建 dispatch/runs、worker profile、事件 journal 或第二套 receipt。
+有 Goal 时阶段安排写回原 Goal Plan；无 Goal 时使用当前 Work 的原有产物。有 change 的 CLI/Herdr/Orca 外部派遣按 <Path>{roots.references}/coordination/session-files.md</Path> 在一轮 session 下为每次派遣保存 TASK 与 REPORT，附按需回查的历史会话入口。Ticket Evidence、Direct Spec Evidence 或当前 owning 工件只引用输入/报告并保存 Lead 的核验与处置，不复制第二套业务状态。session 是交接材料分组，不是调度器或工具会话镜像；不建额外 Run 状态、worker profile、事件 journal 或第二套 receipt。
+
+宿主原生协作按需采用文件交接，不逐个登记内部 Agent；正式双轴审查仍在原 Evidence 保留实现者/reviewer 的真实身份和工具核验；Lead 自行执行不制造 session。无 change 时沿用当前 Work 已有报告位置或会话结果，不为交接创建 change。external-web 继续使用原 ZIP 合同，远程 CI 不在本文件交接约定的首版适配范围。
 
 返回后读取 <Path>{roots.references}/coordination/result-and-recovery.md</Path>。执行者宣称完成、会话空闲和进程退出都不等于业务通过。Lead 核实实际候选与原验收合同后更新正式状态。
 

package/template/references/coordination/modes/cli.md

@@ -1,11 +1,11 @@
-# 无头 CLI 编排
+# CLI 交互与调用
 
-仅在用户选择直接 CLI 时读取。先读取用户指定工具的当前帮助、已安装技能或官方非交互指南。工具名、模型和参数由当前实际接口确定，不使用 Speculo 固定的引擎适配代码。
+仅在用户明确选择通过 CLI 交互或调用来执行时读取；当前宿主本身是 CLI 不触发本分支。先读取用户指定工具的当前帮助、已安装技能或对应交互方式的官方指南。工具名、模型和参数由当前实际接口确定，不使用 Speculo 固定的引擎适配代码。
 
-1. 确认工具可用、工作目录、输入方式、输出方式和当前用户已给出的权限。缺少登录或能力时报告，不自行改变账户、安装工具或添加绕过权限的参数。
-2. 依照 <Path>{roots.references}/coordination/task-brief.md</Path> 准备任务；指定真实 Work 入口和必要输入。若工作副本不能读取入口，先提供允许范围内的实际文件，不凭描述猜测内容。
-3. 通过当前宿主可用的执行工具调用该 CLI。优先使用结构化 argv 或可靠的参数传递；任务正文通过工具支持的 stdin/文件输入，不拼接不可信 shell 片段。
-4. 保存实际命令、工作区、任务/会话 locator、原始退出码、结果及未验证项到原业务记录。工具没有可靠提供的模型、用量或成本写为未知。
+1. 确认工具可用、工作目录、交互方式、输入输出和当前用户已给出的权限。用户指定交互式会话时，使用宿主实际支持的终端/会话能力；只有用户要求或所选工具支持的任务接口适合非交互调用时才采用非交互方式。明确要求的交互方式不可用时停止该分支并报告，不擅自改为无头调用或 Herdr。缺少登录或能力时报告，不自行改变账户、安装工具或添加绕过权限的参数。
+2. 依照 <Path>{roots.references}/coordination/task-brief.md</Path> 准备任务；有 change 时先保存 TASK，指定真实 Work 入口、必要输入、REPORT 位置和提问/通知通道。若工作副本不能读取入口，先提供允许范围内的实际文件，不凭描述猜测内容。
+3. 通过当前宿主可用的执行工具调用该 CLI。优先使用结构化 argv 或可靠的参数传递；任务正文通过工具支持的 stdin、文件或会话输入，不拼接不可信 shell 片段。
+4. 保存实际命令、交互方式、工作区、所属主机与工具任务/会话 locator；有文件交接时由 Lead 补记到 TASK，执行者写 REPORT 并返回任务标识、状态、报告位置和一句话摘要。只有文本返回时由 Lead 按 <Path>{roots.references}/coordination/session-files.md</Path> 原样捕获。进程退出后记录真实退出码，仍运行或未知时据实记录；没有可靠提供的模型、用量或成本写为未知。交付前按派遣文件合同主动定位原始历史，核验主机、会话对应关系与可读性，附真实入口和本任务检索范围；无法核验时说明原因，不猜缓存路径。
 5. 交互提示、等待、取消和恢复按该 CLI 当前指南处理。调用结果不明先查询，不把缺日志解释为没有执行，也不重复可能已经发生的外部动作。
 
 CLI 退出码只说明调用结果。Lead 仍按 <Path>{roots.references}/coordination/result-and-recovery.md</Path> 检查真实候选、测试、findings 和完成门。该方式不要求 Speculo 常驻服务或专用 runner。

package/template/references/coordination/modes/herdr.md

@@ -1,12 +1,27 @@
 # Herdr 编排
 
-仅在当前任务选择 Herdr 时读取。先读取实际可执行文件提供的当前 skill/help，核对版本、来源、运行上下文与目标会话。不同 fork 或同名工具不推定兼容。
+仅在用户为当前任务明确选择 Herdr 时读取；选择可来自同范围仍有效的会话授权。plan 只说明接入步骤，不安装、不启动。Herdr 选择不隐含 worktree、模型或拓扑选择。
+
+## 按需安装项目 Skill
+
+当前 Lead 负责首次接入，项目根由调用 Work 已验证的 projectRoot 确定，不取 pane cwd 或方法安装根。
+
+1. 检查项目 `<Path>{roots.skills}/herdr/SKILL.md</Path>`（标准布局为项目 `.agents/skills/herdr/SKILL.md`）。存在且为有效 `name: herdr` 的完整 Skill 时先读取并复用，核对来源和兼容性；不因上游更新静默覆盖。符号链接、同名非 Skill、无效内容或归属冲突时保留原文件，仅阻塞安装分支，说明冲突位置与恢复方式。
+2. 缺失时从指定上游 [Herdr SKILL.md](https://github.com/NAMEWTA/wta-skills-hub/blob/main/skills/automation/herdr/SKILL.md) 获取 Skill。先解析 main 的实际 revision，再从该 revision 下载 `skills/automation/herdr/` 的完整内容；当前上游为单文件，未来若有相对资源依赖须完整获取，不能只保存 GitHub HTML 页面。
+3. 使用宿主可用的 Skill 安装器并显式指定项目 `.agents/skills/` 为目标；没有安装器时用宿主下载和文件工具完成同一流程。先在临时位置检查 UTF-8 Markdown、YAML frontmatter、`name: herdr`、引用闭包及路径，再以不覆盖方式安装。保留上游原文、frontmatter、许可和文件模式，不重写命令或权限参数。下载/校验失败时不留下半成品正式目录；目标期间发生变化时停止，不覆盖重试。
+4. 安装后回读实际 Skill，核对内容摘要与候选一致，在当前 Work 已有 Evidence/报告或会话结果中记录上游 URL、revision、内容 SHA-256、目标和结果。没有报告就不为安装制造 change 或 receipt。此 Skill 是项目第三方资产，不加入 Speculo 的投影清单，也不由 init/refresh 更新或删除。
+
+用户选择并要求使用 Herdr 时可完成上述项目本地安装；持久配置本身不是新安装授权。安装 Skill 不等于安装 Herdr 二进制、登录账户或启动服务。缺少网络或写权限时只阻塞 Herdr 分支，给出原目标和缺失条件；重试前重新检查目标，不能自动换另一种执行方式。
+
+## 运行与返回
+
+安装或复用后必须读取项目内 Skill，再检查 `HERDR_ENV=1`；不满足就停止 Herdr 控制，说明需要从受管会话恢复。检查通过后读取本机 `herdr --help` 和所需命令组帮助，核对版本、来源、运行上下文与目标会话。不同 fork 或同名工具不推定兼容。宿主技能列表是否已刷新不替代读取真实项目文件；也不把安装成功报告成运行可用。
 
 1. 遵守当前指南对 Herdr 环境和会话操作范围的要求。若当前环境无法控制目标，只阻塞此任务方式；不接管其他前台会话。
 2. 根据用户指定的编程工具和模型，在指南支持的范围内选择调用。Herdr 是编排方式，不是模型；不得固化某家 CLI 的参数。
 3. 使用实际返回的 pane/session 标识，确认对应项目和工作区，等待当前指南定义的就绪条件。不要默认切换用户焦点。
-4. 每个任务使用能明确归属的目标会话，并按 <Path>{roots.references}/coordination/task-brief.md</Path> 提供输入。前一任务尚未结束时，不将其活动或 idle 信号误认成新任务的完成。
-5. 通过工具当前支持的返回读取方式取得结果。遵守其输入/文件交付要求，不为 Speculo 额外强制一份结果文件。
+4. 每个任务使用能明确归属的目标会话，并按 <Path>{roots.references}/coordination/task-brief.md</Path> 提供输入。有 change 时提供已保存 TASK 和准确 REPORT 位置，记录编排 session/task 对应的真实 pane/会话与主机；独立工作区先核对文件可读写。前一任务尚未结束时，不将其活动或 idle 信号误认成新任务的完成。
+5. 通过工具当前支持的返回读取方式取得结果。有文件交接时按 <Path>{roots.references}/coordination/session-files.md</Path> 交回 REPORT 及“任务标识、状态、报告位置、一句话摘要”；只能返回文本时由 Lead 原样捕获并标明来源。交付前主动查询执行 CLI 的实际会话记录，核验主机、真实入口、会话 ID 与可读性，限定本任务范围；不把 pane 标识或终端输出冒充完整 JSONL，无法核验时说明原因。输入、提问和通知仍遵守工具原生接口。
 6. 超时或投递结果不明时先检查原目标，不盲目重发。取消按当前工具说明进行；不要宽泛结束所有 pane 或服务。
 
 任务完成、会话空闲、会话保留是不同事实。只有确认本任务不会继续冲突写入，并由 Lead 完成原验收，才释放业务占用、更新原 Evidence 和继续下一任务。

package/template/references/coordination/modes/orca.md

@@ -1,13 +1,36 @@
 # Orca 编排
 
-仅在当前任务选择 Orca 时读取。先读取本机当前版本提供的 Orca CLI 与 orchestration 指南；使用指南指向的实际命令。记录实际版本、指南来源和任务 locator，不在 Speculo 内固定 agent、模型或 runner 列表。
+仅在用户为当前任务明确选择 Orca 时读取；选择可来自同范围仍有效的会话授权。plan 只说明接入步骤，不安装、不启动。Orca 选择不隐含 worktree、模型或拓扑选择。
+
+## 按需安装项目 Skill
+
+当前 Lead 负责首次接入，项目根由调用 Work 已验证的 projectRoot 确定，不取终端 cwd、桌面客户端路径或方法安装根。
+
+1. 检查项目 `<Path>{roots.skills}/orca/SKILL.md</Path>`（标准布局为项目 `.agents/skills/orca/SKILL.md`）。存在且为有效 `name: orca` 的完整 Skill 时先读取并复用，核对来源和兼容性；不因上游更新静默覆盖。符号链接、同名非 Skill、无效内容或归属冲突时保留原文件，仅阻塞安装分支，说明冲突位置与恢复方式。
+2. 缺失时从指定上游 [Orca SKILL.md](https://github.com/NAMEWTA/wta-skills-hub/blob/main/skills/automation/orca/SKILL.md) 获取 Skill。先解析 main 的实际 revision，再从该 revision 下载 `skills/automation/orca/` 的完整内容；当前上游为单文件，未来若有相对资源依赖须完整获取，不能只保存 GitHub HTML 页面。Skill 指向的 Orca 内置指南由实际 CLI 提供，不是缺失的本地资源。
+3. 使用宿主可用的 Skill 安装器并显式指定项目 `.agents/skills/` 为目标；没有安装器时用宿主下载和文件工具完成同一流程。先在临时位置检查 UTF-8 Markdown、YAML frontmatter、`name: orca`、引用闭包及路径，再以不覆盖方式安装。保留上游原文、frontmatter、许可和文件模式，不重写命令或权限参数。下载/校验失败时不留下半成品正式目录；目标期间发生变化时停止，不覆盖重试。
+4. 安装后回读实际 Skill，核对内容摘要与候选一致，在当前 Work 已有 Evidence/报告或会话结果中记录上游 URL、revision、内容 SHA-256、目标和结果。没有报告就不为安装制造 change 或 receipt。此 Skill 是项目第三方资产，不加入 Speculo 的投影清单，也不由 init/refresh 更新或删除。
+
+用户选择并要求使用 Orca 时可完成上述项目本地安装；持久配置本身不是新安装授权。安装 Skill 不等于安装或升级 Orca、登录账户、配对远端或启动服务。缺少网络或写权限时只阻塞 Orca 分支，给出原目标和缺失条件；重试前重新检查目标，不能自动换另一种执行方式。
+
+## 运行与返回
+
+安装或复用后必须读取项目内 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 或远端可用。入口、权限或目标能力失败时保留原错误，只阻塞此方式，不静默切换生产/开发版或本地/远端入口，不自行安装升级或重启服务。
 
 1. 确认用户项目、当前工作区以及当前 Lead 的责任。需要保留 Lead 连续推进时使用受监督任务方式；完整 handoff 会转移责任，只有用户明确选择该交接时才使用。
-2. 沿当前工具提供的任务、工作区、会话和消息接口建立目标。Orca 管理的 worktree 由 Orca 操作；允许工具支持的 folder workspace，不凭空要求所有项目必须有 Git worktree。
-3. 使用 <Path>{roots.references}/coordination/task-brief.md</Path> 的真实入口和任务说明。保存工具返回的任务/尝试/session locator；不要以标题猜句柄。
-4. 区分投递已接收、任务开始、任务返回、写入停止和业务验收。工具已有生命周期由工具管理，不再建调度器。
-5. 处理该任务的 question、完成及升级请求；已有权威答案由 Lead 回答，额外权限或产品决定再交用户。确认已处理必要消息后才按工具合同确认收件。
-6. 状态不明时重读任务和收件事实。旧句柄失效时按当前指南查询，不同时向旧、新目标重复发送。
-7. 接收、取消、保留或释放工作区按当前指南及真实授权操作。释放不等于取消，完成消息不等于旧写入者已经停止。
-
-核对返回和候选后按 <Path>{roots.references}/coordination/result-and-recovery.md</Path> 接续原 Goal。工具或所需能力不可用时准确报告当前阻塞，不自行安装升级。
+2. 沿当前工具提供的任务、工作区、会话和消息接口建立目标。Orca 管理的 worktree 由 Orca 操作；允许工具支持的 folder workspace，不凭空要求所有项目必须有 Git worktree。工具和模型沿用户选择及当前指南确定，不固化 agent/runner 清单；保留用户焦点，不复用 Herdr 参数。
+3. 使用 <Path>{roots.references}/coordination/task-brief.md</Path> 的真实入口和任务说明。有 change 时先保存 TASK，提供 REPORT 位置；记录编排 session/task 对应的 Orca Run、Task、Dispatch、终端及 provider 会话中实际存在的 locator 和所属主机，不以标题猜句柄。
+4. 区分投递已接收、任务开始、任务返回、写入停止和业务验收。Run、Task、Dispatch 与终端、工作区分别使用真实返回的身份；已有 Run/Dispatch 按指南恢复，不重复创建。工具已有生命周期由工具管理，不再建调度器，也不用其他 subagent 工具冒充 Orca 派遣。
+5. 处理该任务的 question、完成及升级请求；已有权威答案由 Lead 回答，额外权限或产品决定再交用户。报告保存后按当前原生完成协议发送摘要与报告位置；支持 report-path 时传真实路径。REPORT 的 completed/blocked/failed/cancelled 不直接代替 Orca 的 outcome 参数；按本版 worker 协议提交原 Task/Dispatch 的结果，已结算的不再补写第二次完成。处理必要消息与资源归属后才确认收件，不因超时重建同一问题。
+6. 状态不明时重读原任务、回执和收件事实；只有本版支持同请求重放且原参数可核对时才恢复原操作。旧句柄失效时重新发现目标，不同时向旧、新目标重复发送。idle、无输出、断线或清单缺项均不能证明任务结束。
+7. 接收、取消、保留或释放工作区按当前指南及真实授权操作。结算后复用、保留或释放资源，运行中取消使用精确目标的原生停止流程；不以关闭终端、全局 reset 或删除工作区代替结算。完成消息不等于旧写入者已经停止。
+
+核对返回、实际候选和写入停止事实后，由 Lead 按原验收更新 Evidence，并按 <Path>{roots.references}/coordination/result-and-recovery.md</Path> 接续原 Goal。工具或所需能力不可用时准确报告当前阻塞。
+
+## 聚焦交接与历史
+
+按 <Path>{roots.references}/coordination/session-files.md</Path> 在报告中保存简短交接和原始会话入口。借鉴 Focused handoff：先读最近摘要与当前工作区，仅在细节不足时检索原会话；这是历史上下文交付，不自动转移 Leader 所有权或 resume 原 provider 会话。
+
+执行者交付前主动从当前版本的会话元数据或历史接口定位 transcript/history locator 与 provider session ID，Lead 用真实派遣句柄补充。按派遣文件合同核验所属主机、真实入口、会话对应关系和可读性，并记录本任务范围；无法核验时说明原因。需要搜索时先按当前指南检查历史索引是否启用，再在正确主机上按实际会话 ID 查找，结合任务关键词、执行路径或时间缩小范围；索引未启用就记录搜索不可用，不自行开启，仍可核验工具已提供的原始入口。SSH 转发 CLI 的搜索主机可能是控制端，路径过滤不等于切换主机。原记录缺失时可保留带来源与范围的终端节选，但必须明确是节选，不能称为完整会话或伪造 JSONL。

package/template/references/coordination/result-and-recovery.md

@@ -4,11 +4,13 @@
 
 ## 接收
 
-1. 从原 Goal/Evidence 找到当前任务、实际 Work、输入、工作区、基线、owner 和工具 locator。返回必须对应同一目标；过时结果保留为历史材料，不能覆盖当前决定。
+1. 从实际存在的原 Goal、Ticket Evidence、Direct Spec Evidence 或当前审查输入找到任务、实际 Work、工作区、基线、owner 和工具 locator；缺 Goal/Ticket 不要求补造。有文件交接时按 <Path>{roots.references}/coordination/session-files.md</Path> 回读 TASK 与 REPORT，核对 session/task、实际工具尝试和候选身份，先看聚焦交接。需要回查历史时先确认记录主机与本端访问能力，再检索本任务片段；执行者的核验声明不等于接收端已能读取。返回必须对应同一目标；过时结果保留为历史材料，不能覆盖当前决定。
 2. 通过当前工具指南核对任务是否确实返回，以及是否仍可能继续写入。已接收、已开始、会话空闲、任务结束、进程退出和业务通过分别记录；结果不明先查询，不重复发起任务。
 3. 检查实际文件和 Git 事实：基线、可达 checkpoint、tip、dirty 状态、tracked/untracked/ignored 变更以及允许路径。返回文本不能替代真实候选。
 4. 按原验收合同核对检查及输出。执行者修改测试、配置或验收脚本时，判断是否改变了通过标准，不接受伪绿色结果。自报、模拟、截图和推断在 Lead 核实前保持未验证。
-5. review/research/test-observation 的 findings、来源及命令观察由 Lead 核对后写入原工件。独立审查 required 时，审查者必须满足原 Gate；同一实现者换名称或清空会话不构成独立。Lead 自审明确标识。
+5. review/research/test-observation 的 findings、来源及命令观察由 Lead 核对后写入原工件。SpecDev 双轴审查必须核对审查者未参与本范围实现及真实派遣/返回证据；同一实现者换名称或清空会话不构成独立。Lead 参与实现时，自查只算实现活动，不满足审查完成门。
+
+REPORT 的 completed 只表示候选已交回；blocked、failed、cancelled 分别按报告事实处理，均不能直接覆盖 Ticket 或 README Outcome。Lead 在原 Evidence 保存报告指针和独立验收；后续查得的历史 locator、核验结果或快照也追加在原 Evidence，不改写执行者的报告。缺身份、状态或可核验产物时只阻塞本次验收。已提交报告的修正/重试创建新派遣目录并引用旧结果，业务上仍属于原 Ticket，不为重试新建业务票。
 
 ## 修复与集成
 
@@ -18,10 +20,11 @@
 
 ## 中断恢复
 
-- 读取 Goal Plan、当前 Ticket、Map、change 状态、最近 Evidence 和实际候选，核对当前 HEAD、输入与真实 Work 是否漂移。
-- 使用记录的工具 locator 查询原任务，不根据缺日志推断没有执行。
+- 按输入分支读取实际存在的 Goal Plan、Ticket/Map 或 Direct Spec、README Outcome、最近 Evidence 和实际候选，核对当前 HEAD、输入与真实 Work 是否漂移。
+- 使用记录的工具 locator 查询原任务，不根据缺日志或 REPORT 推断没有执行。突然中断而无报告时，由 Lead 在原 Evidence 记录已知/未知事实与恢复入口，不伪造执行者成功报告；临时文件不算完成回报。
 - 仍可能写入或副作用结果未知时，不让 Lead 或另一执行者抢写；按当前工具指南检查、等待或在原授权下取消。
 - 当前会话不具备查询能力时，说明缺失事实和恢复入口，不伪造停止证明。
+- 原历史记录不可读时保留其 locator 和缺失说明，使用报告与真实产物核验；只有缺失事实影响验收时才阻塞对应部分。回查历史不隐式恢复旧会话或授权再次执行。
 - 用户改变后续偏好时在下一安全阶段采用；撤销权限立即停止新动作并处理进行中的任务。
 - 独立且已授权的其他 frontier 可以继续；仅阻塞冲突任务及其依赖闭包。
 

package/template/references/coordination/session-files.md

@@ -0,0 +1,93 @@
+# 派遣文件与聚焦交接
+
+在已有 change 中通过 CLI、Herdr、Orca 等外部工具派遣任务时读取。首次实际派遣才创建文件；宿主原生协作按需采用，Lead 自行执行不创建虚构派遣。无 change 时使用当前 Work 已有报告位置，不补造 change。external-web 继续使用原 ZIP 交付合同。
+
+## 目录与身份
+
+SpecDev 任务目录为 <Path>{roots.state}/specdev/changes/{change}/sessions/{session}/{task}/</Path>：
+
+- `{session}` 是一轮编排，使用中性的 UTC `YYYYMMDDTHHMMSSZ`，不带 Work 或任务类型；恢复同一轮继续使用原目录，新轮次另建，同秒冲突追加最小未使用后缀 `-01`、`-02` 等。
+- `{task}` 是一次具体派遣，命名为轮内递增编号加实际主题，如 `001-code-review`、`002-research`、`003-implement` 或 `004-test-observation`。具体 Work、任务类型和 Ticket 写入 TASK。修正交付或重试使用新编号并引用前次报告，不增加 attempt 子目录，不覆盖旧输入与结果。
+- 两种目录标识只使用字母、数字、连字符；由 Lead 分配，不从未经检查的标题直接拼路径。确认目录在当前 change 内、无链接跳转且未被占用。
+- 编排 session/task 与工具的 Run、Dispatch、pane、conversation ID 分开；工具定位信息记录真实返回值和所属主机，不猜句柄。
+
+每个任务通常只有两份文件：Lead 写 <Path>{roots.state}/specdev/changes/{change}/sessions/{session}/{task}/TASK.md</Path>，执行者写 <Path>{roots.state}/specdev/changes/{change}/sessions/{session}/{task}/REPORT.md</Path>。不另建 session 总表、状态 JSON、心跳文件或聊天流水。
+
+原 Evidence 或当前 Work 工件引用这两份文件及 Lead 的验收结论，不复制整份输入、报告或第二套业务状态。持久导航同时绑定稳定 change 身份与 change 根相对 locator，归档后按该 change 的唯一实际位置解析，不能仅依赖旧活动目录。其他领域仅在其 Work 已拥有的产物位置使用同一交接内容，不接管 SpecDev namespace。
+
+## 输入与文件所有权
+
+Lead 将当前交接说明要求的必要上下文写入 `TASK.md`，使用以下五组内容，按需引用原件，不抄整套规格：
+
+| 内容 | 必需事实 |
+|---|---|
+| 身份与目标 | session/task、implementation/review/research/test-observation、change/Ticket（实际存在时）、Lead、执行者和成功定义 |
+| 输入 | 真实 Work/Skill 入口、必要规格和依赖产物、已锁定决定；前序背景引用原报告与其中的历史入口 |
+| 工作区与范围 | current/required、真实执行位置与基线、允许/只读/共享路径及 owner、已获授权的动作、停止条件 |
+| 验收 | 要运行的检查、可观察通过标准、未在执行者环境运行的 Gate 及其 owner |
+| 返回与通信 | 准确报告位置、提问/通知的工具原生通道、实际调用方式与工具句柄；尚未取得的句柄由 Lead 在调用返回后补记 |
+
+TASK 的返回要求必须包含：
+
+> 交付前主动定位本次会话的原始历史记录，核对所属主机、会话 ID 和可读性，在 REPORT 中记录真实路径及本任务检索范围。无法取得时说明原因，不猜测路径。报告正文应能独立说明结果，不要求接收方先读完整聊天。
+
+Lead 在派遣前形成完整输入、检查并写入，再回读确认后投递。输入正文此后保持稳定，只允许补记实际调用句柄/时间；目标、基线或权限实质变化时建立新任务并保留旧任务。普通澄清通过原生通道回答，影响结果的答复写入报告。
+
+派遣前确认执行者能读输入和必要材料，且能交付报告。独立工作区需要明确实际可读输入和可写报告位置；只有工具返回文本时，由 Lead 原样捕获到正式报告，标注 `Captured-by: Lead` 和原始消息 locator，不补造执行者的验证结果。执行者和 Lead 不同时写同一报告。
+
+只读任务仅可写被明确分配的报告及允许的测试产物，业务文件仍只读。报告路径不同允许独立交付，不放宽 current 的单一代码 writer 约束。所有文件先完成候选内容，再使用可用的同目录临时文件与不覆盖目标的原子落盘方式，写前检查目标未被占用、写后回读；已有正式报告不覆盖，发现冲突交 Lead 处理。未完成的临时文件不是报告，也不能作为完成信号。
+
+## 报告与通知
+
+执行者交回任务时一次性写完整 `REPORT.md`，首部用普通 Markdown 字段明确身份和状态，不要求 YAML/JSON。以下是模板，正文占位说明须替换为实际事实：
+
+```markdown
+# 任务回报
+
+Session: 本轮编排标识
+Task: 本次派遣标识
+Status: completed / blocked / failed / cancelled（仅保留实际值）
+
+## 聚焦交接
+用三至五句话说明完成内容、关键决定、当前停点和下一安全动作。
+
+## 产物与验证
+- 修改或成果：真实文件、checkpoint/commit、dirty 状态或其他产物位置。
+- 验证：命令、退出码、执行环境和实际观察；研究列来源，审查列 findings。
+- 未完成或未验证：实际事项；没有则写“无”。
+
+## 问题与下一步
+阻塞/失败/取消的事实、已尝试内容、需要谁提供什么及恢复条件；无问题写“无”。
+
+## 历史会话
+- 工具与主机：实际工具、记录所属主机。
+- 会话 ID：工具提供的真实标识。
+- 原始记录：所属主机上的实际绝对路径，或工具原生历史入口。
+- 核验：由谁、在哪台主机确认了会话对应关系和可读性；未核验项及原因。
+- 本任务范围与检索线索：消息/时间范围、关键函数或错误信息等关键词。
+```
+
+| Status | 表示什么 |
+|---|---|
+| completed | 执行者完成分配范围并交回候选，仍待 Lead 验收 |
+| blocked | 缺输入、权限、依赖或决定，说明恢复所需条件 |
+| failed | 本次尝试失败，保存已产生的产物和失败事实 |
+| cancelled | 本次派遣按实际指示取消，记录已发生影响和停止情况 |
+
+进行中问题与进度使用工具原生通道，不反复刷新报告。`blocked` 是交回本次派遣；正常提问并等待答复仍在原任务中进行。同一报告的状态不流转，后续修复/重试建立新任务；旧执行者是否停止仍按真实工具核对。
+
+文件回读成功后，通过当前工具原生通道返回“session/task、Status、报告位置、一句话摘要”；原生生命周期参数遵守工具当前指南，不直接把上述枚举塞入工具不支持的字段。工具结果不明或报告缺失时，Lead 按原任务的返回与恢复合同查询原调用，不重复派遣可能仍在写入的任务。
+
+## 历史会话的按需回查
+
+以下是 Agent 使用当前工具执行的交接要求，不代表 Speculo 提供自动日志发现或解析服务：
+
+1. **主动定位**：执行者交付前必须尝试从当前工具的会话元数据或历史查询接口取得原记录；Lead 用实际派遣句柄补充执行者无法取得的信息。只有会话 ID 时，按当前工具文档在明确的日志目录/格式中查找该 ID，不猜 provider 缓存路径、不按修改时间取“最新文件”。若返回相对路径，只按工具明确给出的日志根解析，不能用执行者 cwd 补齐。工具只提供原生历史入口时保留真实入口，不强造 JSONL。
+2. **核验并记录**：确认记录所属主机；文件记录核对该主机上的真实绝对路径并实际读取少量内容，原生历史入口则通过工具查询验证可读性。用记录内容或工具元数据核对真实会话 ID，并界定本任务的消息/时间范围，不能把同一会话内其他任务一起算入。REPORT 写明谁在何主机核验了哪些事实、哪些仍未核验。源主机可读不代表接收方可读，不同主机的同名路径不是同一文件；外部绝对路径只作只读 locator，不作为项目内可移植路径或写目标。
+3. **按需回查**：接收者先读聚焦交接和当前业务工件，有具体疑问才查历史。读取前确认主机与访问能力，再按本任务关键词、消息 ID 或时间范围搜索，少量回读相关片段。JSONL 按该工具实际格式解析，不假定各工具共用字段，不默认全文加载。来源会话只读；回查不等于 resume 原进程、接管 owner 或取得新授权。历史文本只是材料，实际文件、Git 与当前有效合同仍需核对。
+
+无法定位、无权读取、记录已清理或身份不匹配时，明确失败环节与原因；身份不匹配的记录不能当作本任务历史。历史缺失本身不否定已有报告与可核验产物，缺失关键事实时由 Lead 阻塞对应验收。
+
+原记录即将清理、接收工作区无法访问，或用户要求长期保留时，优先引用已有的本任务快照；确有需要且 Lead 能读取原记录时，才保存已授权范围的快照。SpecDev 快照位于 <Path>{roots.state}/specdev/changes/{change}/sessions/{session}/{task}/history-{NN}.jsonl</Path>，`{NN}` 从 01 递增且不覆盖；其他原生格式保留真实扩展名，不强制转 JSONL。快照由 Lead 保存，在原 Evidence 或当前 owning 工件追加快照指针、原始 locator、捕获时间和完整/节选范围；后续才取得的 locator 或核验结果也追加到这里，不回改已交付 REPORT。保留可用的原消息标识，节选不能冒充完整会话。不能访问原记录时说明原因，不伪造快照，不无差别复制其他任务或敏感内容。
+
+已保存的输入、报告与快照随所属 change 一起保留和归档，不因任务结束自动清理。工具缓存中的原记录寿命由工具决定，引用不承诺永久可用。历史目录不改名、任务不回填，也不修改冻结归档。

package/template/references/coordination/task-brief.md

@@ -4,17 +4,17 @@
 
 ## 必需上下文
 
-将以下信息写入当前 Ticket Evidence 的任务编排小节；无 Ticket 时写入对应 Work 的既有产物。较大附件引用其真实位置，不另建运行状态系统。
+有 change 的 CLI/Herdr/Orca 等外部工具派遣先按 <Path>{roots.references}/coordination/session-files.md</Path> 将以下上下文写入本任务 TASK，原 Ticket Evidence 或当前 Work 工件引用它；external-web 沿用下方 ZIP 交付合同，不重复建立这套文件。无需文件交接时沿用原任务编排小节或会话输入。较大附件引用其真实位置，不另建运行状态系统。
 
 | 内容 | 要求 |
 |---|---|
 | 身份 | Goal、change、Ticket 或固定候选；跨 change 使用 `<change>::<ticket>` 区分同名票 |
 | 能力 | 实际 Work 业务 ID、可读取的 SKILL.md 和本次阶段；原 source/合同摘要可用于发现漂移 |
 | 输入 | 目标、IN/OUT、已锁定决定、必要 Spec、依赖 Evidence、当前基线或固定审查 SHA |
-| 项目 Skill | implementation 必须提供 Tickets Map、适用 `ALL`/本票的项目 Skill 和当前 Ticket；读取顺序为 Map → 项目 Skill → Ticket，矩阵是最低必读集合 |
-| 工作区 | Goal 选择的 current 或 required、真实路径/branch、parent/base、允许和共享写路径及 owner |
-| 调用 | 用户选择的 Orca、Herdr 或 CLI；实际工具、模型已知值及会话 locator，不记录秘密 |
-| 边界 | 本次真实允许的动作、实现 commit 权限、检查、E2E owner、停止条件和返回要求 |
+| 项目 Skill | Ticket implementation 提供 Map → 适用 `ALL`/本票的项目 Skill → Ticket，矩阵是最低必读集合；Direct Spec 提供唯一获批规格、项目 Agent 指令、命中的项目 Skill、AC/验证与路径合同，不制造 Ticket/Map；review 提供固定候选及对应轴的来源 |
+| 工作区 | 有效计划或当前 Work 选择的 current 或 required、真实项目根与执行路径/branch、parent/base、允许和共享写路径及 owner；不要用执行者 cwd 猜测方法或数据根 |
+| 调用 | 当前宿主正常执行，或用户明确选择的 CLI 交互/调用、Herdr、Orca；实际工具、模型已知值、所属主机及会话 locator，不记录秘密；文件交接明确 session/task 与原生句柄的对应关系 |
+| 边界 | 本次真实允许的动作、实现 commit 权限、检查、E2E owner、停止条件、可观察验收标准、准确报告位置与原生提问/通知通道 |
 | 父 Goal | 存在父 Implementation Map/Plan 时附实际 revision、组合 task ID、依赖 Gate、并行上限和集成次序 |
 
 缺少必要输入、必需 Skill 不可读、Ready 未满足、owner 冲突或权限不足时，仅阻塞受影响任务。不能根据文件中的“approved”生成授权。
@@ -23,13 +23,15 @@
 
 交给执行者的说明必须明确：
 
-> 先读绑定的真实 Work SKILL.md，按 task 上下文只处理指定目标、阶段和工作区。遵守同一 Work 的方法、TDD、检查与质量门；不要成为 Lead，不递归启动 Goal，不修改正式 Ticket、Map、Goal Plan、Evidence、业务状态或授权。不擅自再交接任务。缺输入、发生冲突或需要额外权利时向 Lead 返回问题与证据。
+> 先读绑定的真实 Work SKILL.md，按 task 上下文只处理指定目标、阶段和工作区。遵守同一 Work 的方法、TDD、检查与质量门；不要成为 Lead，不递归启动 Goal，不修改正式 Ticket、Map、Goal Plan、Evidence、业务状态或授权。宿主原生协作仍受本次写集、单 writer 和权限约束；不擅自跨 CLI 再派单或扩大任务。缺输入、发生冲突或需要额外权利时向 Lead 返回问题与证据。
 
-Lead 自行执行使用同一 Work 的 lead 上下文；不伪造外部任务或独立审查记录。任务执行者返回材料，由 Lead 维护正式工件。
+采用 TASK/REPORT 交接时，TASK 还必须包含派遣文件合同中的历史定位指令：交付前主动查找并核验本次会话的主机、真实入口、会话 ID、可读性与本任务范围；无法取得的事实说明原因，不猜测路径。
+
+Lead 自行执行使用同一 Work 的 lead 上下文；不伪造外部任务或独立审查记录。任务执行者返回材料；采用 TASK/REPORT 交接时只写获准产物与自己的 REPORT，不写 TASK 或正式 Evidence，其他方式按原返回合同交付。正式业务工件由 Lead 维护。前序背景优先引用已有报告的聚焦交接，细节不足再按其中历史入口检索。
 
 ## 任务类型与返回
 
-- implementation：只改分配路径，按 Goal 执行 current 或 required 流程；返回实际修改、checkpoint/commit（已授权且适用时）、dirty 状态、命令及退出码、非 E2E 检查、未运行项和 blocker。
+- implementation：只改分配路径，按有效计划或当前 Work 合同执行 current 或 required 流程；返回实际修改、checkpoint/commit（已授权且适用时）、dirty 状态、命令及退出码、非 E2E 检查、未运行项和 blocker。
 - review：只读固定候选，返回 findings、位置、依据、影响和未验证项；不直接修改通过标准或正式 Evidence。
 - research：返回来源、观察、结论及不确定性，关键外部 claim 对应具体来源。
 - test-observation：运行或观察原任务允许的检查；遵守缓存/产物路径，只返回事实，不接管 E2E Gate。

package/template/workflows/specdev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specdev
-description: "用于需求澄清、规格、任务规划、实现、审查和交付的工程协作；只读发现不启动 Goal。"
+description: "用于需求澄清、规格、任务规划、实现、审查、交付及项目与参考资料学习的工程协作；只读发现不启动 Goal。"
 metadata:
   speculo-kind: domain-skill
   speculo-id: domain/specdev
@@ -26,7 +26,7 @@ metadata:
 - **specdev/grill-with-docs** — Change 决策访谈：<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>
 - **specdev/implement** — 实现与验收：<Path>{roots.workflows}/specdev/specdev-i-implement/SKILL.md</Path>
 - **specdev/init-setup** — 初始化设置：<Path>{roots.workflows}/specdev/specdev-i-init-setup/SKILL.md</Path>
-- **specdev/learn-change** — Change 学习：给零基础新生的图解：<Path>{roots.workflows}/specdev/specdev-l-learn-change/SKILL.md</Path>
+- **specdev/learn** — 学习与图解：<Path>{roots.workflows}/specdev/specdev-l-learn/SKILL.md</Path>
 - **specdev/goal-plan** — Goal 规划与执行：<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>
 - **specdev/prototype** — 逻辑与 UI 原型：<Path>{roots.workflows}/specdev/specdev-p-prototype/SKILL.md</Path>
 - **specdev/retro** — 开发复盘：<Path>{roots.workflows}/specdev/specdev-r-retro/SKILL.md</Path>

package/template/workflows/specdev/common/rules/adr-format.md

@@ -17,20 +17,14 @@
 **Source:** LOG-### / user decision / external specification
 **Supersedes:** none / ADR-###
 
-### Context
-<缺少什么背景会让这个决定令人惊讶。>
-
 ### Decision
-<清晰、规范且可验证的结论。>
-
-### Trade-off
-<认真考虑的替代方案，以及为什么接受当前代价。>
+<用 1–3 句写清决定及重要理由；保留来源和当前 change 适用范围。>
 
-### Consequences
-<真正重要的正面、负面和风险。>
+### Context / Trade-off / Consequences（适用时）
+<只有决定与理由不足以解释真实取舍、风险或后果时才展开；没有替代方案不编造。>
 
-### Verification / Migration
-<仅在适用时出现。>
+### Verification / Migration（适用时）
+<实际需要的验证、兼容或迁移约束。>
 ```
 
 `accepted` 只表示用户已接受该决定作为当前 change 的下游合同；它不证明实现已经落地，也不代表永久知识毕业。修改已接受决定时新建 change ADR 并建立 supersedes 链，不重写历史。

package/template/workflows/specdev/common/rules/artifact-contract.md

@@ -6,7 +6,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 
 整体结论仅在 change README 顶层唯一 `Outcome: active | completed | cancelled` 行；简单任务的范围、可判定 AC、当前清单、真实验证与下一步也由 README 负责。被工具引用的章节使用唯一显式 `<a id="scope"></a>`、`<a id="acceptance"></a>`、`<a id="verification"></a>` 锚点。无 Ticket 的 Goal 只在原计划维护清单；有独立 Ticket 的进度在票及 Evidence，README/Goal/Map 不复制状态。
 
-工具用临时 `{path, section?}` 定位原文，不创建登记表。存在独立 Spec 默认读取它；仅当前合同允许且 README 等价章节完整时读取 README。两份都自称规格权威时停止裁决，不按时间挑一份。跨 change 集成、Deep、真实并行或复杂设计依赖使用完整工件，迁出位置改成导航；用户明确要求 Spec/Ticket/Goal 时照办。UI 小任务同样保留 DESIGN、具体批准及真实浏览器；LOGIC-only 保留独立验证。无需拆票的轻量任务不制造 Ticket/Map。
+工具用临时 `{path, section?}` 定位原文，不创建登记表。存在独立 Spec 默认读取它；仅当前合同允许且 README 等价章节完整时读取 README。两份都自称规格权威时停止裁决，不按时间挑一份。跨 change 集成、Deep、真实并行或复杂设计依赖使用完整工件，迁出位置改成导航；用户明确要求 Spec/Ticket/Goal 时照办。UI 小任务同样保留 DESIGN、具体批准及真实浏览器；LOGIC-only 保留独立验证。无需独立调度或追踪的任务不制造 Ticket/Map；完整获批 Spec 可直接实现，轻量 README 替代规格仍遵守原边界。执行策略见 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path>。
 
 ## 1. 工件职责
 
@@ -29,7 +29,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Implementation Plan | `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
 | Implementation Orchestration Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/implementation-orchestration.md</Path>` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
 | Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策或远程 Issue 正文 |
-| Change 学习图解 | `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实；索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
+| 学习图解 | `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` | L 负责需求参考、项目代码、已有 change 或外部资料的讲解，区分事实、观点与推断；索引按序号持续追加，未指定 change 时新建学习载体 | 产品决定、架构决定、实现授权、用户掌握结论或 Learning workflow 知识 |
 | 代码审查 | `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 项目设计基线 | <Path>{roots.state}/specdev/design/DESIGN.md</Path> | 跨 change 的语义 token、组件/交互规范、版本及来源；A 唯一正式写入 | 单次页面设计或未批准提案 |
 | Change 设计合同 | <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> | 本 change 已批准的页面、状态、视觉/交互、基线版本和例外；P 拥有 | 改写永久基线或替代 Spec/ADR |

package/template/workflows/specdev/common/rules/change-completion.md

@@ -4,9 +4,12 @@
 
 ## 完成门
 
+实现型完成必须按 <Path>{roots.workflows}/specdev/common/skills/code-review/references/review-evidence.md</Path> 有覆盖实际最终交付的独立双轴通过证据。多单元组合使用整体审查；单单元固定输入相同可复用，未提交内容使用工作副本快照。非实现学习、复盘及取消沿各自等价验收，不制造代码审查。
+
+
 一个 change 只有同时满足以下条件才能 completed：
 
-1. 所有计划内 Ticket 为 done，或因权威事实无需改动而记录为 cancelled；Direct Spec/非实现流程有等价验收。
+1. 所有计划内 Ticket 为 done，或因权威事实无需改动而记录为 cancelled；Direct Spec/非实现流程有等价验收；required Direct Spec 的执行记录必须 integrated/removed，父 HEAD 为 result 且包含 source，候选与 required 验证通过。
 2. required Ticket 有 source commit、passed candidate、父分支 result SHA，且父分支包含 source commit；current Ticket 有 implementation commit、passed direct-parent 验证和父分支 result SHA；对应 Ticket Evidence 的 workspace/集成记录均完整；不要求 JSON 镜像。
 3. 每个行为有 Lead Evidence，全部 Spec 合同与 Goal Gate 可定位。
 4. current Ticket 的 current-workspace 检查/回归和适用 E2E，或 required Ticket 的 source-worktree 非 E2E 检查、parent-candidate 集成/回归和 required E2E 已通过；not-required 有理由。
@@ -18,6 +21,8 @@ UI 实施还需 Evidence 对照已批准 change DESIGN、固定基线与页面/
 
 Evidence-only Done 和 empty commit 不满足完成门.
 
+L 新建的学习专用 change 属于非实现终点：以 README 的学习 scope、逐 AC 实际验证及 learning 图解/索引完成轻量验收，由 L 原 owner 在本轮交付后结束。已有开发 change 的学习材料不替代其实现完成门；向 completed/cancelled 对象续加学习图解不重开或重新判定原 Outcome。学习的选择与恢复由 <Path>{roots.workflows}/specdev/specdev-l-learn/SKILL.md</Path> 负责。
+
 父实现 change 还必须满足 `<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`：全部成员 completed，Implementation Map 与 Implementation Plan completed 且 revision 一致，跨 change 全套验证通过，`<Path>{roots.state}/specdev/changes/{change}/evidence/implementation-orchestration.md</Path>` 完整，没有活动派单、candidate、serialization lock 或未裁决冲突。父完成不自动归档或移动任何成员。
 
 ## 转换 Owner
@@ -54,6 +59,6 @@ A 只验证取消结果，不代替用户取消。单 Ticket cancelled 不推导
 
 无 Goal 的 owner 在 README `## Ownership` 写 `Owner` 与 `Evidence`；后者指向实际会话/交接原文或同 README 的独立证据锚点，其 `Owner` 或 `Session` 必须匹配。若动作绑定 `Work`，原证据必须同值；不是每 Work 调用登记。
 
-取消在 README `<a id="cancellation"></a>` 下保留 `Source`、`Scope`、`Time`（实际 ISO 时间）、`Confirmed-By`（原 owner）、`Undelivered`、`Landed`、`Writers`、`Dependencies`、`Checkpoints`、`External`、`Next`。Source 指向真实取消决定原件或同 README 的独立原请求锚点，不能以取消结论自证。Writers 为 `none: <依据>` 或 `stopped: <停止/交接证据 locator>`；后者原件须有 `Writers: stopped` 与真实 Observed。Dependencies/Checkpoints/External 使用 `none|resolved|transferred|waived: <处置依据>`，不能把未知写成已解决。活动/review/integrating/blocked 的执行记录仍须原 owner 处置，不由取消声明抹掉。
+取消在 README `<a id="cancellation"></a>` 下保留 `Source`、`Scope`、`Time`（实际 ISO 时间）、`Confirmed-By`（原 owner）、`Undelivered`、`Landed`、`Writers`、`Dependencies`、`Checkpoints`、`External`、`Next`。Source 指向真实取消决定原件或同 README 的独立原请求锚点，不能以取消结论自证。Writers 为 `none: <依据>` 或 `stopped: <停止/交接证据 locator>`；后者原件须有 `Writers: stopped` 与真实 Observed。Dependencies/Checkpoints/External 使用 `none|resolved|transferred|waived: <处置依据>`，不能把未知写成已解决。Ticket 或 Direct Spec 的 active/review/integrating/blocked 执行记录仍须原 owner 处置，不由取消声明抹掉。
 
 独立 Spec 的无票 Direct Spec 使用原 evidence/direct-spec 的 `## Acceptance Verification` JSON array 逐 AC 回读实际结果：id/result/method/source/observed；command 存在时 exit 为 0，外部 evidence 引用须有匹配 sha256，内联观察无需另建文件。空 Evidence、仅标题或 passed 自评不通过。`--stage complete` 只判本地完成；A 移动前使用 `--stage archive-ready` 同时核对对应 completed/cancelled 门和已承诺远程交付，目标移动后再使用 archived。

package/template/workflows/specdev/common/rules/domain-runtime.md

@@ -6,7 +6,7 @@
 
 1. 明确项目根、方法资源根与获批业务数据根。已有安装时验证真实 workspace 与 roots；没有安装时使用明确根参数，方法资源可以只读。相对参数基于项目根，cwd 只作线索；不静默切换项目。根冲突、越界链接或重叠安装事务仅阻塞依赖该根的写入。详见 <Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>。
 2. 读取当前请求和所选 Work；按 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path> 检索相关知识 ID/关键词，再回读少量原文与 provenance。没有相关知识不要求先初始化知识目录。
-3. 有 change 时定位用户指定对象或唯一合法候选，读取 README 的唯一 Outcome、当前负责工件和接续点。只枚举 changes 直接子目录，排除 archive；多个候选真实消歧。只读代码/架构审查、知识审计、capture 和初始化不强造 change。
+3. 有 change 时定位用户指定对象或唯一合法候选，读取 README 的唯一 Outcome、当前负责工件和接续点。只枚举 changes 直接子目录，排除 archive；多个候选真实消歧。L 学习按其保存合同使用指定/同轮续学对象，独立请求未指定时新建学习 change，不自动接入其他活动对象。只读代码/架构审查、知识审计、capture 和初始化不强造 change。
 4. 按实际分支读取必要参考。创建、恢复、完成、取消或归档时读取 <Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path>；轻量/完整输入或事实冲突读取 <Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>；实际交接、并行、父子集成才加载 <Path>{roots.workflows}/specdev/common/rules/operating-governance.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>。
 5. 写前核对路径、原 owner、实际写入者、相关 pending transaction、lock 和 recovery evidence。失败/阻塞记录在原 README、计划、Evidence 或操作回执；真实交接只更新原负责位置。完成产物、适用验证并回读，返回证据和下一入口。
 
@@ -16,7 +16,7 @@
 
 小请求使用 README 中等价范围、AC 与验证；用户明确要求 Spec/Ticket/Goal 时交付指定工件。复杂需求可经 W → G → S → T → P → I 逐步形成合同，不要求全部 Work 串行必跑。Ticket frontmatter 拥有本票状态、依赖、写集与 Skill binding；有票的 Map/Goal 只管导航、依赖、Gate、集成和恢复，无票 Goal 由计划清单负责进度。整体结论只在 README，归档事实只在目录位置与回执。
 
-真实使用的 Spec/Ticket/Map/Goal、DESIGN、调查、远程账本 schema 与验证继续有效。并发上限、worktree 与集成尝试策略只在实际启用时由原 Goal/项目约定提供来源；缺省 current 单写入者、严格串行/direct-parent。Lead 自己实现也计入实现并发，只读 review/research/test-observation 不新增数字上限。GitHub labels 等实际工具配置仅对应分支读取；未知配置保留，缺标签只阻塞有关远程写入。
+真实使用的 Spec/Ticket/Map/Goal、DESIGN、调查、远程账本 schema 与验证继续有效。并发上限、worktree 与集成尝试策略按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path>，由实际存在的 Goal/项目约定或当前 I 原 Evidence 提供来源；缺省 current 单写入者、严格串行/direct-parent。Lead 自己实现也计入实现并发，只读 review/research/test-observation 不新增数字上限。GitHub labels 等实际工具配置仅对应分支读取；未知配置保留，缺标签只阻塞有关远程写入。
 
 UI 候选缺省 3 个，配置范围 2–4；用户明确数量覆盖默认及上限。W 每会话最多完成一张调查票。专业分支保留：R performance 先测量，D evidence-triage 不以观察冒充根因，I documentation 在原授权范围维护当前工程事实。
 

package/template/workflows/specdev/common/rules/evidence-and-verification.md

@@ -28,7 +28,7 @@ required 模式下，Lead 在最新父分支与 source commit 的 candidate 状
 
 ### Direct Spec
 
-获批 Direct Spec 不创建 Ticket worktree 或 candidate。Lead 在 current workspace 记录实施前基线，运行轻量合同要求的定向检查、适用回归与 E2E，并记录最终 checkpoint、dirty 状态、运行环境、命令、退出状态和未运行原因。E2E 仍只由 Lead 执行；不得为套用两层验证而伪造 Ticket、source/candidate/result 或父分支推进证据。
+Direct Spec 按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 独立选择工作区。current 记录实施前基线、最终 checkpoint、dirty 状态和实际检查；required 以整个 change 为单元复用上方 source-worktree/parent-candidate 两层验证，记录真实 source/candidate/result。E2E 仍只由 Lead 执行；两种模式均按完整规格覆盖全部 AC，不伪造 Ticket 或未发生的集成。
 
 低层证据不能替代明确要求的外部行为证据。高风险迁移还需要 dry-run、调用点扫描、数据核对、监控或恢复演练。
 
@@ -48,7 +48,7 @@ required 模式下，Lead 在最新父分支与 source commit 的 candidate 状
 
 required Ticket Done 必须有 source commit、通过 candidate、父分支 result 与 Lead Evidence；current Ticket Done 必须有 implementation commit、通过 direct-parent 验证、父分支 result 与 Lead Evidence。无法运行 required 验证、存在未批准偏差、父分支未包含 Ticket commit 或 Evidence 不完整时不得 Done。
 
-Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施前/最终 checkpoint、实际路径、定向/回归/E2E 命令及环境、验收映射、未运行项、偏差、残余风险和提交授权状态。
+Direct Spec Evidence 至少包含：用户实际授权与唯一获批规格、执行方式/workspace 选择、Lead、实施前/最终 checkpoint、实际路径、定向/回归/E2E 命令及环境、验收映射、未运行项、偏差、残余风险和提交授权状态；required 还包括原 Workspace Execution Record、候选集成与父分支回读。
 
 父实现 change 的 Implementation Orchestration Evidence 不能替代子 Evidence。它至少记录最终 Map revision、全部成员最终状态和子证据指针、dependency/serialization 实际顺序、跨 change 合同检查、aggregate 命令/环境/结果、stale candidate 处理、偏差和残余风险。任何成员未 completed 或整体验证未通过时不得形成父完成证据。
 

package/template/workflows/specdev/common/rules/execution-policy.md

@@ -0,0 +1,28 @@
+# 执行方式与工作区
+
+I 开始实现、P 安排执行和 dev-worktree 创建/恢复时读取。规格、执行方式、工作区独立选择；共同的工具选择与交接协议见 <Path>{roots.references}/coordination/coordination-contract.md</Path>。
+
+## 输入和选择
+
+- 获批完整 Spec 可直接进入 I；`ready_for_tickets: true` 继续表示规格已就绪，不要求真的拆票。多个行为、公共接口、迁移或高风险不单独构成强制拆票理由，相应设计、批准、验证和恢复门必须完整。
+- README 替代独立 Spec 仍限原轻量边界。用户要求独立 Spec/Ticket/Goal 时按要求交付；缺产品决定不能用执行策略补造。
+- 独立调度、依赖 DAG 或逐票追踪确有需要才使用 T；跨任务 Gate、跨 change 或用户要求总控时使用 P。已有 Ticket/父实现不能通过转称 Direct Spec 绕过未完成责任；先由原 owner 处置活动执行和证据，再改路由。
+- 没有明确执行方式时，按当前宿主正常执行，App、CLI 等均可；工作区默认 `current`。明确指定 CLI 交互、Herdr 等方式时按选择执行；复用已有明确选择，不逐层重问。只读 C 冻结原候选，不创建实现工作区。
+- 已有父 Implementation Plan 的 workspace/Gate/上限优先约束子任务；子 Goal 不得放宽。无父计划使用已有 Goal；无 Goal 时由当前 I owner 在原 Evidence 的执行上下文记录方式、workspace 策略、Lead、路径、验证、原授权来源和恢复依据，不创建 Goal。
+- 无 Goal 的实现单元默认串行，集成尝试上限为 3；有明确项目约定时记录其来源并复用更严格上限。有效计划、实际存在的执行限制和平台能力取共同上限。不为这些默认值创建 config。
+
+## 工作区
+
+`current` 在当前工作副本执行；同一时刻只有一个代码 writer，包括 Lead、原生 subagent/team 和 Herdr 执行者。派出实现任务后 Lead 等待写入结束再接收，测试、审查不读正在漂移的候选。只读任务可以并行。Ticket 继续 direct-parent 验收；Direct Spec 保留实施前/最终 checkpoint、dirty 状态与提交授权，未授权不提交，不伪造已集成。
+
+`required` 对每个独立实现单元创建 source worktree；无票时整个 Direct Spec change 就是一个单元。使用 <Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path> 的 source → parent-candidate → parent 流程，Lead 拥有集成、适用 E2E 与正式证据。创建前核对实现 commit 和本地集成授权；来源清理仍单独授权。worktree 不构成沙箱或执行锁。
+
+## 记录与恢复
+
+Ticket 沿用原 Evidence；无票使用 <Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>，其中 `Workspace Execution Record` 的 Direct Spec 记录用 `purpose: direct-spec`、`change` 与 `integration_attempt_limit` 代替 `ticket_id`，其余 workspace/integration 字段沿用现有合同。不允许两种执行记录并存。
+
+新建 Direct Spec required 必须记录真实执行对象；current 可以保留原 checkpoint 证据而不制造集成记录，历史无记录 current Evidence 仍可读取。使用结构化 current 记录时必须满足同一 commit/direct-parent 完成门。无论模式，完整 Spec 的完成需要逐 AC 的 Acceptance Verification 与实际双轴审查；未完成或未验证不能标 completed。
+
+恢复先核对原 Evidence、实际 writer、Git、候选和权限；未知结果先查询，失败候选不推进父分支。重复同一 blocker 无新证据或达到尝试上限时暂停，Lead 记录下一轮实质变化后才能重试。取消、归档不能抹掉活动 worktree 或未决 candidate。
+
+Direct Spec 整体取消时，原 owner 先按 change-completion 记录真实取消决定、已停止 writer、依赖及 checkpoint/candidate 的保留或交接；这些条件满足后才把本单元记录 status 改为 cancelled。此状态仅适用于 Direct Spec，不表示集成通过或授予清理权限；不能用于 completed。Ticket 状态格式不变。

package/template/workflows/specdev/common/rules/operating-governance.md

@@ -15,8 +15,8 @@
 10. **恢复依赖权威工件**：跨 Work 或 Agent 的实际交接在原 README/计划/Evidence 记录 owner、范围、未决动作和下一步，不维护 Work 调用镜像；返回下一 Work 和权威工件完整路径。
 11. **本地执行权威**：远程 Issue/PR/URL 只作为来源或完成投影；Spec、Ticket、Map、Goal Plan、Evidence 和状态始终以本地工件为准。
 12. **完成与归档分离**：本地完成按 change completion 合同决定；远程 close 失败不回滚完成，但必须 reconcile 或 waive 后才归档。
-13. **Lead 与隔离正交**：Lead 固定拥有原计划、Evidence 与父分支；是否派遣 任务执行者 由 Lead 动态决定。Goal Plan 创建时询问 Ticket 是否开启 worktree，默认不开启；选择只作用于当前 Goal Plan。
-14. **策略化验收**：current 模式使用当前 workspace 严格串行、direct-parent 验证；required 模式使用 source worktree 与 parent-candidate。只有 required 模式创建独立 Ticket worktree。
+13. **Lead 与隔离正交**：Lead 固定拥有原计划、Evidence 与父分支；是否派遣 任务执行者 由 Lead 动态决定。执行方式与工作区按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 独立选择，执行方式默认当前宿主正常执行，工作区默认 current；无 Goal 时由 I 在原 Evidence 承接，已有选择不重复询问。
+14. **策略化验收**：current 模式使用当前 workspace 严格串行、direct-parent 验证；required 模式使用 source worktree 与 parent-candidate。只有 required 模式创建独立实现 worktree，单元可以是 Ticket 或整个 Direct Spec change。
 15. **父子权威隔离**：父实现 change 只拥有 Ready 子 change 的组合 Ticket DAG、serialization、全局 workspace/资源和实现进度投影；子 change 继续拥有全部行为与实现合同。一个未完成子 change 只能属于一个未完成父实现 change。
 
 共享规则：