npm - @namewta/speculo - Versions diffs - 0.7.2 → 0.7.3 - Mend

@namewta/speculo 0.7.2 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (53) hide show

package/template/workflows/specdev/I-implement/I-implement.md CHANGED Viewed

@@ -3,222 +3,176 @@ id: specdev/implement
 type: workflow-entry
 workflow: specdev
 name: 实现
-description: 基于 Ready Ticket 或获批的小型 Spec 执行设计检查、TDD 红绿循环、持续验证、双轴审查、证据回写和提交。
-keywords: [实现, TDD, 代码审查, 模块设计, 证据, ticket]
+description: 基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、Ticket worktree commit、候选合并验证和 Lead Evidence 回写。
+keywords: [实现, TDD, Lead, subagent, worktree, candidate-merge, 代码审查, 证据]
 ---
 # 实现
-本 work 保留深模块设计检查、接缝和依赖分类、design-it-twice、TDD 红→绿垂直循环、隔离双轴审查、项目级验证、提交和状态更新。治理升级增加 Ready、路径所有权、Evidence、完成所有权和偏差门禁。
+本 work 保留模块设计检查、design-it-twice、TDD 红绿循环、双轴审查和证据治理。Ticket 模式固定使用来源 worktree、实现 commit 和 parent-candidate 集成；Lead 根据实际情况自行实现或动态派单。
 ## 执行模式
 ### Ticket 模式（默认）
-读取一个 Ready Ticket：
+读取 Ready Ticket、Tickets Map 和可选 Goal Plan。存在 Goal Plan 时使用其中的 Lead；没有 Goal Plan 时，当前主会话作为该 Ticket 的 Lead。每个 Ticket 都建立独立 worktree，无论实现者是 Lead 还是 implementation subagent。
-- Ticket：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
-- Tickets Map：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
-- 可选 Goal Plan：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+### Direct Spec 模式
-Ticket 模式适用于多 Ticket、Standard/Deep、并行、迁移或需要完整证据治理的工作。
+只有极小、局部、单一行为、低风险、可逆且无需 Ticket DAG 的工作，才可在用户批准后直接基于 Spec/ADR/CONTEXT 在 current workspace 执行。先确认目标、IN/OUT、唯一写入 owner、可写范围、关键不变量、验证和验收。出现公共 API/schema、迁移、安全、高风险、多个行为或并行需求时返回 T-tickets。
-新 Goal Plan 通过 `coordination_mode` 与 `workspace_strategy` 分别决定协作和工作区；旧计划缺少字段时根据完整 Delegated Execution Addendum 与现有 worktree 记录兼容推导。只有 `lead-team` 进入 delegated execution 分支；`single-session` 可使用只读辅助 Agent，但主会话保持唯一写入 owner。Worktree/mixed 独立加载 dev-worktree 合同，不因是否存在 Lead 而改变。
+## 输入
-### Direct Spec 模式（保留原能力）
+两种模式都必须读取：
-极小、局部、单一行为且不需要独立 Ticket DAG 的工作，可以在用户明确批准后直接基于：
-- Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- 架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-- 领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-执行前必须从 Spec 明确提取并向用户确认一个轻量执行契约：目标、IN/OUT、可写范围、关键不变量、验证命令和验收条件。出现公共 API/schema、迁移、安全、高风险、多个独立行为或并行需求时，必须返回 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`，不得使用 Direct Spec 模式绕过治理。
+- 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- 项目配置：`<Path>{roots.state}/specdev/config.json</Path>`
-## 通用输入
+Ticket 模式还必须读取当前 Ticket `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`；存在 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 时必须读取。Direct Spec 模式必须读取用户对轻量执行合同和直接实现的明确批准。
 按存在情况读取：
-- 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-- 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-- 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- 当前 change 架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 当前 change 领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前 change 设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- 当前 change 诊断：`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
 - 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
 - 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
-- 项目配置：`<Path>{roots.state}/specdev/config.json</Path>`
-当前 change 的架构决策或领域上下文缺失，且实现需要这些决定时，先运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 或请求用户建立上下文。永久目录可以为空，静默继续。
+永久目录可以为空，静默继续。当前 ADR/CONTEXT 缺失且实施需要对应决定时，返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；Spec、Ticket 或 Goal Plan 与代码事实冲突时按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 返回真正 owner，不在实现中覆盖。
-## 流程
+Git 已处于 merge/rebase 冲突时，先加载 `<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`；不把冲突伪装成普通 TDD。
-Git 已处于 merge/rebase 冲突时，先加载 `<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>` 并完成或可恢复地暂停该分支；不要把冲突伪装成普通 TDD 切片。
+## 流程
-### 1. 执行前预检
+### 1. 执行前预检与来源 worktree
 加载 `<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`。
