@namewta/speculo 0.7.2 → 0.7.4

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

@@ -1,34 +1,31 @@
 # Change Completion
 
-本规则是 change 从 active/blocked 转为 completed 的唯一合同，并由 Implement、Goal Plan、Triage、Status 与 Archive 共同读取。
+本规则是 change 从 active/blocked 转为 completed 的唯一合同。
 
 ## 完成门
 
-一个 change 只有同时满足以下条件才能设置 `change_status: completed`：
+一个 change 只有同时满足以下条件才能 completed：
 
-1. 所有计划内 Ticket 为 `done`，或有明确批准理由的 `cancelled`；无 Ticket 的 Direct Spec/非实现流程有等价的验收清单。
-2. 每个完成行为有 Evidence，全部 Spec 验收合同和适用 Goal Gate 可定位。
-3. 项目级验证通过；既有或环境失败已分类、接受并记录风险。
-4. 迁移、发布、监控、回滚和不可逆批准已完成或明确不适用。
-5. 没有未批准 deviation、未处置 blocker 或伪装成通过的 `unverified` 声明。
-6. Ticket、Map、Goal Plan、Evidence、源码 checkpoint 和 change 状态一致。
+1. 所有计划内 Ticket 为 done，或因权威事实无需改动而记录为 cancelled；Direct Spec/非实现流程有等价验收。
+2. required Ticket 有 source commit、passed candidate、父分支 result SHA，且父分支包含 source commit；current Ticket 有 implementation commit、passed direct-parent 验证和父分支 result SHA；对应 workspace 记录均为完成状态。
+3. 每个行为有 Lead Evidence，全部 Spec 合同与 Goal Gate 可定位。
+4. current Ticket 的 current-workspace 检查/回归和适用 E2E，或 required Ticket 的 source-worktree 非 E2E 检查、parent-candidate 集成/回归和 required E2E 已通过；not-required 有理由。
+5. 迁移、发布、监控、恢复和不可逆批准已完成或明确不适用。
+6. 没有未批准 deviation、blocker、unverified、活动 candidate 或未集成 source checkpoint。
+7. Ticket、Map、Goal Plan、Evidence、change status 与实际 Git 一致。
+
+Evidence-only Done 和 empty commit 不满足完成门。
 
 ## 转换 Owner
 
-- Goal Plan 为 `coordination_mode: lead-team`：Lead 在独立验收并关闭最后一个 Gate 后拥有完成转换。
-- Goal Plan 为 `coordination_mode: single-session`，或无 Goal Plan 的 Ticket/Direct Spec 实现：最后一个计划内 Implement 在最后一项验收通过后拥有完成转换。
-- 旧 Goal Plan 缺少 coordination 字段时，根据完整 `## Delegated Execution Addendum` 是否存在兼容推导，不要求 runtime schema 迁移。
-- 非实现型终点：最后一个拥有最终验收工件的 Work 使用本规则完成转换。
+- 有 Goal Plan：其唯一 Lead 在关闭最后 Gate 后拥有转换；
+- 无 Goal Plan 的 Ticket/Direct Spec：当前 I-implement 主会话 owner 拥有转换；
+- 非实现型终点：最终验收工件 owner 使用本规则。
 
-Owner 原子更新 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `change_status`、`completed_at`、`updated_at` 和 `current_work`，然后重读验证。全局 `<Path>{roots.state}/specdev/status.json</Path>` 继续只保存 active 索引，不复制完成详情。
+Owner 原子更新 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `change_status`、`completed_at`、`updated_at` 和 `current_work`，然后重读。全局 status 只维护 active/archived 索引。
 
 ## 远程来源与归档
 
