@namewta/speculo 0.7.2 → 0.7.3

package/template/workflows/specdev/common/schemas/status.schema.json

@@ -1,82 +1,26 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:status:v4",
+  "$id": "urn:speculo:specdev:status:v5",
   "title": "SpecDev Global Status",
   "type": "object",
-  "required": [
-    "schema_version",
-    "workflow",
-    "active",
-    "archived"
-  ],
+  "required": ["schema_version", "workflow", "active", "archived"],
   "properties": {
-    "schema_version": {
-      "const": 4
-    },
-    "workflow": {
-      "const": "specdev"
-    },
+    "schema_version": {"const": 5},
+    "workflow": {"const": "specdev"},
     "active": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": [
-          "change",
-          "current_work",
-          "works_run"
-        ],
+        "required": ["change"],
         "properties": {
           "change": {
             "type": "string",
             "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
-          },
-          "current_work": {
-            "type": [
-              "string",
-              "null"
-            ],
-            "pattern": "^specdev/"
-          },
-          "works_run": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "pattern": "^specdev/"
-            },
-            "uniqueItems": true
-          },
-          "claimed_investigations": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "required": [
-                "id",
-                "owner",
-                "claimed_at"
-              ],
-              "properties": {
-                "id": {
-                  "type": "string"
-                },
-                "owner": {
-                  "type": "string"
-                },
-                "session": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
-                },
-                "claimed_at": {
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
-            }
           }
         },
         "additionalProperties": false