-Ticket 模式检查：
-- `ready: true`；
-- 状态允许开始；
-- `blocked_by` 全部 done；
-- Ticket 与 Spec/ADR/Goal Plan 无冲突；
-- 可写、只读、共享路径明确且无并发冲突；
-- Ticket 分配到 worktree 时，记录为 `active`，trigger、`base_sha`、父分支、owners、locator 和结束动作与计划一致；
-- `lead-team` 时，派单块的 execution model、Lead、mutation role、checkpoint、workspace/session locator、路径合同、修正上限和授权矩阵与当前事实一致；`worker-write` 必须绑定独立 workspace；
-- current workspace 只有一个项目和 SpecDev 状态写入 owner；read-only Agent 不产生 patch、commit 或状态写入；
-- 验证命令和 Evidence 位置可用；
-- 当前代码事实没有使核心契约失效。
+Ticket 模式：
-Direct Spec 模式检查：
+1. 验证 Ready、依赖 Evidence、Spec/ADR/Goal Plan、一致性、路径 owner 和验证接缝；
+2. 确认 Goal Plan schema v4（若存在）、Lead、implementation agent 上限与授权；
+3. 以 `purpose=ticket, operation=create|restore` 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`；
+4. Lead 把 Ticket 设为 `in_progress`，change worktree 记录设为 `active`；
+5. 当前代码使合同失效时停止并返回对应上游 owner。
-- 用户已明确批准直接实现；
-- 单一行为、局部、低风险、可逆；
-- 轻量执行契约完整；
-- 不涉及 Deep 条件；
-- 可写范围和验证明确。
+Direct Spec 模式验证用户批准、轻量合同和 current workspace 唯一写入 owner；不创建虚假 Ticket/worktree 状态。
-失败时停止，标记 `blocked` 或 `deviated`，不得边做边补关键决策。
+**完成标准**：Ticket 来源 worktree、基线、owners、权限与实际 Git 一致；Direct Spec 的小型边界可判定。
-### 2. 设计检查
+### 2. Lead 决定自行实现或动态派单
-加载 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`，并严格使用其中的模块、接口、深度、接缝、适配器、杠杆和局部性术语。
+Ticket 模式下，Lead 根据 Ticket 独立性、路径冲突、上下文、风险和平台能力决定。派单时以 `operation=dispatch` 调用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`。Direct Spec 模式由 Lead 作为 current workspace 唯一写入 owner；可以派遣只读 review/research/test-observation agent，不派遣 implementation subagent 写 current workspace。
-在写代码前检查：
+- implementation subagent 同时最多取 Goal Plan/config/平台上限的最小值且不超过三个；Lead 不计入；
+- review/research/test-observation agent 不设置 SpecDev 数字上限，但保持只读；
+- implementation Packet 绑定唯一 Ticket worktree、checkpoint、路径、非 E2E 检查与 commit 返回；
+- subagent 不写 SpecDev 工件、Evidence、父分支或 E2E 结果；
+- Lead 自行实现时仍遵循相同 worktree、commit 与返回事实合同。
-- 目标代码属于哪些模块；
-- 每个模块的接口、类型、不变量、顺序约束、错误和性能语义；
-- 模块是否有足够深度，是否减少调用者认知；
-- 接缝在哪里，是否有真实适配器或可替换实现；
-- 依赖属于进程内、本地可替换、远程自有或真正外部依赖；
-- 测试应在哪个稳定接缝观察行为；
-- Ticket/Spec 已锁定的公共契约是否被保持。
+**完成标准**：只有一个 implementation owner 写当前 Ticket worktree，或 Direct Spec 只有 Lead 写 current workspace；所有 SpecDev 写入仍由 Lead 拥有。
-存在多个局部接口设计且不改变已锁定契约时，可以运行 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。若设计摩擦已经超出当前 Ticket 范围，返回 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>`；若方案会改变产品行为、公共接口、数据、兼容、安全或范围，返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 或相应规划工件，不使用 design-it-twice 绕过决策。
+### 3. 设计检查
-若不熟悉外部库、框架 API 或依赖能力边界，调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
+加载 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`，检查模块、接口、类型、不变量、顺序/错误/性能语义、接缝、适配器、依赖分类、测试观察点和既有公共合同。
-**完成标准**：模块深度、接口、不变量、接缝、适配器和依赖策略已检查，局部设计与上层契约一致。
+存在多个不改变上层契约的局部设计时，可运行 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。超出 Ticket 或改变产品/公共合同/数据/兼容/安全时，返回架构审查、Grill、Spec 或 Ticket owner。陌生外部依赖使用 research Skill。
-### 3. TDD 红→绿垂直循环
+**完成标准**：局部设计与上层契约一致，稳定接缝和依赖策略明确。
-加载：
+### 4. TDD 红→绿垂直循环
-- `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`
-- `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
-对每个验收行为或关键风险：
+加载 `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`。对每个验收行为或关键风险：
 1. 选择公共接口或稳定接缝；