-远程动作不参与本地完成判定。完成后若 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` 的 `external_action` 为 `pending-close` 或 `close-failed`，下一路线是 Triage reconcile；`closed`、`waived` 或 `not-applicable` 才允许 Archive 移动 change。归档后工件只读，不在归档目录补写远程结果。
-
-## 完成标准
+远程动作不参与本地完成判定。Triage 为 `pending-close`/`close-failed` 时先 reconcile；`closed`、`waived` 或 `not-applicable` 才允许 Archive。归档后工件只读。
 
-- 完成声明可以从本地工件和实际验证重建；
-- 当前 change 只有一个条件命中的转换 owner；
-- 远程失败不会把 completed 改回 active；
-- Archive 不接收尚未 reconcile 或 waive 的远程来源。
+**完成标准**：完成声明可由本地工件、Git 与验证重建；只有一个 owner 命中；失败 candidate 不污染父分支。

package/template/workflows/specdev/common/rules/deviation-control.md

@@ -40,4 +40,4 @@
 
 - 未批准的 ticket、spec、architecture 或 release 偏差不得继续实现。
 - 不得通过扩大 `writable_paths`、删除测试、降低断言或把风险改写成“已知限制”来绕过停止。
-- 偏差影响普通并行执行时，当前集成 owner 必须暂停受影响 Wave，重新计算路径所有权、依赖和 Gate；委派执行由 Lead 承担同一责任。
+- 偏差影响并行执行、source checkpoint 或 candidate 集成时，Lead 必须暂停受影响 Wave，重新计算路径所有权、依赖、Gate 与父分支顺序；任何 subagent 都不能自行改写上层合同。

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

@@ -1,57 +1,51 @@
 # 证据与验证规范
 
-验证回答“怎样证明行为已经正确发生”，Evidence 回答“实际运行了什么、结果是什么、仍有什么风险”。
+验证回答“怎样证明”，Evidence 记录“实际运行了什么、在哪个状态运行、结果和残余风险是什么”。
 
 ## 1. 验证矩阵
 
-每一行绑定一个行为、合同或风险：
+每行绑定行为、合同或风险，并标记环境：
 
-| 行为或风险 | 验证接缝 | 方法或命令 | 预期结果 | Evidence |
-|---|---|---|---|---|
-| 正常路径 | 公共接口 | 项目定向测试 | 指定外部行为成立 | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` |
-| 无效输入 | schema 或公共接口 | 定向失败测试 | 稳定错误行为成立 | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` |
-| 回归 | 现有测试套件 | 项目回归命令 | 相关既有行为保持 | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` |
+| 行为或风险 | 接缝 | 命令/方法 | 环境 | 预期 | Evidence |
+|---|---|---|---|---|---|
+| 正常/失败路径 | 公共接口或稳定接缝 | 定向测试 | current-workspace 或 source-worktree | 合同成立 | Ticket Evidence |
+| 跨模块回归 | 集成接缝 | 回归命令 | current-workspace 或 parent-candidate | 组合状态成立 | Ticket Evidence |
+| E2E required | 真实端到端边界 | 场景步骤 | current-workspace 或 parent-candidate | 外部行为成立 | Ticket Evidence |
 
-命令引用项目脚本时，项目文件路径使用项目相对 Path 标签，例如 `<Path>package.json</Path>` 或 `<Path>Makefile</Path>`。
+## 2. 两层验证
 
-## 2. 最小充分验证
+### Current workspace
 
-选择最接近目标行为的稳定接缝：
+current 模式的 implementation owner 在当前父分支和当前 workspace 工作。Ticket 必须严格串行，workspace clean 后形成非空 implementation commit；Lead 在同一 workspace 执行适用集成/回归和 E2E，并在父 HEAD 未漂移时将 Ticket commit 记录为 result SHA。
 
-1. 公共接口或契约集成测试；
-2. 稳定接缝上的单元测试；
-3. 类型检查、静态分析、lint 和构建；
-4. 可重复手动步骤、截图或查询结果；
-5. 代码阅读推断。
+### Source-worktree
 
-E2E 仅在变更影响用户界面交互时加入验证矩阵。普通执行由当前实现或集成 owner 运行；委派执行中 Worker 只记录场景、预期结果和待执行状态，由 Lead 在集成阶段运行。API、CLI、后端、库或数据变更默认使用其稳定接缝，不追加 E2E。
+implementation owner 运行最接近目标行为的单元/组件测试、静态分析、类型、lint/build 等适用非 E2E 检查。来源实现必须在 clean worktree 形成 commit。任何 source-worktree E2E pass 声明无效。
 
-低层证据不能替代明确要求的用户行为证据。高风险迁移还需要 dry-run、调用点扫描、数据核对、监控信号或回滚演练。
+### Parent-candidate
 
-## 3. 失败分类
+required 模式下，Lead 在最新父分支与 source commit 的 candidate 状态运行受影响集成/回归、项目父状态检查和适用 E2E。E2E 由实际跨边界风险决定，不限于 UI；not-required 必须写理由。required E2E 未运行或失败时不得推进父分支。
 
-每个失败必须分类为：
+### Direct Spec
 
