@namewta/speculo 0.7.2 → 0.7.3

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

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