-2. 编写会因目标行为缺失而失败的测试或可重复验证；
-3. 确认失败原因正确；
-4. 只写足以通过当前测试的实现；
-5. 运行定向验证；
-6. 保存 red/green 证据并进入下一条窄垂直切片。
+2. 编写因目标行为缺失而失败的测试/验证并确认失败原因；
+3. 只写足以通过当前测试的实现；
+4. 运行定向非 E2E 验证；
+5. 保存 red/green 事实并进入下一条窄切片。
-本循环新增或修改代码注释时，使用注释规则判断信息是否应由代码表达，并同步维护受行为变更影响的既有注释。
+不得删除测试、放宽断言、吞错、永久跳过或只验证 Mock 调用次数来制造绿色。
-不得通过删除测试、放宽断言、吞错、永久跳过或只测试 Mock 调用次数来制造绿色。
+新增或修改代码注释时，先判断信息能否由命名、类型或结构表达，并同步维护受行为变化影响的既有注释。
-### 4. 持续验证与范围审计
+### 5. 实现检查、commit 与 Lead 接收
-- 每个安全落点运行定向验证；
-- 完成前运行 Ticket 验证矩阵，或 Direct Spec 模式的轻量验证契约；
-- 按 `<Path>{roots.state}/specdev/config.json</Path>` 运行适用的类型检查、lint、测试和构建；
-- current workspace 由其唯一写入 owner 运行适用 E2E；隔离 workspace 由 integration owner 在集成阶段运行；Lead Team 的 Worker 只记录场景与预期结果；
-- 检查实际修改均在 `writable_paths` 或获批的 Direct Spec 可写范围内；
-- shared path 只由 owner 修改；
-- 越界前停止并提出 ownership change，不先改后报；
-- 记录新失败、既有失败和环境失败的区别。
+Ticket 模式的 implementation owner 在来源 worktree：
-完成当前实现审查前运行：
+- 运行 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查；
+- 审计 writable/shared/read-only 路径和新/既有/环境失败；
+- 在已授权时创建引用 Ticket ID 的实现 commit；
+- 返回 commit、dirty 状态、实际路径、命令/结果、未运行项和恢复条件。
-```bash
-node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
-  --stage implement \
-  <Path>{roots.state}/specdev/changes/{change}</Path>
-```
+Ticket 模式中，Lead 以 `operation=accept` 调用 subagent-delivery，重读 Git 状态、branch tip、commit、diff 和命令事实。无改动时将 Ticket 改为 `cancelled` 并记录原因；不得 empty commit 或 Evidence-only Done。来源 worktree 不运行 E2E。
-证据规则见 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
+Direct Spec 模式由 Lead 在 current workspace 运行轻量合同要求的定向非 E2E 检查，审计获批可写范围，并在获得 implementation commit 授权后创建引用 change 的非空 commit；无需改动时记录事实并取消直接实现，不创建 empty commit。记录实施前基线、最终 checkpoint、dirty 状态、实际路径、命令结果、未运行项和恢复条件。
-### 5. 双轴审查
+**完成标准**：Ticket worktree clean 且 `source_checkpoint` 精确等于 branch tip；或 Direct Spec 的 current workspace checkpoint、路径和轻量合同一致。
-调用 `<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`，把当前 Ticket 基线和实现 checkpoint 固定为本地 SHA。
+### 6. 双轴审查
-- **标准轴**：正确性、模块设计、代码异味、错误处理、安全、性能、并发、资源释放、测试质量和可维护性；
-- **规范轴**：对照 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、Ticket 的 IN/OUT、实现契约、路径所有权、验证矩阵和 Goal Gate。
+调用 `<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`。Ticket 模式以 `base_sha` 与 `source_checkpoint` 为固定点；Direct Spec 以实施前基线与 current workspace 最终 checkpoint 为固定点：
-标准轴同时复核步骤 3 加载的注释规则：公共 API 契约完整，内部注释只保留非显然的 Why、Invariant 和 Risk，且所有相关注释与当前行为一致。
+- 标准轴：正确性、模块设计、错误、安全、性能、并发、资源、测试与可维护性；
+- 规范轴：Spec/Ticket IN/OUT、实现合同、路径所有权、验证矩阵与 Goal Gate。
-两个轴使用隔离上下文并按标准轴、规范轴顺序写入 Evidence，不合并或跨轴重排。审查发现局部问题时进入独立修正/重构阶段，随后重跑受影响验证和 review 轴；需要改变上层契约时升级 deviation 并返回 Spec/Ticket/ADR。
+标准轴同时复核 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`：公共 API 契约完整，内部注释只保留非显然的 Why、Invariant 和 Risk，且相关注释与当前行为一致。
-### 6. Evidence 与状态
+两个轴隔离并按标准轴、规范轴顺序返回 Lead。局部 finding 在当前模式的实现 workspace 修正、创建新 checkpoint 并重跑；改变上层契约则登记 deviation。Ticket 进入 `review` 或 Direct Spec 进入最终验证前，两轴必须通过。
-Ticket 模式使用 `<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>` 写入：
+### 7. 最终集成与适用 E2E
-```text
-<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>
-```
+Ticket 模式中，Lead 以 `purpose=ticket, operation=finalize` 调用 dev-worktree：
-Direct Spec 模式写入：
+1. 在最新父分支的 Lead-owned candidate checkout 组合 source commit；
+2. 运行受影响集成/回归、项目父状态检查和 Ticket 标记 required 的 E2E；
+3. candidate 失败时父分支不动，Ticket 回 `in_progress`/`blocked`；
+4. 父 HEAD 漂移时废弃本轮 candidate，基于最新父分支重建并重跑；
+5. 全部通过后父分支 fast-forward 到 candidate/result SHA；
+6. 重读父 HEAD/tree 和 ancestor 关系后，才允许 Ticket Done。
-```text
-<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>
-```
+E2E 是否需要由 Ticket/Goal Plan 的实际跨边界风险决定，不限于 UI；不适用必须记录原因。
-Evidence 必须包含实际修改范围、命令与结果、验收逐条映射、未运行项、偏差、残余风险和提交引用。
+Direct Spec 模式跳过 source worktree、candidate merge 和父分支推进。Lead 在 current workspace 运行轻量合同要求的适用回归与 E2E，记录运行环境、命令、退出码和摘要；E2E 不得派给其他 agent。失败时不声明完成，保留最后可信 checkpoint 和恢复条件。全部通过后重读 Git 状态与最终 checkpoint。
-`lead-team` 时加载 `<Path>{roots.workflows}/specdev/I-implement/delegated-evidence-template.md</Path>`，补充 execution model、provider、mutation role、派单与最终 checkpoint、workspace/session locator、候选交付核对、修正轮次和未验证声明。Lead 使用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>` 的 `operation=execute` 分支完成核对；provider 自报结果不能直接标记为 `pass`。`single-session` Evidence 不包含这些字段或空占位。
+### 8. Evidence、状态与完成
-Ticket 状态依次为 `ready → in_progress → review → done`；阻塞使用 `blocked`，实际实现与批准契约不一致使用 `deviated`。验证无法运行或存在未批准偏差时不得标 `done`。
+Lead 使用 `<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>` 写入 Ticket Evidence；Direct Spec 按该模板的 Direct Spec 适配说明写 `<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`。Ticket Evidence 包含 source/candidate/result SHA、派单/返回、两层验证、双轴审查、E2E disposition、路径审计、偏差和残余风险；Direct Spec Evidence 使用实施前基线与 current workspace 最终 checkpoint，不伪造 Ticket/worktree/candidate 字段。
-最后一个计划内 Ticket 完成后加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`：没有 Goal Plan 或 `coordination_mode: single-session` 时，完成门全部通过后由本 Work 原子设置 change 为 completed；`lead-team` 时只返回 Evidence，由 Lead 独立验收并关闭 change。旧计划按委派附录兼容推导。若 triage 显示 `pending-close` 或 `close-failed`，下一 Work 为 `<Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path>`；否则进入 Archive。
+Ticket 正常状态：`ready → in_progress → review → done`。`done` 要求 change worktree 已完成集成（`integrated`，或集成后已清理的 `removed`）、父 HEAD=result SHA 且包含 source commit。阻塞使用 `blocked`，契约偏差使用 `deviated`，无需改动使用 `cancelled`。Direct Spec 由当前 I-implement owner 按 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 关闭 change。
-同步：
+按存在和当前模式同步 Ticket、Tickets Map、Goal Plan、`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 和全局状态；Direct Spec 不创建缺失的 Ticket/Map/Goal Plan。最后一个计划内 Ticket 完成后，Goal Plan 的 Lead 按 change completion 关闭；无 Goal Plan 的当前 I owner 承担同一门禁。需要远程 reconcile 时返回 T-triage，否则进入 Archive。
-- Ticket：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
-- Tickets Map：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
-- change 状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
-- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
+运行：
-### 7. 提交与返回
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage implement \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
-1. 运行项目自身的适用验证；
-2. 仅在 `<Path>{roots.state}/specdev/config.json</Path>` 和用户授权允许时提交；
-3. 提交信息引用 Ticket ID 或 Direct Spec change；
-4. Worktree 记录为 `review` 且 `terminal_action=integrate` 时，由 integration owner 自动加载 finalize 合同完成本地集成；其他 merge、push、PR、部署、发布或不可逆迁移不得自动执行；
-5. 返回 Ticket ID 与状态、Evidence 完整路径、`workspace_ref`、source/result checkpoint、commit 或 PR 引用和适用 E2E 结果；Lead Team Worker 返回待 integration owner 执行的 E2E；
-6. Direct Spec 模式返回 change、状态和 `<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`。
+### 9. 返回
-所有 Goal Plan 遵循 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>` 的 Evidence 返回协议；Lead Team 额外遵循 `<Path>{roots.workflows}/specdev/P-goal-plan/delegated-execution.md</Path>`，隔离 workspace 额外遵循 dev-worktree Skill，并返回稳定 locator、最终 checkpoint、集成结果、修正轮次和未验证项。
+Ticket 模式返回 Ticket/change 状态、Evidence 完整路径、source workspace、source/candidate/result SHA、父分支、E2E disposition、未验证项和下一路由。Direct Spec 返回 change 状态、`<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`、current workspace、实施前/最终 checkpoint、适用 E2E 和下一路由。push、PR、remote merge、deploy、migration、生产动作及来源 branch/worktree cleanup 只在独立授权时执行。
 ## 完成标准
-- 执行前预检通过；
-- 设计检查严格使用共享术语，并保留深模块、接缝、适配器和依赖分类能力；
-- 每个行为通过真实红→绿循环实现；
-- 定向与适用回归验证完成；
-- 双轴审查通过；
-- Evidence 完整；
-- 实际修改未超出授权路径；
-- 无未批准 deviation；
-- 状态已同步；
-- 实现结果可通过 Evidence、状态和代码引用完整定位；
-- 提交遵守用户授权。
+- Ticket 模式的 worktree、实现 commit、双轴审查和 candidate gate 完整；Direct Spec 的轻量合同、current workspace checkpoint、双轴审查和最终验证完整；
+- source worktree 无 E2E，Ticket 适用 E2E 由 Lead 在 parent-candidate 运行，Direct Spec 适用 E2E 由 Lead 在 current workspace 运行；
+- Lead 独立核对并写全部 SpecDev 工件；
+- Ticket 父分支只推进到通过的 candidate，Ticket Done 与实际 Git 一致；Direct Spec 的完成状态与 current workspace 最终 checkpoint 一致；
+- 实际路径、验证、偏差和状态可由 Evidence 恢复；
+- validator 无 error。
 ## 子文件引用
 - 执行前预检：`<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`
-- 代码库设计规则：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
+- 代码库设计：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
 - Design It Twice：`<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`
-- TDD 规则：`<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`
-- TDD 测试设计：`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`
-- TDD Mocking：`<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`
-- 代码注释规则：`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
-- 双轴审查：`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
-- Evidence 模板：`<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>`
-- 委派 Evidence 附录：`<Path>{roots.workflows}/specdev/I-implement/delegated-evidence-template.md</Path>`，仅 lead-team 时加载
-- Agent 交付合同：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
-- Merge/rebase 冲突：`<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`
+- TDD：`<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`
+- 代码注释：`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
+- Evidence：`<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>`
+- Agent 交付：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
+- Worktree：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`
+- 冲突处理：`<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`

package/template/workflows/specdev/I-implement/evidence-template.md CHANGED Viewed

@@ -1,90 +1,102 @@
 # Evidence: <Ticket ID> — <Ticket title>
+Direct Spec 使用本模板时写入 `<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`：Ticket、Goal Plan、source worktree 与 candidate 字段写“不适用：Direct Spec”，以实施前基线和 current workspace 最终 checkpoint 代替 source/candidate/result 链；第 5、7 节分别记录 current workspace 定向检查和 Lead 最终回归/E2E，不伪造 Ticket 状态。
 - **Change：** `<change>`
 - **Ticket：** `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
 - **Spec：** `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- **Tickets Map：** `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
 - **Goal Plan：** `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` / 不适用