-- 本 Ticket 引入的新失败；
-- 基线已存在的失败；
-- 环境、权限或基础设施失败；
-- 验证本身无效或无法观察目标行为。
+获批 Direct Spec 不创建 Ticket worktree 或 candidate。Lead 在 current workspace 记录实施前基线，运行轻量合同要求的定向检查、适用回归与 E2E，并记录最终 checkpoint、dirty 状态、运行环境、命令、退出状态和未运行原因。E2E 仍只由 Lead 执行；不得为套用两层验证而伪造 Ticket、source/candidate/result 或父分支推进证据。
 
-不得通过跳过测试、放宽断言、吞错、删除用例或把命令移出验证矩阵来制造绿色。
+低层证据不能替代明确要求的外部行为证据。高风险迁移还需要 dry-run、调用点扫描、数据核对、监控或恢复演练。
 
-## 4. Evidence 最低内容
+## 3. Agent 声明
 
-每个完成 Ticket 在 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` 记录：
+subagent 只返回候选命令与结果，不写 Evidence。Lead 重读 workspace/Git、必要时复跑或核对输出后落盘；外部 provider 自报、截图、模拟和推断在此之前标记 `unverified`。review/research/test-observation agent 不拥有 E2E Gate。
 
-- 基线、分支或 worktree；
-- 实际修改的项目路径；
-- 每条命令、退出状态和结果摘要；
-- 每条验收合同的证据映射；
-- 未运行项与原因；
-- 新失败、既有失败和环境失败；
-- 偏差及批准；
-- 残余风险；
-- worktree、提交或 PR 引用；
-- 最终结论。
+## 4. 失败分类与完整性
 
-无法运行关键验证、存在未批准偏差或 Evidence 不完整时，Ticket 不得标为 `done`。
+失败分类为本 Ticket 新失败、基线既有失败、环境/权限/基础设施失败、无效验证或 candidate stale。不得通过跳过、放宽断言、吞错、删除用例或迁移验证位置制造绿色。
+
+受控反向验证只用于可能静默通过的关键门禁：证明检查能在目标风险出现时失败，再恢复并重跑。普通测试不为形式执行破坏性操作。
+
+## 5. Evidence 最低内容
+
+每个 Ticket Evidence 至少包含：Lead、Dispatch/返回（若有）、workspace 策略、base/source/result SHA、candidate 字段（required 模式适用，current 模式明确不适用）、实际路径、每条命令/环境/退出状态、合同映射、双轴审查、E2E disposition、未运行项、失败分类、偏差、残余风险和父分支重读结果。
+
+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 命令及环境、验收映射、未运行项、偏差、残余风险和提交授权状态。

package/template/workflows/specdev/common/rules/path-ownership.md

@@ -1,35 +1,33 @@
 # 路径所有权与并发规则
 
-路径所有权是并行执行的硬边界，不是文件预测清单。
+路径所有权是逻辑写入边界；worktree 是物理隔离边界，两者不能互相替代。
 
 ## 1. 四类路径
 
-- `expected_changes`：预计修改的项目路径，仅用于导航；每项写成项目相对 Path 标签。
-- `writable_paths`：实现者获准修改的项目路径或 glob，是硬约束。
-- `read_only_paths`：建立上下文但不得修改的项目路径。
-- `shared_paths`：多个 Ticket 可能需要修改的项目路径，必须指定唯一 owner。
+- `expected_changes`：导航预测；
+- `writable_paths`：当前 Ticket implementation owner 可写的硬边界；
+- `read_only_paths`：只读上下文；
+- `shared_paths`：多个 Ticket 可能触达且必须有唯一 owner 的项目路径。
 
-示例：
-
-```yaml
-expected_changes: ["<Path>src/auth/session.ts</Path>"]
-writable_paths: ["<Path>src/auth/**</Path>"]
-read_only_paths: ["<Path>src/users/**</Path>"]
-shared_paths: ["<Path>package.json</Path>"]
-```
+所有项目路径使用项目相对 Path 标签。根依赖清单、锁文件、根导出、共享 schema、迁移索引、全局路由和跨 Ticket 合同默认视为 shared。
 
 ## 2. 所有权规则
 
-1. 可能并行的 Ticket，其 `writable_paths` 不得相交。
-2. glob 与具体路径按覆盖关系判断，不得只比较字符串。
-3. 根依赖清单、锁文件、根导出、共享 schema、迁移索引、全局路由和跨 Ticket 合同文件默认视为 shared。
-4. shared path 只能由专用 owner Ticket 或 Goal Plan 明确指定的唯一集成 owner 修改；消费者 Ticket 只读。委派 Goal Plan 可以把该 owner 指定为 Lead，但普通计划不预设角色。
-5. 需要越界时先停止，按 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 提出 ownership change；不得先改后报。
-6. 前置 Ticket 改变目录结构后，后续 Ticket 开始前重新解析项目路径；若授权范围语义未改变，可只更新导航路径。
-7. 不得把“最后解决合并冲突”当作所有权方案。
+1. 可能并行的 Ticket，其 writable paths 不得相交；glob 按覆盖关系判断。
+2. shared path 只由专用 owner Ticket 修改；消费者 Ticket 只读。Lead 负责集成，不以冲突解决替代 shared owner。
+3. implementation subagent 只写其 Packet 与 Ticket 授权路径；Lead 自行实现也受同一边界约束。
+4. review/research/test-observation agent 只读项目与 SpecDev 工件。
+5. 越界前停止并按 deviation control 提出 ownership change；不得先改后报。
+6. 上游 Ticket 改变目录/合同后，下游基于已集成父分支重新解析路径和 preflight。
+
+## 3. Ticket workspace strategy
+
+Goal Plan 创建时选择 Ticket workspace strategy，默认 `current`。`current` 模式的 Ticket 使用当前分支、当前 workspace 和严格串行执行；允许一个 implementation subagent 写入当前 workspace，但前一 Ticket 必须完成 commit、Lead 验收和 direct-parent 验证后才能开始下一个。`required` 模式每个 Ticket 使用唯一来源 worktree `specdev-worktree/<ticket-id>`，并通过 candidate-merge 集成。没有 Ticket 的获批 Direct Spec 继续由 current workspace 唯一 owner 执行；只读调查不创建实现 worktree。
+
+workspace/implementation owner 可以是 Lead 或动态 implementation subagent；integration owner 固定为 Lead。current 模式 Lead 在父分支直接验收和推进，required 模式 Lead 建立 parent-candidate、运行适用 E2E 并推进父分支。required 生命周期由 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 管理，current 生命周期由 I-implement 的 direct-parent 规则管理。
 
-## 3. Worktree 与分支
+## 4. 并发
 
-Worktree 只在存在可观察隔离需求时使用：并行写入、保护当前本地状态、一次性实验、后台恢复、provider 要求或用户明确要求。只读调查和没有其他隔离事实的顺序写入默认共用当前工作区。Agent Team、Ticket 数量和泛化的“更安全”都不构成隔离理由。Worktree 防止工作区污染，路径所有权防止逻辑冲突，两者不能互相替代。
+required 模式 implementation subagent 上限取 Goal Plan、config 和平台能力共同约束，Lead 不计入。current 模式保持单 writer 串行安全不变量，Ticket 严格串行。review/research/test-observation agent 不设置 SpecDev 数字上限，但 Lead 必须避免重复工作与可变环境争用。
 
-生命周期由调用方明确的 workspace owner 与 integration owner 按 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 管理。`single-session` 通常把两者映射为主会话；`lead-team` 可以把 integration owner 映射为 Lead，但角色选择不决定是否使用 worktree。同一 current workspace 只允许一个项目与 SpecDev 状态写入 owner；Worker 要写项目文件时必须拥有独立 workspace。编排规则位于 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>`。
+**完成标准**：每个项目写入映射到唯一 Ticket、owner 和来源 worktree；shared 与父分支写入 owner 唯一。

package/template/workflows/specdev/common/rules/readiness-and-depth.md

@@ -16,7 +16,7 @@
 
 ### Deep
 
-任一条件触发：公共 API、schema、wire format、数据迁移、认证授权、隐私、资金、不可逆操作、expand-contract、共享核心路径、多 Agent 复杂协作、多个实质架构方案或高事故半径。
+任一条件触发：公共 API、schema、wire format、数据迁移、认证授权、隐私、资金、不可逆操作、expand-contract、共享核心路径、多个 implementation owner 的跨 Ticket 写入协调、多个实质架构方案或高事故半径。
 
 额外要求：数据流或状态转换、兼容窗口、迁移顺序、可观测性、回滚、风险缓解、收缩条件和人工批准点。