-      }
+      },
+      "uniqueItems": true
     },
     "archived": {
       "type": "array",

package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md

@@ -1,31 +1,52 @@
 ---
-name: specdev-dev-worktree
-description: 为具有明确隔离触发条件的 Ready Ticket 或一次性原型建立可恢复 worktree，并由 workspace owner 与 integration owner 管理基线、自动本地集成或清理。
+name: dev-worktree
+description: 管理 SpecDev Ticket 或原型的 Git worktree；为 Ticket 创建隔离来源 workspace、固定实现 commit，并由 Lead 在 parent-candidate checkout 验证后推进父分支。
 ---
 
-# SpecDev Dev Worktree
+# Dev Worktree
 
-## 适用范围
+本 Skill 由 T-tickets/P-goal-plan/I-implement 和 P-prototype 复用。`purpose=ticket` 使用完整 source → candidate → parent 状态机；`purpose=prototype` 只使用调用方批准的临时生命周期。
 
-- 只用于具备 `parallel-write`、`protect-local-state`、`disposable-experiment`、`background-resume`、`provider-requirement` 或 `user-requested` 触发事实的 Ready Ticket/原型。
-- 只读调查、Agent Team 本身和没有其他隔离事实的顺序执行默认共用当前工作区。
-- 调用方必须明确 trigger、workspace owner、implementation owner、integration owner、固定基线、父分支、工作项 ID、持久化 owner 和允许的结束动作。
-- Coordination 与 workspace 正交：`single-session` 可以使用本 Skill；`lead-team` 不自动使用。Current workspace 下 Worker 只读；Worker 写入必须绑定本 Skill 创建的独立 workspace。
-- 平台原生 worktree 优先；不可用时使用 Git worktree。
+## 输入
 
-## 生命周期
+- `operation=create | restore | finalize | remove`；
+- `purpose=ticket | prototype`；
+- repository、父分支、`base_sha`、branch、portable workspace locator；
+- workspace、implementation 和 integration owner；
+- 允许动作、路径合同、验证合同、调用方状态记录位置。
 
-1. 创建或恢复时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/create.md</Path>`。
-2. implementation owner 完成后返回工作项状态、Evidence/record 路径、`workspace_ref`、不可变 source checkpoint、commit 或 PR 引用和未验证项；Ticket worktree 从 `active` 更新为 `review`。
-3. `terminal_action=integrate` 时 integration owner 自动加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/finalize.md</Path>`；`retain` 保持 review。一次性原型只评估和清理，不合入生产分支。
+Ticket 还必须提供 Ready Ticket、Goal Plan（若存在）、Evidence 路径、implementation commit 与本地 candidate integration/父分支更新授权。缺失时返回 blocked，不使用 current workspace 代替。
 
-Ticket worktree 状态依次为 `planned → active → review → integrating → integrated → removed`；失败进入 `blocked`，记录写入 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees`。`integrating` 是带完整授权、来源和尝试证据的可恢复锁：同一父分支一次只允许一个 integration owner；fast-forward 与 merge-commit 都必须落到可复核的 `integrated/passed` 终态。原型的 branch、`workspace_ref` 和清理结果只写入 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>`，不伪造 Ticket worktree 记录。
+## 1. 创建或恢复
 
-## 边界
+`operation=create` 时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/create.md</Path>`。Ticket 使用 `specdev-worktree/<ticket-id>`；同一 Ticket 只存在一个来源 worktree。`operation=restore` 时重读实际 Git worktree/branch/tip/dirty 状态并与调用方记录核对，漂移时停止。
 
-- 每个隔离 Ticket 使用独立 worktree 和分支；同一并行 Wave 固定相同 `base_sha`。每个原型使用独立 worktree 和分支。
-- Git provider 固定使用 `<project-root>/specdev-worktree/<work-item-id>/`，持久化 `workspace_ref: specdev-worktree/<work-item-id>`；`<project-root>` 由 `workspace.json#path_base: project-root` 解析。
-- native/external provider 保留其可迁移 opaque locator；所有 provider 都不保存机器绝对路径、认证秘密或真实用户数据。
-- 项目根 `.gitignore` 的 `specdev-worktree/` 条目由 `speculo init` 单一维护；缺失时创建流程阻塞并提示重新运行 init。
-- E2E 仅适用于用户界面交互受影响的变更，由 integration owner 在集成阶段运行。
-- `terminal_action=integrate` 授权本地 fast-forward，以及分叉集成所需的暂存、merge continue 和一次集成专用 merge commit；不授权普通实现提交、push、PR、远端 merge、部署、迁移或删除分支/worktree。
+**完成标准**：来源基线、branch、locator、owners 和实际 Git 状态一致；现有用户改动未被覆盖。
+
+## 2. 来源实现门
+
+implementation owner 只在来源 worktree 修改授权项目路径，运行 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查。进入 `review` 前，worktree 必须 clean，branch tip 必须是已授权的 `source_checkpoint` commit，实际 diff 必须符合路径合同。
+
+**完成标准**：source checkpoint 不可变且可达；来源 worktree 没有 E2E pass 声明。
+
+## 3. 候选合并与父分支推进
+
+`operation=finalize` 仅由 Lead/integration owner 调用，并加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/finalize.md</Path>`。Lead 在独立 parent-candidate checkout 组合最新父分支与 source checkpoint，运行集成检查和适用 E2E，通过后才推进父分支。
+
+本地 candidate checkout/branch 的创建、重建和回收属于已授权 local candidate integration；来源 branch/worktree 的删除仍需要独立 cleanup 授权。push、PR、remote merge、deploy、migration 和生产动作不从本 Skill 继承。
+
+**完成标准**：Ticket `integrated` 时父 HEAD 精确等于记录的 result SHA，并包含 source checkpoint；失败或 stale 时父分支未变化。后续 `removed` 只表示来源 branch/worktree 已清理，不撤销该集成事实。
+
+## 4. 移除
+
+`operation=remove` 先验证 Ticket 已 `integrated` 或 prototype 已结束、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree；强制删除需要单独确认。删除后重读 `git worktree list` 与 refs，并只把调用方生命周期状态更新为 `removed`；`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
+
+**完成标准**：只删除精确授权目标；失败保留现场与恢复命令。
+
+## 固定规则
+
+- Agent Team 不决定 worktree；Ticket 切片本身决定来源 worktree；
+- Ticket E2E 只在 Lead-owned parent-candidate checkout 运行；
+- 每个 Done Ticket 必须有 source commit 与父分支 result，worktree 状态为 `integrated` 或其清理后终态 `removed`；
+- candidate 失败保留来源 worktree 修正，父分支不动；
+- 成功集成不自动清理来源 branch/worktree。

package/template/workflows/specdev/common/skills/dev-worktree/references/create.md

@@ -1,43 +1,52 @@
-# 创建或恢复工作项 Worktree
+# Create Or Restore Worktree
 
-## 前置
+## Ticket 前置条件
 
-- Ticket `ready: true` 且依赖完成，或原型问题与临时写入范围已锁定；项目写路径无冲突。
-- 调用方已记录允许的 trigger 及其事实。`parallel-write` 还要求 `<Path>{roots.state}/specdev/config.json</Path>` 中 `git.worktree_for_parallel: true`；一次性原型要求 P-prototype 已取得本次临时 worktree 授权。
-- 调用方已指定 workspace owner、implementation owner、integration owner、父分支、工作项 ID、持久化 owner、`integrate | retain`，并固定 `base_sha`；并行 Ticket 共用同一基线。
+- Ticket Ready，项目根是有效 Git repository，父分支和 `base_sha` 可解析；
+- implementation commit 与 local candidate integration/父分支更新已授权；
+- workspace、implementation、integration owner 唯一；integration owner 必须为 Lead；
+- `specdev-worktree/` 已由 Speculo init 加入项目 `.gitignore`；
+- 目标 branch/worktree 不覆盖现有用户 workspace，路径合同无冲突。
 
-## 创建
+Prototype 只要求调用方已记录本次临时 branch/worktree 授权、问题、owner、locator 和清理策略；它不写 Ticket worktree 状态。
 
-1. 从 Speculo 工作区声明的 `path_base: project-root` 解析 `<project-root>`。若记录的 provider 为 `git`，要求 `workspace_ref` 精确为 `specdev-worktree/<work-item-id>`，拼接后仍位于 project root，且 `specdev-worktree/` 不是逃逸到外部的符号链接。
-2. 读取调用方拥有的持久化记录：Ticket 使用 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees`；原型使用 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>`。若已有可恢复记录，Git provider 必须在 `git worktree list --porcelain` 中匹配固定路径、分支与 `base_sha`；native/external 由对应 provider 解析 opaque locator。一致则恢复，任一不一致停止。
-3. 否则优先调用平台原生 worktree 能力。使用 native/external 时保存 provider 返回的可迁移 locator；不可用时进入 Git fallback。
-4. Git fallback 前确认项目根 `.gitignore` 已包含 `specdev-worktree/` 或等价根模式。缺失时停止并提示重新运行当前版本 `speculo init`，不在本 Skill 内修改 `.gitignore`。
-5. Git fallback 固定 `physical_path = <project-root>/specdev-worktree/<work-item-id>`、`workspace_ref = specdev-worktree/<work-item-id>`，从 `base_sha` 执行 `git worktree add -b <work-item-branch> <physical-path> <base-sha>`。已存在但未与同一记录和 Git 注册匹配的目标路径一律阻塞。
-6. 分支使用 `speculo/<change>/<work-item-id>`；现有分支未能匹配记录时停止。
-7. 安装项目所需依赖，运行最小基线检查。E2E 不属于 implementation owner 的创建基线。
-8. Ticket 将记录写入 `worktrees`；`owner` 保持 implementation owner 的兼容含义：
+## 创建 Ticket 来源 worktree
+
+1. 重读父分支 HEAD、工作树、现有 worktrees 与 refs；父 HEAD 与计划基线不一致时由 Lead决定更新 `base_sha` 或阻塞；
+2. 固定 branch `speculo/<change>/<ticket-id>` 与 locator `specdev-worktree/<ticket-id>`；
+3. 确认目标 branch/path 不存在，或其实际记录精确匹配当前 Ticket；
+4. 从 `base_sha` 创建 Git worktree，不复用其他 Ticket/原型目录；
+5. 在来源 worktree 读取项目 Agent 指令、依赖、构建与路径合同；
+6. 安装实际需要的依赖，运行最小非 E2E 基线；
+7. Lead 写入 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`，状态为 `active`。
+
+初始记录：
 
 ```json
 {
   "ticket_id": "T-01",
-  "owner": "<implementation-owner>",
-  "integration_owner": "<integration-owner>",
+  "owner": "lead",
+  "implementation_owner": "lead-or-dynamic-agent",
+  "integration_owner": "lead",
   "provider": "git",
-  "base_sha": "<sha>",
+  "base_sha": "<immutable-sha>",
   "parent_branch": "<parent-branch>",
   "branch": "speculo/<change>/T-01",
   "workspace_ref": "specdev-worktree/T-01",
-  "terminal_action": "integrate",
   "source_checkpoint": null,
   "integration": {
     "status": "pending",
     "parent_before_sha": null,
     "source_sha": null,
+    "candidate_sha": null,
+    "candidate_branch": null,
+    "candidate_workspace_ref": null,
     "result_sha": null,
     "method": null,
     "conflict_paths": [],
     "verification": "pending",
-    "evidence": "<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>",
+    "e2e": {"required": false, "status": "not-required", "evidence": null},
+    "evidence": "<Path>{roots.state}/specdev/changes/<change>/evidence/T-01.md</Path>",
     "attempts": 0
   },
   "status": "active",
@@ -45,6 +54,12 @@
 }
 ```
 
-native/external provider 将示例中的 provider 与 `workspace_ref` 换为对应可迁移 locator，不套用 Git 物理路径。原型不使用本 JSON 结构，只在 record 的 Run and Assets 中记录源码 branch/commit，并在 frontmatter 写入 `workspace_ref` 与清理状态。
+`e2e.required` 与 Ticket/Goal Plan disposition 一致；required 时初始 status 为 `pending`。
+
+## 恢复
+
+恢复时核对 repository、branch、locator、`base_sha`、实际 HEAD、dirty 状态和 owner。状态记录与 Git 不一致、branch 被其他 worktree 占用或出现越界修改时停止；Lead 写 blocker，不重建覆盖。
+
+进入 `review` 前必须由 implementation owner 创建最终 commit；Lead 重读 branch tip、diff 与 `git status`，把精确 SHA 写入 `source_checkpoint`。
 
-`terminal_action=integrate` 不替代来源实现提交授权；进入 `review` 前必须把已获授权的最终 commit 写为 `source_checkpoint`。完成条件：工作区可定位、基线可用、调用方记录与实际 provider、分支和 checkpoint 一致；Git provider 的引用与工作项 ID 完全一致。失败时在调用方拥有的记录中设为 `blocked` 并保留现场。
+**完成标准**：来源 worktree 可定位且唯一；基线、记录与 Git 一致；source 检查不含 E2E；失败时保留现场。

package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md

@@ -1,25 +1,53 @@
-# 集成与清理工作项 Worktree
+# Candidate Merge And Parent Integration
 
-## 集成
+仅由 Lead/integration owner 对状态为 `review` 的 Ticket 调用。
 
-仅生产 Ticket 进入本段；一次性原型不得合入生产分支。
+## 1. 接收 source checkpoint
 
-1. integration owner 确认记录为 `review`、`terminal_action=integrate`，读取 implementation owner 的 Evidence，并验证实际修改未越过 writable/shared owner 合同。`source_checkpoint` 必须是不可变 commit，且与记录 branch 当前 tip 一致、从 `base_sha` 可达。
-2. 确认目标 checkout 正位于 `parent_branch`、index 与项目 working tree 干净，并把当前 HEAD 固定为 `parent_before_sha`。目标不干净、父分支不匹配、其他记录已在同一父分支 `integrating` 或 HEAD 在集成期间变化时停止，不覆盖用户工作。
-3. 将记录原子更新为 `integrating`，设置 `integration.status=running`、`parent_before_sha`、`source_sha` 并递增 `attempts`。中断恢复时先核对记录、Git `MERGE_HEAD` 和当前 HEAD，不重复开始第二次集成。
-4. 恢复已有 `integrating` 记录时只进入一个分支：HEAD 仍等于 `parent_before_sha` 且没有 `MERGE_HEAD` 时恢复同一次尝试；HEAD 已等于 `source_checkpoint`、没有 `MERGE_HEAD` 且 `parent_before_sha` 可达来源时，将其视为已完成但尚未落状态的 fast-forward；`MERGE_HEAD` 等于 `source_checkpoint` 时恢复未完成 merge。其他 HEAD、来源或 merge 状态漂移一律设为 `blocked`，不修改 Git 现场。
-5. 若 `parent_before_sha` 是 `source_checkpoint` 的祖先，先在来源 workspace 运行 Ticket 定向验证、受影响回归、项目 typecheck/lint/build 和适用最小 E2E，再从目标 checkout 执行 `git merge --ff-only <source_checkpoint>`。重读目标 HEAD、tree 和 Evidence，确认 HEAD 精确等于 `source_checkpoint` 后，记录 `method=fast-forward`、`result_sha=source_checkpoint`、空 `conflict_paths`、验证命令与结果、`verification=passed`、Evidence 和 `integration.status=passed`，再把 worktree 状态更新为 `integrated`。这是 fast-forward 的终态，不继续执行 merge-commit 步骤。
-6. 若双方已分叉，从干净目标 checkout 执行 `git merge --no-ff --no-commit <source_checkpoint>`。出现冲突时加载 `<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`，并将本记录作为持久授权来源；不为 `git add`、继续 merge 或集成提交重复请求确认。
-7. 在未提交的合并结果上运行 Ticket 定向验证、受影响回归、项目 typecheck/lint/build 和适用最小 E2E。可由既有意图机械修正的失败最多处理 3 轮；不得放宽断言、删除检查或引入未批准行为。
-8. 验证通过后完成一次集成专用 merge commit，重读 HEAD、parents、tree、diff 和 Evidence，确认父分支为第一 parent、`source_checkpoint` 为第二 parent，记录 `method=merge-commit`、`result_sha`、conflict paths、`verification=passed`、Evidence 与 `integration.status=passed`，再把 worktree 状态更新为 `integrated`。
-9. 冲突需要新产品/架构/安全/迁移决定、修改越过授权路径、验证无法通过、目标状态漂移或提交 hook 无法安全完成时，执行 `git merge --abort`（仅限本流程从干净目标开始的 merge），设置 worktree 与 integration 为 `blocked`，记录最小失败、已通过行为和恢复条件，并保留来源 worktree。
+1. 核对 Ticket、Goal Plan、Evidence 目标、owner 与本地 integration 授权；
+2. 验证来源 worktree clean，branch tip 精确等于 `source_checkpoint`，commit 从 `base_sha` 可达；
+3. 审计实际 diff 未越过 writable/shared owner 合同；
+4. 确认 source-worktree 必跑非 E2E 检查已执行，且没有把 E2E 自报为通过；
+5. 重读父分支 checkout clean、HEAD 与 remote/本地约定，记录 `parent_before_sha`。
 
-Fast-forward 路径的 `result_sha` 等于 `source_checkpoint`；merge-commit 路径必须保持父分支为第一 parent、来源 checkpoint 为第二 parent。任何成功结果都必须能从记录和 Evidence 复核。
+失败时保持 `review`/`blocked`，不开始候选合并。
 
-## 清理
+## 2. 建立 parent-candidate checkout
 
-1. 取得用户对删除 worktree 和分支的授权。
-2. Git provider 从 project root 解析 `specdev-worktree/<work-item-id>`，重验无路径逃逸且与 `git worktree list --porcelain` 的记录一致，再从主工作树移除；native/external 通过对应 provider 管理入口移除。
-3. 确认 worktree 不再注册且工作项目录不存在后删除对应分支。Ticket 将状态更新为 `removed`；原型把 `cleanup_status` 更新为 `clean`。保留项目根 `specdev-worktree/` 统一目录及 `.gitignore` 条目。
+1. 使用 branch `speculo/integration/<change>/<ticket-id>` 和 locator `specdev-worktree/.integration/<ticket-id>`，从最新 `parent_before_sha` 建立 Lead-owned integration worktree；
+2. 如果父 SHA 是 source checkpoint 的祖先，在 candidate checkout 执行 `git merge --ff-only <source_checkpoint>`，`method=fast-forward`；
+3. 否则执行 `git merge --no-ff --no-commit <source_checkpoint>`；
+4. 冲突按 `<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>` 处理。需要新产品决定时执行 `git merge --abort`，记录 blocker 并返回来源 worktree；
+5. 对分叉结果创建一次 Lead-owned candidate merge commit，`method=merge-commit`；
+6. 记录 candidate branch/locator、`candidate_sha`、`source_sha`、冲突路径与 attempts，worktree 状态改为 `integrating`、integration 状态改为 `candidate`。
 
-PR、`terminal_action=retain` 或暂缓集成时保留 worktree。成功集成也不自动清理。清理失败时停止；仅在用户明确要求时使用强制删除。
+重试前从最新父分支重建 candidate branch/worktree；旧 candidate SHA 保存在 Evidence。候选生命周期的重建/回收包含在 local candidate integration 授权中。
+
+## 3. 在候选父状态验证
+
+在 candidate checkout 运行：
+
+- Ticket 受影响集成与回归；
+- 项目要求的 typecheck/lint/build 或其他父状态检查；
+- 仅当 Ticket/Goal Plan `e2e.required=true` 时运行对应 E2E。
+
+每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。可由既有合同机械修正的失败最多处理三轮；不得放宽断言、删除检查或发明行为。
+
+## 4. 推进父分支
+
+全部 required 检查通过后：
+
+1. 重读父分支 HEAD；不等于 `parent_before_sha` 时将 candidate 标记 `stale`，不推进父分支并从步骤 2 重建；
+2. 在父分支 checkout 执行 `git merge --ff-only <candidate_sha>`；候选 merge commit 本身已以父 SHA 为第一祖先，因此不再创建第二个 merge commit；
+3. 重读父 HEAD、tree 与 ancestor 关系，确认 HEAD 精确等于 candidate SHA 且包含 source checkpoint；
+4. 写入 `result_sha=candidate_sha`、`verification=passed`、E2E 最终状态和 Evidence；
+5. integration/status 改为 `passed`/`integrated`，再由 Lead 标记 Ticket Done。
+
+## 5. 失败、清理与恢复
+
+- candidate 检查失败：父分支不动，Ticket 回 `in_progress` 或 `blocked`，来源 worktree 保留；
+- 父 HEAD 漂移：旧 candidate 记 `stale`，完整重建并重跑；
+- 成功后可按 candidate integration 授权回收 transient integration worktree/branch；来源 branch/worktree 不自动清理。获得独立 cleanup 授权并清理后，只将生命周期状态改为 `removed`，完整保留已经通过的集成与 E2E 证据；
+- push、PR、remote merge、deploy、migration 和生产动作仍需各自授权。
+
+**完成标准**：passed 时父 HEAD=result/candidate SHA 且包含 source commit；failed/stale 时父 HEAD 仍为开始该轮记录的父状态或更新后的外部事实，没有本轮候选污染。

package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md

@@ -1,60 +1,63 @@
 ---
 name: subagent-delivery
-description: 交付合同：只为用户已选择委派的 Goal Plan 生成可恢复的原生或外部网页 Agent 派单，并在 Implement 阶段核对基线、候选交付、修正和 Lead 验收。
+description: 动态派单合同：为 Lead 生成受限的 implementation/review/research/test-observation packet，绑定不可变 checkpoint，并在返回时核对 commit、范围和候选声明。
 ---
 
-# SpecDev Subagent Delivery
+# Subagent Delivery
 
-本 Skill 管理一次 **Agent 交付合同**：规划时把 Ticket 压缩成可独立投递的派单块，执行时按同一合同恢复、核对并验收交付。它不拥有新的状态目录；Goal Plan、Ticket、Evidence 和 change 状态仍由调用 work 写入。
+本 Skill 被 P-goal-plan 与 I-implement 调用。它不选择是否使用 Lead 模式：Lead 是固定外层 owner；本 Skill 只保证每次动态派单可恢复、可验收且不产生第二个 SpecDev 状态写入者。
 
 ## 输入
 
-- `operation`：`plan` 或 `execute`；
-- `execution_model`：`native-subagent` 或 `external-web-subagent`；
-- mutation role：`read-only`、`lead-write` 或 `worker-write`，以及独立确定的 workspace allocation；
-- Lead、Ticket、Goal Plan、Spec、适用 ADR/CONTEXT、Wave/Gate 和依赖 Evidence；
-- 项目写、只读和 shared 路径，验证矩阵与当前源码基线；
-- provider、会话或 workspace locator、源码交付方式，以及用户当前明确授权。
+所有调用都必须提供 `operation=plan | dispatch | accept` 与 Lead owner/session locator。其余输入按 operation 判定，不得把后续阶段事实反向要求给 `plan`：
 
-`single-session` Goal Plan 和缺失 Goal Plan 的 Ticket 直接由 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行，不调用本 Skill；只读辅助 Agent 由对应 research/review 能力管理。Lead Team 输入缺失时返回调用方补齐，不猜测 checkpoint、权限或验收结果。
+- `operation=plan`：提供允许的 `task_kind` 集合、implementation subagent 上限、Lead/SpecDev/父分支/E2E 所有权和通用授权边界；Goal Plan 此时可以尚未写入，不要求 Ticket、provider、checkpoint 或 workspace；
+- `operation=dispatch`：提供 `task_kind=implementation | review | research | test-observation`、已存在 Goal Plan（若有）、Ticket/固定审查目标、依赖 Evidence、适用合同、repository、不可变 checkpoint、项目 Agent 指令、workspace/session locator、provider、允许动作、路径边界、检查、停止条件与返回格式；
+- `operation=accept`：提供原 Dispatch Packet、subagent 返回、当前 repository/workspace、预期与实际 checkpoint，以及 Lead 可用于独立核对的 Git/命令事实。
 
-## 流程
+`operation=dispatch` 且 `task_kind=implementation` 时，还必须提供独立 Ticket worktree、branch、`base_sha`、writable/shared owner、implementation commit 授权与 source-worktree 非 E2E 检查。缺失时返回 blocked，不推断权限或创建 current-workspace 写入者。
 
-### 1. 固定 Lead、模型与权限
+## 1. 固定 Lead 与任务类型
 
-一个交付链只有一个 Lead。Lead 保留需求解释、仓库保护、Wave/Gate、shared owner、权限控制、交付集成、独立验收和最终状态同步责任。
+Lead 保留需求解释、DAG/Wave/Gate、shared owner、权限、SpecDev 工件、Evidence、candidate-merge、父分支和最终回复。subagent 不写 Ticket、Map、Goal Plan、Evidence、change status 或父分支。
 
-将本次请求解析为逐动作授权：local changes、implementation commit、local worktree integration、push、PR、remote merge、deploy、migration、production configuration、production feature 和 real user data。未明确授权的动作记为 `not-authorized`；项目指令、历史授权和 Agent 建议不扩大权限。`terminal_action=integrate` 只满足对应 Ticket 的 local worktree integration，不扩展其他动作。
+- implementation 可以写唯一 Ticket worktree，并在授权时创建实现 commit；
+- review/research/test-observation 只读，返回 findings、来源或命令观察；
+- E2E Gate 永远由 Lead 拥有，不能派给 implementation 或只读 agent；Ticket E2E 在 parent-candidate 状态执行，Direct Spec E2E 在 Lead-owned current workspace 执行。
 
-**完成标准**：`operation` 和 `execution_model` 唯一；Lead、授权动作、目标和条件均可判定。
+**完成标准**：Lead、task kind、写入边界和 E2E owner 唯一。
 
-### 2. 固定源码与恢复基线
+## 2. 锁定基线、provider 与授权
 
-记录不可变 `base_sha` 或等价本地基线、分支、`workspace_ref`、工作区状态和适用外部合同版本。GitHub 是源码事实来源时，加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/github-checkpoints.md</Path>`；需要固定附件、私有上下文或未提交改动时，再加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/source-package.md</Path>`。
+记录 repository、branch、`base_sha`/固定审查 SHA、workspace/session locator 和 provider。GitHub 是源码事实来源时加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/github-checkpoints.md</Path>`；需要向外部 provider 发送附件或私有上下文时，取得发送授权后加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/source-package.md</Path>`。
 
-`workspace_ref`、session locator 和附件 locator 必须可迁移，不写机器绝对路径、认证秘密或真实用户数据。
+授权逐动作记录：worktree local changes、implementation commit、外部内容发送、push、PR、remote merge、deploy、migration 和 production actions。Goal Plan 的本地 commit/integration 授权不扩展到远端、清理或生产动作。
 
-**完成标准**：每次派单、恢复、修正和验收都能定位到同一源码与合同版本。
+**完成标准**：每个可变输入绑定 checkpoint；provider 只接收已授权范围；未授权动作不可执行。
 
-### 3. 加载执行分支
+## 3. 生成动态 Dispatch Packet
 
-- `native-subagent`：加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/native-subagent.md</Path>`，完成隔离派单、恢复和返回；
-- `external-web-subagent`：加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/external-web-subagent.md</Path>`，完成能力探测、会话恢复、候选交付与修正。
+`operation=plan` 时只返回通用 Lead delivery contract，不读取尚未生成的 Goal Plan，也不为 Ticket 预分配 agent/provider。
 
-**完成标准**：只加载当前执行模型和实际源码交付方式需要的 reference。
+`operation=dispatch` 时为单次任务生成 Packet：目标、IN/OUT、已锁定决定、固定输入、workspace、writable/read-only/shared paths、允许动作、必跑检查、禁止在 source worktree 运行 E2E、停止条件和返回字段。
 
-### 4. 规划或执行交付合同
+- 原生 Agent：加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/native-subagent.md</Path>`；
+- 外部网页 Agent：加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/external-web-subagent.md</Path>`。
 
-`operation=plan` 时，向调用方返回：里程碑级 Delivery Contract，以及每个 Ticket 的独立 Dispatch Packet。每个派单块必须包含目标、权威输入、边界优先级、路径合同、mutation role、workspace allocation、依赖证据、基线、验证与反向验证、授权、恢复 locator、最多修正轮次和返回字段。`worker-write` 没有独立 workspace 时拒绝规划；read-only 不得返回项目或状态写入。调用方将结果写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`，不复制完整历史对话或 Ticket 全文。
+implementation Packet 必须适合一个上下文独立完成；多个 implementation subagent 由 Lead 控制在 Goal Plan/config 上限内且最多三个。只读 agent 不设置 SpecDev 数字上限，但不得争用可变环境。
 
-`operation=execute` 时，先核对派单块与当前 Goal Plan、Ticket、基线和权限；再接收原生 Worker 或外部 provider 的候选交付，检查范围与事实声明，由 Lead 运行适用验证，并把结果写入 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`。外部声明、截图或模拟结果在 Lead 复核前保持 `unverified`。
+**完成标准**：Packet 可独立投递；目标、checkpoint、路径、权限、检查和返回均可判定。
 
-**完成标准**：规划结果可独立投递；执行结果的每个 `pass` 都有 Lead 可复查证据。
+## 4. 接收与验收候选
 
-### 5. 收敛、阻塞与恢复
+`operation=accept` 时，Lead 核对 Packet、当前父/来源基线、实际路径、dirty 状态、commit 可达性、命令输出和未验证项。外部声明、截图、provider 自报测试和推断保持 `unverified`，直到 Lead 在本地复核。
 
-同一验收项连续失败达到 Goal Plan 的 `max_correction_rounds` 后停止该 Ticket，记录最后基线、失败命令、最小错误、已通过行为、责任方和恢复条件。默认上限为 3；不得通过跳过测试、放宽断言、吞错、删除检查或越过路径合同制造完成。
+implementation 返回必须包含 Ticket ID、workspace locator、最终 commit、dirty 状态、修改路径、非 E2E 检查、失败/未运行项和恢复条件。review/research/test-observation 返回固定输入、findings、来源、命令与未验证声明。Lead 把验收结果写入调用方拥有的 Evidence/状态。
 
-恢复时读取 Goal Plan 的派单块、Ticket、最新 Evidence 和 change/worktree 状态，从最后已验证 checkpoint 继续，不重新决定已锁定事项。完成或阻塞后向调用方返回 Ticket 状态、Evidence 完整路径、workspace/session locator、checkpoint、commit/PR 引用、未验证项和待 Lead E2E。
+**完成标准**：每个 pass 有 Lead 可复查事实；candidate 未被误写为 Done 或父分支结果。
 
-**完成标准**：交付结束于 `review`、`done`、`blocked` 或 `deviated`；状态、Evidence、源码引用和恢复信息一致。
+## 5. 修正与恢复
+
+修正继续使用同一 Ticket 与 worktree，基于最后 source checkpoint 生成新 commit。基线或父分支漂移时由 Lead 暂停派单、重算影响并更新 Packet；契约冲突返回拥有该决定的工件。Lead 可以按当次风险在 Dispatch Packet 中定义停止条件，但 SpecDev 不推断全局修正次数；继续修正已无合理收益或需要上游决定时，返回 blocked、最后可信 checkpoint、失败命令和恢复条件。
+
+**完成标准**：恢复不重新决定已锁定事项；每次候选都有唯一 checkpoint 和明确 owner。

package/template/workflows/specdev/common/skills/subagent-delivery/references/external-web-subagent.md

@@ -1,32 +1,19 @@
-# 外部网页 Subagent 交付
+# External Web Subagent
 
-用户或已批准 Goal Plan 明确选择网页模型时加载；原生能力不足本身不授权向外部 provider 发送上下文。外部输出是候选交付，Lead 的本地核对决定验收状态。
+用户已授权目标 provider 与发送内容范围，且外部网页模型能为当前任务提供实际价值时加载。外部会话永远返回候选，不拥有本地 worktree、commit、SpecDev 状态或 E2E Gate。
 
-## 能力探测与会话
+## 能力与数据门
 
-首次使用或界面变化时实测并记录：provider、稳定 session locator、仓库访问、附件上传与返回、长任务状态和认证交接。Provider 名称只是标识；只有能力差异改变交付路径时才产生分支。
+先确认 provider 能接收的文件、大小、会话恢复、输出格式和数据保留边界。需要源码包时加载 source-package reference，排除凭据、真实用户数据、运行时状态和无关代码；记录 locator、hash 与 checkpoint。能力或授权不足时改用原生/Lead 执行，不降低合同。
 
-登录、账号选择、密码、验证码、Passkey、两步验证、恢复码和 CAPTCHA 由用户在界面内完成。认证秘密不进入派单、源码包、Goal Plan 或 Evidence；发送仓库链接、源码或附件前还必须确认 provider 和内容范围已获授权。
+## 投递与返回
 
-每个独立复杂 Ticket 使用独立会话；强耦合修正可以复用原会话。会话记录绑定 Ticket、branch、checkpoint、附件 hash、最近完整交付和修正轮次。恢复时先定位最后完整输出并核对 checkpoint；不可恢复时，新会话携带旧 locator、当前 checkpoint、已验收摘要和剩余事项。
+Packet 固定目标、范围、合同、checkpoint、路径边界、非 E2E 验证要求和停止条件。外部 provider 返回 patch/文件、修改清单、推理摘要、模拟或自报测试、未验证项和会话 locator。
 
-## 工程派单
+Lead 在 Ticket worktree 中核对附件 hash、应用候选、检查 diff、依赖与锁文件、运行本地非 E2E 检查并创建 implementation commit。外部自报结果、截图或模拟保持 `unverified`；适用 E2E 仍只在 parent-candidate 状态运行。
 
-派单块必须提供：
+## 修正与恢复
 
-1. repository locator、branch、不可变 checkpoint 和源码包 hash；
-2. 用户结果、里程碑位置、相关模块、公共契约和领域不变量；
-3. allowed/read-only/shared 路径、保留行为和依赖策略；
-4. 需要返回的方案、修改清单、patch/源码、测试、实际命令和风险；
-5. mutation role、workspace allocation、当前授权矩阵与逐项验收标准；
-6. 未实际运行的检查必须标记 `unverified`。
+修正轮绑定新的源码 checkpoint 或 candidate hash，不覆盖旧附件。会话无法恢复、输出越界或 contract 冲突时停止并保留最后可信包、失败证据和恢复条件。
 
-公开仓库 URL 使用 `<Url>https://example.com/owner/repository</Url>` 形式并同时给出 branch 与 checkpoint。Provider 无法读取仓库、需要私有上下文或固定工作区快照时使用 source-package 分支。
-
-## 候选交付与修正
-
-Lead 在隔离工作区从派单 checkpoint 应用候选交付，核对附件 hash、修改范围、依赖与锁文件、数据和安全边界，再运行 Ticket 与 Goal Plan 要求的验证。模拟结果、provider 自报测试和静态推断分别标记，不替代本地或目标环境证据。
-
-修正请求必须包含未通过项、checkpoint、命令与退出状态、最小错误、项目位置、正确约束和必须保留的已通过行为。每轮重新核对 checkpoint、范围、受影响检查和验收矩阵；达到修正上限后形成 blocker。
-
-**完成标准**：每轮会话和候选交付绑定唯一基线；每个 `pass` 有 Lead 独立证据，未验证项保持显式。
+**完成标准**：发送范围有授权且可审计；本地 commit 与验收完全由 Lead 拥有；外部声明不被当作通过证据。

package/template/workflows/specdev/common/skills/subagent-delivery/references/native-subagent.md

@@ -1,34 +1,24 @@
-# 原生 Subagent 交付
+# Native Subagent
 
-当前 Lead 能直接创建和管理隔离 Agent 时加载。
+Lead 可以直接创建和管理隔离 Agent 时加载。
 
-## 派单与隔离
+## 派单
 
-每个 Ticket 使用唯一 Agent 标识，并接收一个独立 Dispatch Packet：
+Lead 为每个 Agent 发送一个完整 Dispatch Packet。implementation Agent 只进入指定 Ticket worktree；review/research/test-observation Agent 只读取固定输入。并行前核对 Ticket 依赖与 writable/shared path，不以“不同 Agent”代替路径隔离。
 
-```text
-DISPATCH ticket=<id> wave=<wave> gate=<gate>
-baseline=<sha> branch=<branch> workspace=<workspace-ref>
-ticket_path=<full-ticket-path> evidence_path=<full-evidence-path>
-```
+Packet 对 implementation 明确：
 
-派单块还必须给出项目 `writable_paths`、`read_only_paths`、`shared_paths`、完成的依赖 Evidence、合同 ID、验证矩阵、反向验证、权限和偏差升级方式。Agent 先核对基线与路径，再用不超过 10 行的开工回执记录目标、顺序和最大风险；回执写入 Ticket Evidence，不新增进度文件。
-
-派单必须标记 mutation role。`read-only` Agent 只返回结论；`lead-write` 不把项目写入委派给 Agent；`worker-write` 必须引用已规划的独立 workspace，由其 integration owner 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 管理。多个并行写入 Ticket 固定同一 `base_sha`，分别使用独立分支和 `workspace_ref`；Agent 只修改获准项目路径，只把 Ticket 推进到 `review`。
-
-## 审查与修正
-
-候选交付必须同时通过：
-
-- 标准轴：正确性、架构、错误处理、安全、依赖和测试质量；
-- 规范轴：Spec、ADR、Ticket、Goal Plan、路径合同和验收映射；
-- Lead 复跑的定向验证与适用回归；
-- 对可能静默失效的门禁执行一次受控反向验证，并恢复绿色基线。
-
-失败时沿用同一 Agent 或建立明确继任者，返回失败标准、命令与退出状态、最小错误、文件位置、正确约束、当前 checkpoint 和必须保留的已通过行为。达到修正上限后标记 blocker，不无限重派。
+- Ticket、Goal Plan、依赖 Evidence 与 `base_sha`；
+- branch、portable `workspace_ref`、writable/read-only/shared paths；
+- 允许 worktree local changes 与 implementation commit；
+- 单元、组件、静态、类型、lint/build 等适用非 E2E 检查；
+- E2E 由 Lead 在 parent-candidate 状态执行；
+- 越界、合同冲突、基线漂移和无法提交时立即停止。
 
 ## 返回
 
-Agent 返回 Ticket 状态、`<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`、`workspace_ref`、checkpoint、commit/PR 引用和待 Lead E2E。Lead 负责候选验收、回归、Gate 判断和状态同步；只有 workspace allocation 指定时才承担 integration owner。逻辑冲突返回契约 owner，不机械选择某一侧版本。
+implementation Agent 返回 Ticket ID、workspace locator、最终 commit、`git status`、修改路径、命令/结果、未运行项、冲突和恢复条件，不写 SpecDev Evidence。只读 Agent 返回固定 checkpoint、findings、来源、命令观察和未验证项。
+
+Lead 重读 worktree、验证 commit 可达且 tip 一致、检查实际 diff 与路径合同，再决定接受、修正或 blocked。接受的 implementation 候选进入 dev-worktree candidate-merge；只读结论由 Lead 写入对应权威工件。
 
-**完成标准**：派单、工作区、路径修改、审查、修正和返回均可由 Goal Plan、Evidence 与 change 状态恢复。
+**完成标准**：原生 Agent 的写入与返回均绑定一个 Packet；Lead 可以独立复现其事实声明。