-- **基线/分支：**
-- **Worktree 引用：** 不适用 / `<workspace_ref>`
-- **实现者：**
-- **开始/结束：**
-- **状态：** review / done / blocked / deviated
+- **Lead：** `<owner-or-session-locator>`
+- **Source worktree/branch：** `<workspace_ref>` / `<branch>`
+- **Base/source/candidate/result SHA：** `<sha>` / `<sha>` / `<sha>` / `<sha>`
+- **状态：** review / done / blocked / deviated / cancelled
 ## 1. 实现摘要
-用用户可观察行为和已锁定契约说明实际完成了什么，不复述提交日志。
+用可观察行为与已锁定合同说明实际完成内容。Cancelled 时说明为何无需实现及其权威来源。
+## 2. Lead Dispatch And Candidate Return
+- **Implementation owner：** Lead / `<agent/provider>`
+- **Dispatch Packet/checkpoint：** Lead direct / `<locator + immutable checkpoint>`
+- **允许动作：** worktree changes / implementation commit / ...
+- **返回：** commit、dirty 状态、修改路径、非 E2E 命令、未验证项与恢复条件
+- **Lead 独立核对：** pass / fail；实际读取与命令摘要
+- **只读 Agent findings：** 无 / 固定输入、来源、结论、Lead 核对
+subagent 不写本 Evidence；以上内容由 Lead 从实际 workspace、Git 和返回事实整理。
-## 2. 修改范围
+## 3. 修改范围与路径所有权
 | 路径 | 所有权 | 改动目的 |
 |---|---|---|
 | `<Path>src/example.ts</Path>` | writable / shared:<owner> | ... |
-## 3. 验收与合同映射
+- **read-only 修改：** 无
+- **未声明路径：** 无
+- **生成文件/锁文件：** 无 / 来源与 owner
+## 4. 验收与合同映射
 | Contract / Acceptance ID | 验证接缝 | 证据 | 结果 |
 |---|---|---|---|
-| AC-... | ... | 测试、截图、日志或人工检查摘要 | pass / fail / not-run |
+| AC-... | ... | 测试、日志或人工检查摘要 | pass / fail / not-run |
-每个 Ticket 验收项必须恰好落到一行；不能用“一般测试已通过”替代逐项证据。
+每个 Ticket 验收项恰好落到一行。
-## 4. 验证执行
+## 5. Source-worktree 验证
-| 命令或步骤 | 运行环境 | 结果 | 摘要或附件 |
+| 命令或步骤 | 运行环境 | 结果 | 摘要 |
 |---|---|---|---|
-| ... | ... | pass / fail / not-run | ... |
+| ... | source-worktree | pass / fail / not-run | ... |
 - **失败后修复与重跑：** 无 / ...
-- **未运行检查：** 无 / 原因与风险 ...
-- **E2E：** 不适用 / 场景、执行者与结果
-- **反向验证：** 不适用 / 受控失败信号与恢复结果
-- **外部声明：** 无 / 已核对 / `unverified`：原因
+- **未运行检查：** 无 / 原因与风险
+- **E2E：** 禁止在 source-worktree 声明 pass；此处固定为 not-run: parent-candidate-owned
-## 5. 双轴审查
+## 6. 双轴审查
 ### 标准轴
+- **固定输入：** `<base_sha>..<source_checkpoint>`
 - **结果：** pass / request-changes
-- **来源：** 仓库标准 + Fowler baseline
-- **Findings：** 无 / ...
-- **修正与重跑：** 不适用 / ...
+- **Findings 与修正：** 无 / ...
 ### 规范轴
+- **固定输入与来源：** Spec / Ticket / Goal Plan / source
 - **结果：** pass / request-changes / skipped:no-spec
-- **来源：** Spec / Ticket / source / 无
-- **Findings：** 无 / ...
-- **修正与重跑：** 不适用 / ...
+- **Findings 与修正：** 无 / ...
-两轴保持独立顺序，不合并或跨轴重排 finding。
+两个轴隔离并按上述顺序记录。
-## 6. 路径所有权审计
+## 7. Parent-candidate 集成验证
-- **writable 内修改：**
-- **shared 修改与 owner 批准：** 无 / ...
-- **read-only 修改：** 无
-- **未声明路径：** 无
-- **生成文件或锁文件：** 无 / 来源与 owner ...
+| 项目 | 结果 |
+|---|---|
+| Parent before SHA | `<sha>` |
+| Source/candidate SHA | `<sha>` / `<sha>` |
+| Candidate branch/workspace | `<branch>` / `<workspace_ref>` |
+| Method/conflicts | fast-forward / merge-commit；无 / paths |
+| Candidate checks | 命令、运行环境 `parent-candidate`、结果 |
+| E2E disposition | required / not-required: reason |
+| E2E result | pending / passed / failed / not-required；场景与证据 |
+| Parent result/re-read | `<sha>`；HEAD/tree/ancestor 核对 |
-## 7. 偏差与决策
+Candidate failed/stale 时明确父分支未推进、失败命令、旧 candidate SHA 和恢复条件。
-- **偏差：** 无 / `<deviation-id>`
-- **偏差记录：** `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` / 不适用
-- **批准人或决策来源：**
-- **对范围、契约、依赖或后续 Ticket 的影响：** 无 / ...
+## 8. 偏差与决策
-偏差处理遵守 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`，不得静默修改 Ticket 目标或验收。
+- **偏差：** 无 / `<deviation-id>`
+- **记录：** `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` / 不适用
+- **批准来源及影响：** ...
-## 8. 残余风险与后续
+## 9. 残余风险与交付定位
-- **残余风险：** 无 / ...
-- **已知限制：** 无 / ...
+- **残余风险/已知限制：** 无 / ...
 - **后续 Ticket：** 无 / `<ticket-id>`
-- **监控或回滚触发条件：** 不适用 / ...
-## 9. 交付定位
-- **Commit / PR：**
-- **最终 Workspace 引用：** 不适用 / `<workspace_ref>`
-- **Evidence 文件：** `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`
+- **监控或回滚触发：** 不适用 / ...
+- **Source commit：** `<sha>`
+- **Parent result：** `<sha>`
+- **Source workspace：** `<workspace_ref>`
+- **Evidence：** `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`

package/template/workflows/specdev/I-implement/execution-preflight.md CHANGED Viewed

@@ -1,28 +1,36 @@
 # Execution Preflight
-## 硬检查
+## Ticket 硬检查
 - [ ] Ticket frontmatter 可解析，`ready: true`，`status: ready`。
-- [ ] 所有 blocked_by Ticket 为 done 且证据存在。
-- [ ] Spec、ADR、Ticket 和 Goal Plan 无冲突。
-- [ ] 当前代码入口、接口和路径仍与 Ticket 假设一致。
-- [ ] writable_paths 无并发 owner 冲突。
-- [ ] Goal Plan 的 coordination mode 与 workspace strategy 均可判定；旧计划缺少字段时只按兼容规则推导，不把 Agent Team 当作 worktree 触发条件。
-- [ ] Ticket 分配到 worktree 时，记录为 `active`，合法 trigger、`base_sha`、父分支、implementation/integration owner、分支、`workspace_ref` 和结束动作与计划一致。
-- [ ] `lead-team` 时只有一个 execution model 和 Lead，mutation role、派单 checkpoint 与当前源码一致，workspace/session locator 可恢复；`worker-write` 不指向 current workspace。
-- [ ] 授权矩阵分别覆盖 local changes、implementation commit、local worktree integration、push、PR、remote merge、deploy、migration 和生产动作；未授权动作不会执行。
-- [ ] 委派候选交付的附件 hash、修改范围和事实声明可由 Lead 独立核对。
-- [ ] 验证命令/环境可用。
-- [ ] 可静默失效的关键门禁定义了受控反向验证；普通测试不为形式追加破坏性检查。
-- [ ] Deep Ticket 的批准点已满足。
+- [ ] 所有 `blocked_by` Ticket 为 done 且 Evidence 存在。
+- [ ] Spec、ADR、Ticket 与 Goal Plan 无冲突；旧 Goal Plan schema 必须重跑 P-goal-plan。
+- [ ] Goal Plan（若存在）为 `lead-directed`，Lead 可恢复，implementation agent limit 为 `1..3`。
+- [ ] 当前代码入口、接口、路径和父分支仍与 Ticket 假设一致。
+- [ ] writable/shared paths 有唯一 owner，当前 Wave 无项目写冲突。
+- [ ] implementation commit 与 local candidate integration/父分支更新已授权；push/PR/remote/deploy 等保持独立。
+- [ ] dev-worktree 记录 schema v4，`base_sha`、父分支、owners、branch、`workspace_ref`、integration 与 E2E disposition 完整。
+- [ ] implementation subagent 若被派遣，Packet 绑定上述 worktree/checkpoint；subagent 不写 SpecDev 状态。
+- [ ] 来源检查明确为非 E2E；required E2E 有 parent-candidate 场景与预期。
+- [ ] 验证命令/环境可用，关键静默失败风险有受控反向验证。
+- [ ] Deep Ticket 批准点已满足。
+## Direct Spec 硬检查
+- [ ] 用户明确批准 Direct Spec；单一行为、局部、低风险、可逆且无需并行/Ticket DAG。
+- [ ] current workspace 只有一个项目与 SpecDev 写入 owner。
+- [ ] 目标、IN/OUT、可写范围、不变量、验证与验收完整。
+- [ ] 实施前 Git checkpoint、dirty 状态和现有用户改动已记录，不覆盖无关改动。
+- [ ] 非 E2E、适用回归与 E2E 验证环境可执行；E2E owner 固定为 Lead。
+- [ ] implementation commit 授权状态明确；未授权时不提交，并在轻量合同与 Evidence 中记录交付状态。
 ## 失效分类
-- **stale-navigation**：仅 expected_changes/行号过时，契约仍有效；更新导航后继续。
-- **local-implementation**：局部实现方式需调整，不改变契约；记录后继续。
-- **ticket-invalid**：范围、接口、依赖、验证或路径契约失效；停止并修 Ticket。
-- **spec-invalid**：外部行为/合同需改变；停止并修 Spec。
-- **adr-conflict**：架构决策冲突；停止并处理 ADR。
-- **checkpoint-drift**：委派派单基线、源码包或当前代码已经漂移；暂停并由 Lead 重放、重派或建立新 checkpoint。
-- **workspace-contract-invalid**：worktree 缺少合法 trigger、父分支、owner、locator、source checkpoint 或结束动作；停止并修 Goal Plan/状态记录。
-- **delivery-unverified**：候选交付、provider 声明或附件无法独立核对；保持 `unverified`，不得推进 `done`。
+- **stale-navigation**：导航过时但契约仍有效；更新导航继续。
+- **local-implementation**：局部实现调整不改变契约；记录后继续。
+- **ticket-invalid**：范围、接口、依赖、验证或路径合同失效；停止并修 Ticket。
+- **spec-invalid / adr-conflict**：返回对应上游 owner。
+- **checkpoint-drift**：来源/父分支/派单 checkpoint 漂移；由 Lead重建 worktree 或 candidate。
+- **workspace-contract-invalid**：缺少父分支、owner、locator、source/candidate/result 字段或授权；停止并修状态/计划。
+- **delivery-unverified**：候选、provider 声明或附件不能独立核对；保持 unverified。
+- **e2e-owner-invalid**：E2E 被安排在 source worktree 或非 Lead owner；停止并修 Ticket/Goal Plan。

package/template/workflows/specdev/I-implement/merge-conflict-protocol.md CHANGED Viewed

@@ -1,21 +1,21 @@
 # Merge / Rebase Conflict Protocol
-只在 `git status` 证明仓库正处于 merge 或 rebase 冲突时加载。普通集成设计冲突继续按 deviation/upstream owner 处理。
+只在 `git status` 证明仓库正处于 merge/rebase 冲突时加载。
 ## 流程
-1. 读取 Git 状态、操作类型、冲突文件、base/ours/theirs commit、当前 Ticket/Evidence，以及是否存在匹配的 `terminal_action=integrate` worktree 记录。
-2. 追溯双方意图：commit message、冻结的 source、Spec、Ticket、ADR、测试和调用者。二者缺失时不凭代码表面猜测产品行为。
-3. 逐 conflict hunk 写出双方意图、共同约束和建议结果。只合并既有意图；需要发明新行为或改变上层合同则停止并登记 deviation。
-4. 在获授权可写范围内解决文本，运行受影响测试、typecheck、lint 和项目要求的验证。能从既有权威唯一推导的冲突直接处理，不把“发生冲突”本身升级为人工确认。
-5. 若当前 merge 来自匹配记录的本地集成，`terminal_action=integrate` 已授权 `git add`、继续 merge 和一次集成专用 commit；验证通过后直接完成，不逐动作请求确认。其他 merge/rebase 仍分别取得 Git 副作用授权；没有授权时保存分析、剩余文件和精确恢复命令。
-6. 需要发明新产品行为、改变 Spec/ADR、安全/迁移决定、越过路径 owner 或无法保持双方既有意图时停止；由从干净目标开始的自动集成执行 `git merge --abort`，记录 blocker 并保留来源 worktree。普通冲突现场不擅自 abort。
-7. 重读 Git 状态、parents 和 diff，确认无 marker、无未声明路径、双方要求及测试仍成立。
+1. 读取 Git 状态、操作类型、冲突路径、base/ours/theirs SHA、Ticket/Evidence 与匹配的 candidate integration 记录。
+2. 从 commit、source、Spec、Ticket、ADR、测试和调用者追溯双方意图；信息不足时不猜产品行为。
+3. 对每个 hunk 写出双方意图、共同约束和唯一可推导结果；需要新行为或上层决定时停止并登记 deviation。
+4. 在授权路径内解决文本，运行受影响的非 E2E 检查；candidate checkout 中按 finalize 合同运行父状态检查/E2E。
+5. 匹配的 local candidate integration 授权包含 `git add`、candidate merge commit、必要的 `git merge --abort` 和 transient candidate checkout/branch 生命周期；不扩展到来源 branch/worktree cleanup 或远端动作。
+6. 需要改变 Spec/ADR、安全/迁移决定、越过 owner 或无法同时保持既有意图时，在 Lead-created candidate 中执行 `git merge --abort`，记录 blocker 并保留来源 worktree；未知普通冲突现场不擅自 abort。
+7. 重读 Git 状态、parents 与 diff，确认无 marker、无未声明路径、双方合同及验证仍成立。
 ## 完成标准
-- 每个 hunk 的结果可追溯到双方意图；
+- 每个 hunk 可追溯到既有意图；
 - 新产品决定没有藏在冲突解决中；
-- 项目验证有命令、退出码和关键输出；
-- Git 副作用来自逐动作授权，或来自可核对 worktree 记录中的持久本地集成授权；
-- 完成或暂停状态可以从 Evidence 和 Git 状态恢复。
+- 验证记录命令、运行环境、退出码和摘要；
+- Git 副作用来自明确的 candidate integration 或其他逐动作授权；
+- 完成/暂停可以从 Git、change status 和 Evidence 恢复。