@namewta/speculo 2.0.4 → 2.0.5

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 (81) hide show
  1. package/package.json +1 -1
  2. package/template/canonical/canonical-specdev-goal-plan.md +2145 -1003
  3. package/template/canonical/canonical-specdev-grill-with-docs.md +1948 -506
  4. package/template/canonical/canonical-specdev-spec.md +2046 -604
  5. package/template/canonical/canonical-specdev-tickets.md +1978 -518
  6. package/template/canonical/canonical-specdev-wayfinder.md +2393 -951
  7. package/template/references/coordination/coordination-contract.md +7 -5
  8. package/template/references/coordination/result-and-recovery.md +1 -1
  9. package/template/references/coordination/session-files.md +2 -2
  10. package/template/references/coordination/task-brief.md +4 -4
  11. package/template/references/retrospective/references/friction-taxonomy.md +1 -1
  12. package/template/references/writing-for-agents/references/project-skill-maintenance.md +29 -0
  13. package/template/references/writing-for-agents/writing-contract.md +2 -0
  14. package/template/workflows/specdev/SKILL.md +1 -1
  15. package/template/workflows/specdev/common/README.md +1 -1
  16. package/template/workflows/specdev/common/rules/artifact-contract.md +1 -1
  17. package/template/workflows/specdev/common/rules/change-completion.md +6 -6
  18. package/template/workflows/specdev/common/rules/domain-runtime.md +2 -2
  19. package/template/workflows/specdev/common/rules/evidence-and-verification.md +17 -34
  20. package/template/workflows/specdev/common/rules/execution-policy.md +24 -16
  21. package/template/workflows/specdev/common/rules/operating-governance.md +1 -1
  22. package/template/workflows/specdev/common/rules/parent-implementation-orchestration.md +4 -2
  23. package/template/workflows/specdev/common/rules/path-ownership.md +9 -7
  24. package/template/workflows/specdev/common/rules/workflow-routing.md +1 -1
  25. package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md +6 -2
  26. package/template/workflows/specdev/common/schemas/execution-context.schema.json +67 -0
  27. package/template/workflows/specdev/common/schemas/execution-record.schema.json +154 -0
  28. package/template/workflows/specdev/common/schemas/goal-plan.schema.json +15 -55
  29. package/template/workflows/specdev/common/schemas/implementation-plan.schema.json +15 -55
  30. package/template/workflows/specdev/common/schemas/retro-approval.schema.json +44 -0
  31. package/template/workflows/specdev/common/schemas/retro-archive.schema.json +99 -0
  32. package/template/workflows/specdev/common/schemas/retro-execution.schema.json +112 -0
  33. package/template/workflows/specdev/common/schemas/retro-upgrade.schema.json +163 -0
  34. package/template/workflows/specdev/common/schemas/retrospective.schema.json +119 -14
  35. package/template/workflows/specdev/common/skills/code-review/references/review-evidence.md +2 -2
  36. package/template/workflows/specdev/common/skills/code-review/references/source-discovery.md +2 -0
  37. package/template/workflows/specdev/common/skills/code-review/references/working-tree-review.md +1 -1
  38. package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md +15 -34
  39. package/template/workflows/specdev/common/skills/dev-worktree/references/create.md +27 -56
  40. package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md +10 -54
  41. package/template/workflows/specdev/common/tools/README.md +10 -0
  42. package/template/workflows/specdev/common/tools/delivery-artifacts.mjs +4 -4
  43. package/template/workflows/specdev/common/tools/execution-context.mjs +104 -0
  44. package/template/workflows/specdev/common/tools/plan-contract.mjs +3 -1
  45. package/template/workflows/specdev/common/tools/review-evidence.mjs +2 -2
  46. package/template/workflows/specdev/common/tools/tests/engineering.test.mjs +2 -2
  47. package/template/workflows/specdev/common/tools/tests/review-fixture.mjs +4 -4
  48. package/template/workflows/specdev/common/tools/ticket-control.mjs +17 -12
  49. package/template/workflows/specdev/common/tools/validate-retro.mjs +331 -0
  50. package/template/workflows/specdev/common/tools/validate-specdev.mjs +135 -105
  51. package/template/workflows/specdev/specdev-a-archive-and-consolidate/SKILL.md +2 -1
  52. package/template/workflows/specdev/specdev-a-archive-and-consolidate/references/operation-contract.md +2 -0
  53. package/template/workflows/specdev/specdev-a-archive-and-consolidate/references/retro-archive.md +27 -0
  54. package/template/workflows/specdev/specdev-c-code-review/SKILL.md +1 -1
  55. package/template/workflows/specdev/specdev-i-implement/SKILL.md +3 -3
  56. package/template/workflows/specdev/specdev-i-implement/assets/evidence-template.md +37 -29
  57. package/template/workflows/specdev/specdev-i-implement/references/execution-preflight.md +16 -16
  58. package/template/workflows/specdev/specdev-i-implement/references/implementation-procedure.md +21 -37
  59. package/template/workflows/specdev/specdev-i-implement/references/merge-conflict-protocol.md +8 -18
  60. package/template/workflows/specdev/specdev-p-goal-plan/SKILL.md +3 -3
  61. package/template/workflows/specdev/specdev-p-goal-plan/assets/goal-plan-template.md +23 -26
  62. package/template/workflows/specdev/specdev-p-goal-plan/references/completion-control.md +11 -14
  63. package/template/workflows/specdev/specdev-p-goal-plan/references/lead-orchestration.md +12 -33
  64. package/template/workflows/specdev/specdev-p-goal-plan/references/map-control.md +1 -1
  65. package/template/workflows/specdev/specdev-p-goal-plan/references/multi-change-plan.md +11 -16
  66. package/template/workflows/specdev/specdev-p-goal-plan/references/multi-conflict-and-drift.md +2 -2
  67. package/template/workflows/specdev/specdev-p-goal-plan/references/multi-execution-loop.md +6 -6
  68. package/template/workflows/specdev/specdev-p-goal-plan/references/orchestration-protocol.md +13 -44
  69. package/template/workflows/specdev/specdev-p-goal-plan/references/planning-modes.md +18 -25
  70. package/template/workflows/specdev/specdev-p-goal-plan/references/single-change-plan.md +16 -16
  71. package/template/workflows/specdev/specdev-r-retro/SKILL.md +15 -11
  72. package/template/workflows/specdev/specdev-r-retro/assets/retro-template.md +26 -14
  73. package/template/workflows/specdev/specdev-r-retro/assets/upgrade-plan-template.md +41 -0
  74. package/template/workflows/specdev/specdev-r-retro/references/development-retrospective.md +42 -0
  75. package/template/workflows/specdev/specdev-r-retro/references/records.md +47 -0
  76. package/template/workflows/specdev/specdev-r-retro/references/skill-upgrade.md +13 -0
  77. package/template/workflows/specdev/specdev-t-tickets/SKILL.md +2 -0
  78. package/template/workflows/specdev/specdev-t-tickets/assets/ticket-template.md +1 -1
  79. package/template/workflows/specdev/specdev-t-tickets/assets/tickets-map-template.md +6 -6
  80. package/template/workflows/specdev/specdev-t-tickets/references/planning-procedure.md +2 -2
  81. package/template/workflows/specdev/specdev-t-tickets/references/ticket-readiness.md +3 -3
@@ -32,12 +32,14 @@
32
32
 
33
33
  ## 工作区和并行
34
34
 
35
- 执行输入、编排方式和工作区是三个独立选择。工作区继承当前有效计划或用户选择,无 Goal 时由当前 Work owner 在原工件记录;未指定默认 current,已有选择不重复问。Herdr 不强制 worktree,原生 agent team 也不隐含开启 worktree。只读审查使用固定候选所在工作区,不为审查本身创建实现 worktree。
35
+ 票据调度、Agent 编排和工作区分别决定。serial 表示逐票完成,不限制同票内部协作;parallel/auto 允许按 DAG、路径、共享资源及实际能力推进多票,不强制派遣。按用户、项目初始化和 Work/Skill 要求选择实现者与工具;Lead 是状态/验收角色,不代表只能独自实现。
36
36
 
37
- - current:严格单 writer,Lead 自己实现时也计入。上一任务的写入是否结束不明时,先查询真实工具,不开始冲突写入。
38
- - required:使用原 Work 的独立 worktree 和 candidate 集成合同;SpecDev 可以是 Ticket 或整个 Direct Spec change。并行数取实际存在的配置、有效计划和平台能力的共同上限;无计划默认一个实现单元。Lead 及宿主原生协作者参与代码写入同样计数。另核对 shared paths、端口、数据库等实际资源。
39
- - review/research/test-observation 对业务文件默认只读;可写本任务明确分配的报告,测试输出仅写原任务允许的缓存或产物位置。
40
- - worktree 是工作副本,不是沙箱。Speculo 不提供运行期强制隔离、进程监管、租约或任务锁服务。
37
+ 工作区继承用户和 owning Work 的选择,已有选择不重复问。SpecDev 使用 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 的 change 级唯一工作区,默认复用 current;所有 Ticket 和协作者复用,Herdr、CLI、subagent/team 不触发额外 worktree。跨 change 保留成员各自选择。
38
+
39
+ - 共享工作区的写集明确 owner;不相交且资源无冲突可并行。Git index、提交、checkout/merge 和全局验证协调串行,不暂存他人改动。
40
+ - review 使用固定输入,相关 writer 停写并回读快照;输入漂移后重验。review/research/test-observation 默认只读业务文件,可写获分配报告和允许的缓存/测试产物。
41
+ - 票据数量、实现者人数和 workspace 数量各自核对,不能互相换算。明确的项目/宿主限制继续生效。
42
+ - worktree 是工作副本,不是沙箱;Speculo 不提供运行期进程监管、租约或任务锁服务。
41
43
 
42
44
  ## 记录和接续
43
45
 
@@ -14,7 +14,7 @@ REPORT 的 completed 只表示候选已交回;blocked、failed、cancelled 分
14
14
 
15
15
  ## 修复与集成
16
16
 
17
- 同范围 finding 有明确修复路径时,继续原 Ticket 的修复和复验,不逐个要求用户确认、不为每个 finding 新建 Ticket。current 由 Lead 在原 workspace 核验;required 使用原 source/candidate 集成合同。父分支推进、commit 和外部动作继续核对原授权。
17
+ 同范围 finding 有明确修复路径时继续原票修复和复验,不逐项询问、不为每个 finding 新建票。复用 change 选定工作区,冻结新的实际输入;提交、合并和外部动作继续核对原授权,不创建额外 worktree。
18
18
 
19
19
  达到原 integration_attempt_limit 或重复相同 blocker 时,在现有 Evidence 记录共同失败模式、最可能原因、下一轮具体改变、下一 owner/路由。只有有实质变化和新证据才开始下一尝试。更换执行者、清空 attempts 或再次询问相同问题不构成变化。
20
20
 
@@ -23,7 +23,7 @@ Lead 将当前交接说明要求的必要上下文写入 `TASK.md`,使用以
23
23
  |---|---|
24
24
  | 身份与目标 | session/task、implementation/review/research/test-observation、change/Ticket(实际存在时)、Lead、执行者和成功定义 |
25
25
  | 输入 | 真实 Work/Skill 入口、必要规格和依赖产物、已锁定决定;前序背景引用原报告与其中的历史入口 |
26
- | 工作区与范围 | current/required、真实执行位置与基线、允许/只读/共享路径及 owner、已获授权的动作、停止条件 |
26
+ | 工作区与范围 | 选定 change 工作区、真实执行位置与基线、允许/只读/共享路径及 owner、已获授权的动作、停止条件 |
27
27
  | 验收 | 要运行的检查、可观察通过标准、未在执行者环境运行的 Gate 及其 owner |
28
28
  | 返回与通信 | 准确报告位置、提问/通知的工具原生通道、实际调用方式与工具句柄;尚未取得的句柄由 Lead 在调用返回后补记 |
29
29
 
@@ -35,7 +35,7 @@ Lead 在派遣前形成完整输入、检查并写入,再回读确认后投递
35
35
 
36
36
  派遣前确认执行者能读输入和必要材料,且能交付报告。独立工作区需要明确实际可读输入和可写报告位置;只有工具返回文本时,由 Lead 原样捕获到正式报告,标注 `Captured-by: Lead` 和原始消息 locator,不补造执行者的验证结果。执行者和 Lead 不同时写同一报告。
37
37
 
38
- 只读任务仅可写被明确分配的报告及允许的测试产物,业务文件仍只读。报告路径不同允许独立交付,不放宽 current 的单一代码 writer 约束。所有文件先完成候选内容,再使用可用的同目录临时文件与不覆盖目标的原子落盘方式,写前检查目标未被占用、写后回读;已有正式报告不覆盖,发现冲突交 Lead 处理。未完成的临时文件不是报告,也不能作为完成信号。
38
+ 只读任务仅可写被明确分配的报告及允许的测试产物,业务文件仍只读。报告路径不同允许独立交付,仍须遵守当前 Work 的写集和共享资源 owner 约束。所有文件先完成候选内容,再使用可用的同目录临时文件与不覆盖目标的原子落盘方式,写前检查目标未被占用、写后回读;已有正式报告不覆盖,发现冲突交 Lead 处理。未完成的临时文件不是报告,也不能作为完成信号。
39
39
 
40
40
  ## 报告与通知
41
41
 
@@ -12,7 +12,7 @@
12
12
  | 能力 | 实际 Work 业务 ID、可读取的 SKILL.md 和本次阶段;原 source/合同摘要可用于发现漂移 |
13
13
  | 输入 | 目标、IN/OUT、已锁定决定、必要 Spec、依赖 Evidence、当前基线或固定审查 SHA |
14
14
  | 项目 Skill | Ticket implementation 提供 Map → 适用 `ALL`/本票的项目 Skill → Ticket,矩阵是最低必读集合;Direct Spec 提供唯一获批规格、项目 Agent 指令、命中的项目 Skill、AC/验证与路径合同,不制造 Ticket/Map;review 提供固定候选及对应轴的来源 |
15
- | 工作区 | 有效计划或当前 Work 选择的 current 或 required、真实项目根与执行路径/branch、parent/base、允许和共享写路径及 owner;不要用执行者 cwd 猜测方法或数据根 |
15
+ | 工作区 | 有效计划或当前 Work 选择的 选定 change 工作区、真实项目根与执行路径/branch、parent/base、允许和共享写路径及 owner;不要用执行者 cwd 猜测方法或数据根 |
16
16
  | 调用 | 当前宿主正常执行,或用户明确选择的 CLI 交互/调用、Herdr、Orca;实际工具、模型已知值、所属主机及会话 locator,不记录秘密;文件交接明确 session/task 与原生句柄的对应关系 |
17
17
  | 边界 | 本次真实允许的动作、实现 commit 权限、检查、E2E owner、停止条件、可观察验收标准、准确报告位置与原生提问/通知通道 |
18
18
  | 父 Goal | 存在父 Implementation Map/Plan 时附实际 revision、组合 task ID、依赖 Gate、并行上限和集成次序 |
@@ -23,7 +23,7 @@
23
23
 
24
24
  交给执行者的说明必须明确:
25
25
 
26
- > 先读绑定的真实 Work SKILL.md,按 task 上下文只处理指定目标、阶段和工作区。遵守同一 Work 的方法、TDD、检查与质量门;不要成为 Lead,不递归启动 Goal,不修改正式 Ticket、Map、Goal Plan、Evidence、业务状态或授权。宿主原生协作仍受本次写集、单 writer 和权限约束;不擅自跨 CLI 再派单或扩大任务。缺输入、发生冲突或需要额外权利时向 Lead 返回问题与证据。
26
+ > 先读绑定的真实 Work SKILL.md,按 task 上下文只处理指定目标、阶段和工作区。遵守同一 Work 的方法、TDD、检查与质量门;不要成为 Lead,不递归启动 Goal,不修改正式 Ticket、Map、Goal Plan、Evidence、业务状态或授权。宿主原生协作仍受本次写集、共享资源 owner 和权限约束;不擅自跨 CLI 再派单或扩大任务。缺输入、发生冲突或需要额外权利时向 Lead 返回问题与证据。
27
27
 
28
28
  采用 TASK/REPORT 交接时,TASK 还必须包含派遣文件合同中的历史定位指令:交付前主动查找并核验本次会话的主机、真实入口、会话 ID、可读性与本任务范围;无法取得的事实说明原因,不猜测路径。
29
29
 
@@ -31,12 +31,12 @@ Lead 自行执行使用同一 Work 的 lead 上下文;不伪造外部任务或
31
31
 
32
32
  ## 任务类型与返回
33
33
 
34
- - implementation:只改分配路径,按有效计划或当前 Work 合同执行 current 或 required 流程;返回实际修改、checkpoint/commit(已授权且适用时)、dirty 状态、命令及退出码、非 E2E 检查、未运行项和 blocker。
34
+ - implementation:只改分配路径,按有效计划或当前 Work 合同执行 选定 change 工作区 流程;返回实际修改、checkpoint/commit(已授权且适用时)、dirty 状态、命令及退出码、非 E2E 检查、未运行项和 blocker。
35
35
  - review:只读固定候选,返回 findings、位置、依据、影响和未验证项;不直接修改通过标准或正式 Evidence。
36
36
  - research:返回来源、观察、结论及不确定性,关键外部 claim 对应具体来源。
37
37
  - test-observation:运行或观察原任务允许的检查;遵守缓存/产物路径,只返回事实,不接管 E2E Gate。
38
38
 
39
- current 同时只允许一个实现 writer,包括 Lead。required 保留 source worktree 检查与 Lead parent-candidate E2E 的分工。任务结束、会话空闲和写入停止分别核对。
39
+ 共享工作区按授权写集和语义资源协调并行,Git index 操作串行;冻结审查输入/整体检查前停止相关 writer。票据调度不限制同票 Agent 合作,任务结束、会话空闲和写入停止分别核对。
40
40
 
41
41
  ## 条件性交付
42
42
 
@@ -8,7 +8,7 @@
8
8
 
9
9
  1. **当前对话上下文** —— 本次会话激活过的 command / workflow;用户在哪一步卡住、追问、返工;为绕开限制做了哪些手动动作;哪些指令被误解。
10
10
  2. **命令产物** —— `<Path>{roots.state}/commands/{command}/*.md</Path>`:其中记录的验证失败、未完成和阻塞点是一手摩擦。
11
- 3. **change 状态机** —— 按所属 workflow schema 读取 `<Path>{roots.state}/{workflow}/changes/{change}/.status.json</Path>`;SpecDev 使用 current_work、works_run、真实工件和失败记录,不假定存在 phase_history。停滞时间仅为线索,不能推断用户动机或问题根因。
11
+ 3. **change 状态与事实** —— 按所属 workflow 合同读取真实负责工件。SpecDev 从 README 唯一 Outcome、计划/Ticket/Evidence 与失败记录取证,不读取旧 current_work/works_run 镜像;其他领域仍按自身 schema。停滞时间仅为线索,不能推断用户动机或问题根因。
12
12
  4. **change 产物正文** —— 所属 workflow 的 Spec、Ticket、Evidence、diagnosis.md 等真实工件中显式写下的待澄清、风险和阻塞;不臆造不存在的文件。
13
13
  5. **沉淀教训** —— 各 workflow 声明的 lessons/knowledge store:已记录但尚未转成改进项的教训,用于去重与佐证频率。
14
14
  6. **契约落差** —— 实际产物路径、frontmatter、命名是否偏离所属入口的合同及 schema;不同工件命名分别判断,不能强制全部使用日期前缀。
@@ -0,0 +1,29 @@
1
+ # 项目 Skill 创建与维护
2
+
3
+ 仅在调用方拥有明确项目根、证据范围和项目 Skill 写入授权时使用。调用方拥有方案、确认、执行回执及恢复位置;本方法不创建 namespace,不把共享写作参考变成新 Command。
4
+
5
+ ## 发现与筛选
6
+
7
+ 1. 先枚举 `.agents/skills/` 的名称和 description,再读取匹配的入口及必要 reference。查现有项目标准、源码/模板、消费者、配置、测试和 CI,核对旧结论现在是否成立。
8
+ 2. 按职责与触发匹配已有 Skill,优先升级。新增须同时具备独立触发、重复使用价值、充分项目证据及清晰边界;仅局部解释放入原 Skill reference。语言或目录数量不决定 Skill 数量。
9
+ 3. 区分项目自有源、Builder 管理内容和宿主投影。已安装 Speculo 的投影清单位于 `<Path>{roots.state}/projections.json</Path>`,投影不能直接修改;回到真实源/安装 owner。Builder 管理的内容使用 `<Path>{roots.commands}/engineering-standards-builder/references/rules/14-generation-contract.md</Path>` 的清单、刷新和验证合同,采用当前调用的窄范围,不隐式启动全仓扫描或接管清单外 Skill。没有对应资源时仅阻塞该分支。
10
+
11
+ ## 形成候选
12
+
13
+ 每个候选列出原文依据、适用范围、当前事实、触发变化、精确目标、owner、保留/更新/新增及验证。机械规则交项目既有检查体系;判断规则放在 reviewer 的标准分支,已有 CODING_STANDARDS/standards Skill 是权威就引用它。可复用执行过程才进入项目 Skill。
14
+
15
+ 按 `<Path>{roots.references}/writing-for-agents/references/document-contract.md</Path>` 保全编辑前内容、模式、链接、许可、用户决定和有效例外。保留 `name`/目录一致、必要 frontmatter 和宿主配置;新增默认使用标准 name/description,不把 Claude 专有字段复制到所有宿主。
16
+
17
+ 入口写清触发、输入、步骤、退出和验收;分支资料就近引用。引用项目现有事实源,说明何时读、解决什么问题、如何验证,不复制源码和完整日志。经验来源与历史取舍放在 reference,入口不堆复盘流水账。
18
+
19
+ 升级同时修订或移除已经过时、重复和被替代的内容,保留来源及理由;没有足够证据则不强行改动。重命名/删除整个 Skill 不包含在默认更新、新增授权中,需在具体方案中另列动作及调用方迁移。
20
+
21
+ ## 应用与验证
22
+
23
+ 调用方先给出完整候选。没有覆盖候选的具体批准时只交方案;批准已覆盖的范围由入口核对后直接执行,不逐文件重复询问。写前重验目标原始字节、当前事实、所有权和相关 pending/lock/recovery;漂移停止重叠写集。
24
+
25
+ 候选先通过 YAML、名称、触发、引用及适用宿主格式验证,随后原子替换单个文件并回读;跨文件不声称整体原子。更新保留原模式,失败依据 before-image 与实际落地结果恢复。新目标默认无覆盖创建,不能将软链接替换为普通文件。
26
+
27
+ 验证既包括应触发/近邻不触发,也包括正常、缺失输入和失败边界;运行项目现有相关检查,记录命令/退出码。Builder 内容运行其原生成物 validator。只有静态验证时明确未观察宿主真实调用。相同证据、事实与决定重复执行应无无意义差异,不为更新时间戳重写整个 Skill。
28
+
29
+ 返回实际更新/新增/保留、验证结果、未完成项和恢复位置。代码、CI、远程操作及 ADR/context 写入仍由调用方路由到原 owner;本合同不授予这些动作权限。
@@ -10,6 +10,8 @@
10
10
 
11
11
  当前工程事实维护或明确基线请求直接读取 [局部事实方法](references/current-facts-docs.md);它不包含 docs-sync 的全局/Git/state 编排。
12
12
 
13
+ 明确要求根据项目事实或复盘经验创建、更新 `.agents/skills/` 时读取 [项目 Skill 维护](references/project-skill-maintenance.md)。它负责证据筛选、已有能力优先升级与缺失能力新增;具体方案、批准和记录归调用方,不因一次文档编辑自动迭代 Skills。
14
+
13
15
  ## 宿主适配
14
16
 
15
17
  Claude 的显式调用使用 disable-model-invocation;Codex 使用 agents/openai.yaml 中 policy.allow_implicit_invocation=false。metadata 仅描述策略,不授予权限。Speculo 的分发路径不等于宿主原生发现目录,安装/启用需由对应宿主方式完成;不要复制到系统或插件缓存。
@@ -29,7 +29,7 @@ metadata:
29
29
  - **specdev/learn** — 学习与图解:<Path>{roots.workflows}/specdev/specdev-l-learn/SKILL.md</Path>
30
30
  - **specdev/goal-plan** — Goal 规划与执行:<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>
31
31
  - **specdev/prototype** — 逻辑与 UI 原型:<Path>{roots.workflows}/specdev/specdev-p-prototype/SKILL.md</Path>
32
- - **specdev/retro** — 开发复盘:<Path>{roots.workflows}/specdev/specdev-r-retro/SKILL.md</Path>
32
+ - **specdev/retro** — 开发复盘与项目 Skill 迭代:<Path>{roots.workflows}/specdev/specdev-r-retro/SKILL.md</Path>
33
33
  - **specdev/review-architecture** — 架构审查:<Path>{roots.workflows}/specdev/specdev-r-review-architecture/SKILL.md</Path>
34
34
  - **specdev/spec** — 编写 Spec:<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>
35
35
  - **specdev/tickets** — 编写计划型 Tickets:<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>
@@ -58,7 +58,7 @@
58
58
  - 包与 change 校验器:`<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`
59
59
  - 校验器说明:`<Path>{roots.workflows}/specdev/common/tools/README.md</Path>`
60
60
  - 外部技术研究 Skill:`<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`
61
- - Ticket worktree Skill:`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`;仅 required Ticket 使用 source → parent-candidate → parent 状态机,current Ticket 使用 current workspace/direct-parent
61
+ - Change worktree Skill:<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>;创建/复用一个 change 工作区,所有票据和协作者共用,串并行不增加 worktree。
62
62
  - 动态 Agent 交付合同 Skill:`<Path>{roots.references}/coordination/task-brief.md</Path>`;P-goal-plan 可建立子 change Lead 合同,I-implement 在执行期派单与验收,Goal 编排的全局门约束
63
63
  - 双轴代码审查 Skill:`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
64
64
 
@@ -99,7 +99,7 @@ W 的 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 只
99
99
  ## 新增工件 owner
100
100
 
101
101
  - T:<Path>{roots.state}/specdev/changes/{change}/pull-requests/PR-###.md</Path> 拥有 PR 交付回执;<Path>{roots.state}/specdev/triage-runs/TRI-###.md</Path> 拥有独立远程操作,绝不复用 external_action/publish_action/capture。
102
- - R-retro:<Path>{roots.state}/specdev/changes/{change}/retro/RETRO-###.md</Path> 拥有活动复盘建议和来源;不成为永久知识。
102
+ - R-retro:<Path>{roots.state}/specdev/retro/{retro}/RETRO.md</Path> 拥有独立复盘及原文来源;<Path>{roots.state}/specdev/retro/{upgrade}/PLAN.md</Path> 拥有跨报告筛选、具体升级方案与执行依据。`retro`/`upgrade` 是日期主题 ID;按 <Path>{roots.workflows}/specdev/specdev-r-retro/references/records.md</Path> 保存,不成为永久知识或 change 完成证据。A 只拥有已批准的移动/封存。
103
103
  - P:<Path>{roots.state}/specdev/changes/{change}/prototypes/LOGIC-NNN/logic.md</Path> 记录逻辑模型与浏览器证据;index.html 是可运行原型,ready 时 hash 与记录一致。
104
104
  - 来源更新:<Path>{roots.state}/specdev/changes/{change}/source.md</Path> 冻结后保持不变。T 将后续读取写入 <Path>{roots.state}/specdev/changes/{change}/sources/SRC-###.md</Path>,记录 replaces、固定 SHA/hash、完整性和原 locator,triage 正文选择有效快照;不得把新远程事实自动升级为已接受 Spec。
105
105
 
@@ -9,17 +9,17 @@
9
9
 
10
10
  一个 change 只有同时满足以下条件才能 completed:
11
11
 
12
- 1. 所有计划内 Ticket 为 done,或因权威事实无需改动而记录为 cancelled;Direct Spec/非实现流程有等价验收;required Direct Spec 的执行记录必须 integrated/removed,父 HEAD 为 result 且包含 source,候选与 required 验证通过。
13
- 2. required Ticket 有 source commit、passed candidate、父分支 result SHA,且父分支包含 source commit;current Ticket 有 implementation commit、passed direct-parent 验证和父分支 result SHA;对应 Ticket Evidence 的 workspace/集成记录均完整;不要求 JSON 镜像。
12
+ 1. 所有计划内 Ticket 为 done,或因权威事实无需改动而有依据地 cancelled;Direct Spec/非实现流程有等价验收。
13
+ 2. 每票的原执行记录 verified,实际改动、AC、checkpoint、独立审查和验证证据完整;Direct Spec 有等价证据。未提交工作副本快照可作为交付,不强制 commit 或合并。
14
14
  3. 每个行为有 Lead Evidence,全部 Spec 合同与 Goal Gate 可定位。
15
- 4. current Ticket 的 current-workspace 检查/回归和适用 E2E,或 required Ticket 的 source-worktree 非 E2E 检查、parent-candidate 集成/回归和 required E2E 已通过;not-required 有理由。
15
+ 4. 选定 change 工作区中的适用单元/组件、集成/回归和 Lead-owned E2E 已通过;not-required 有真实理由。
16
16
  5. 迁移、发布、监控、恢复和不可逆批准已完成或明确不适用。
17
- 6. 没有未批准 deviation、blocker、unverified、活动 candidate 或未集成 source checkpoint。
17
+ 6. 没有未批准 deviation、blocker、unverified 或活动 writer;明确承诺的 Git/外部交付按原约定完成或获明确处置,不虚构未发生的集成。
18
18
  7. Ticket、Map 的依赖/导航、Goal Plan、Evidence、README 与实际 Git 一致;不复制单票状态。
19
19
 
20
20
  UI 实施还需 Evidence 对照已批准 change DESIGN、固定基线与页面/状态验收;原型截图不代替实现的真实渲染。设计漂移或未确认例外按 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 返回 owner,不能以票全 done 消除缺口。
21
21
 
22
- Evidence-only Done 和 empty commit 不满足完成门.
22
+ 只有结论而无实际改动/验收证据不能 Done;无需改动须有权威依据并 cancelled,不用 empty commit 代替。
23
23
 
24
24
  L 新建的学习专用 change 属于非实现终点:以 README 的学习 scope、逐 AC 实际验证及 learning 图解/索引完成轻量验收,由 L 原 owner 在本轮交付后结束。已有开发 change 的学习材料不替代其实现完成门;向 completed/cancelled 对象续加学习图解不重开或重新判定原 Outcome。学习的选择与恢复由 <Path>{roots.workflows}/specdev/specdev-l-learn/SKILL.md</Path> 负责。
25
25
 
@@ -38,7 +38,7 @@ Owner 依据来自原 Goal/Implementation Plan、I 的真实会话或非实现
38
38
 
39
39
  远程动作不参与本地完成判定。Triage `external_action` 为 `pending-close`/`close-failed` 时先 reconcile;`closed`、`waived` 或 `not-applicable` 才允许 Archive。Triage `publish_action` 为 `pending`/`publish-failed` 时先恢复或结束 publish;`not-requested`、`published` 或 `waived` 才允许 Archive。`not-requested` 是默认,未点过 publish 的 change 不被新模式绑架。归档后工件只读。
40
40
 
41
- **完成标准**:完成声明可由本地工件、Git 与验证重建;只有一个 owner 命中;失败 candidate 不污染父分支。
41
+ **完成标准**:完成声明可由原工件、真实工作区与验证重建,只有一个 owner;完成不自动授权提交、合并或工作区清理。
42
42
 
43
43
  ## 非实现复盘终点与 PR 归档门
44
44
 
@@ -16,7 +16,7 @@
16
16
 
17
17
  小请求使用 README 中等价范围、AC 与验证;用户明确要求 Spec/Ticket/Goal 时交付指定工件。复杂需求可经 W → G → S → T → P → I 逐步形成合同,不要求全部 Work 串行必跑。Ticket frontmatter 拥有本票状态、依赖、写集与 Skill binding;有票的 Map/Goal 只管导航、依赖、Gate、集成和恢复,无票 Goal 由计划清单负责进度。整体结论只在 README,归档事实只在目录位置与回执。
18
18
 
19
- 真实使用的 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 等实际工具配置仅对应分支读取;未知配置保留,缺标签只阻塞有关远程写入。
19
+ 真实使用的 Spec/Ticket/Map/Goal、DESIGN、调查、远程账本 schema 与验证继续有效。票据调度、Agent 编排与 change 工作区按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 独立确定:默认 auto 和复用 current;并发票数不等于实现者人数。已有 config 的明确限制按原义执行,不为默认值创建配置。GitHub labels 等只在对应分支读取,未知配置保留。
20
20
 
21
21
  UI 候选缺省 3 个,配置范围 2–4;用户明确数量覆盖默认及上限。W 每会话最多完成一张调查票。专业分支保留:R performance 先测量,D evidence-triage 不以观察冒充根因,I documentation 在原授权范围维护当前工程事实。
22
22
 
@@ -32,4 +32,4 @@ UI 候选缺省 3 个,配置范围 2–4;用户明确数量覆盖默认及
32
32
 
33
33
  按当前分支运行 <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> 的适用 stage;传明确项目/方法/数据根,不用 CLI 包装器作为普通 Work 前置。prototype 传具体 UI-NNN/LOGIC-NNN;完成/取消按 <Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path> 核验真实证据,票全 done 不替代整体验收。归档后以实际目标运行 archived 验证。
34
34
 
35
- 场景出口见 <Path>{roots.workflows}/specdev/common/rules/workflow-routing.md</Path>。T 的 capture、publish、PR 和独立 TRI 各有原账本 owner;未请求远程动作不创建空账本或新完成门。completed/cancelled 不自动授权外部动作,已承诺而未结束的外部交付仍阻塞封存。已完成/归档来源的复盘另建 review-only change,不改写历史。
35
+ 场景出口见 <Path>{roots.workflows}/specdev/common/rules/workflow-routing.md</Path>。T 的 capture、publish、PR 和独立 TRI 各有原账本 owner;未请求远程动作不创建空账本或新完成门。completed/cancelled 不自动授权外部动作,已承诺而未结束的外部交付仍阻塞封存。开发复盘独立保存在 <Path>{roots.state}/specdev/retro/{retro}/RETRO.md</Path>(retro 为日期主题 ID),不创建/重开来源 change;升级与归档按 R 的独立工件合同。
@@ -1,34 +1,21 @@
1
- # 证据与验证规范
1
+ # Evidence 与验证
2
2
 
3
- 验证回答“怎样证明”,Evidence 记录“实际运行了什么、在哪个状态运行、结果和残余风险是什么”。
3
+ I、C、P 验收时读取。环境由 change README 的执行上下文定位,不从票据串并行或 Agent 数量推导。
4
4
 
5
- ## 1. 验证矩阵
5
+ | 检查 | 执行位置 | owner | 证据 |
6
+ |---|---|---|---|
7
+ | 单元、组件、类型、lint/build、正常/失败路径 | change-workspace | 实际实现者 | 原 Ticket/Direct Spec Evidence |
8
+ | 独立双轴审查 | 选定工作区的固定 commit 或工作副本快照 | 未参与本范围实现的 reviewer | 原 Independent Review 与工具核验 |
9
+ | 集成/回归及适用 E2E | change-workspace 的稳定交付输入 | Lead | 命令、退出码、观察、E2E disposition |
10
+ | 整体 AC/Gate | 同一 change 工作区;跨 change 按明确 aggregate 合同 | Lead | 原整体 Evidence |
6
11
 
7
- 每行绑定行为、合同或风险,并标记环境:
12
+ 有提交授权可用实际 commit 固定输入;没有授权时使用 <Path>{roots.workflows}/specdev/common/skills/code-review/references/working-tree-review.md</Path>。快照必须包含本票真实实现范围,保留其他票及用户改动的排除理由。单票通过不代表整个工作区全部通过;最终审查覆盖全部实际交付。
8
13
 
9
- | 行为或风险 | 接缝 | 命令/方法 | 环境 | 预期 | Evidence |
10
- |---|---|---|---|---|---|
11
- | 正常/失败路径 | 公共接口或稳定接缝 | 定向测试 | current-workspace 或 source-worktree | 合同成立 | Ticket Evidence |
12
- | 跨模块回归 | 集成接缝 | 回归命令 | current-workspace 或 parent-candidate | 组合状态成立 | Ticket Evidence |
13
- | E2E required | 真实端到端边界 | 场景步骤 | current-workspace 或 parent-candidate | 外部行为成立 | Ticket Evidence |
14
+ 共享工作区验收前协调相关 writer 停写,测试资源/生成输出独占或明确隔离。Git index 操作串行;当前交付与固定输入、规范或标准不一致时重验受影响项。必需 E2E 未运行/失败不能写 passed,not-required 必须给理由。E2E Gate 仍由 Lead 拥有,不接受执行者自报代替。
14
15
 
15
- ## 2. 两层验证
16
+ Ticket 的 verified 执行记录和 done 状态基于真实改动、AC、检查与独立审查;不要求每票提交、父分支推进或 candidate worktree。Direct Spec 同样逐 AC 验收,不制造票据。明确承诺的 Git/发布交付按原授权单列,失败不伪造成功。
16
17
 
17
- ### Current workspace
18
-
19
- current 模式的 implementation owner 在当前父分支和当前 workspace 工作。Ticket 必须严格串行,workspace clean 后形成非空 implementation commit;Lead 在同一 workspace 执行适用集成/回归和 E2E,并在父 HEAD 未漂移时将 Ticket commit 记录为 result SHA。
20
-
21
- ### Source-worktree
22
-
23
- implementation owner 运行最接近目标行为的单元/组件测试、静态分析、类型、lint/build 等适用非 E2E 检查。来源实现必须在 clean worktree 形成 commit。任何 source-worktree E2E pass 声明无效。
24
-
25
- ### Parent-candidate
26
-
27
- required 模式下,Lead 在最新父分支与 source commit 的 candidate 状态运行受影响集成/回归、项目父状态检查和适用 E2E。E2E 由实际跨边界风险决定,不限于 UI;not-required 必须写理由。required E2E 未运行或失败时不得推进父分支。
28
-
29
- ### Direct Spec
30
-
31
- 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 或未发生的集成。
18
+ 重复失败按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 保留历史并复盘。恢复读原 Evidence、Git 和工具事实,不从 REPORT completed 或进程退出推断验收通过。
32
19
 
33
20
  低层证据不能替代明确要求的外部行为证据。高风险迁移还需要 dry-run、调用点扫描、数据核对、监控或恢复演练。
34
21
 
@@ -38,21 +25,17 @@ Direct Spec 按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md
38
25
 
39
26
  ## 4. 失败分类与完整性
40
27
 
41
- 失败分类为本 Ticket 新失败、基线既有失败、环境/权限/基础设施失败、无效验证或 candidate stale。不得通过跳过、放宽断言、吞错、删除用例或迁移验证位置制造绿色。
28
+ 失败分类为本 Ticket 新失败、基线既有失败、环境/权限/基础设施失败、无效验证或 固定输入漂移。不得通过跳过、放宽断言、吞错、删除用例或迁移验证位置制造绿色。
42
29
 
43
30
  受控反向验证只用于可能静默通过的关键门禁:证明检查能在目标风险出现时失败,再恢复并重跑。普通测试不为形式执行破坏性操作。
44
31
 
45
- ## 5. Evidence 最低内容
46
-
47
- 每个 Ticket Evidence 至少包含:Lead、Dispatch/返回(若有)、workspace 策略、base/source/result SHA、candidate 字段(required 模式适用,current 模式明确不适用)、实际路径、每条命令/环境/退出状态、合同映射、双轴审查、E2E disposition、未运行项、失败分类、偏差、残余风险和父分支重读结果。
48
-
49
- required Ticket Done 必须有 source commit、通过 candidate、父分支 result 与 Lead Evidence;current Ticket Done 必须有 implementation commit、通过 direct-parent 验证、父分支 result 与 Lead Evidence。无法运行 required 验证、存在未批准偏差、父分支未包含 Ticket commit 或 Evidence 不完整时不得 Done。
32
+ ## Evidence 最低内容
50
33
 
51
- Direct Spec Evidence 至少包含:用户实际授权与唯一获批规格、执行方式/workspace 选择、Lead、实施前/最终 checkpoint、实际路径、定向/回归/E2E 命令及环境、验收映射、未运行项、偏差、残余风险和提交授权状态;required 还包括原 Workspace Execution Record、候选集成与父分支回读。
34
+ 记录 Lead、实际派遣/返回、唯一 change 工作区引用、基线与实际 checkpoint/快照、真实修改路径、逐命令环境/退出结果、AC 映射、独立双轴审查、E2E disposition、未运行项、失败分类、偏差和残余风险。Direct Spec 同时保留实际授权和唯一获批规格,不制造 Ticket。
52
35
 
53
- 父实现 change 的 Implementation Orchestration Evidence 不能替代子 Evidence。它至少记录最终 Map revision、全部成员最终状态和子证据指针、dependency/serialization 实际顺序、跨 change 合同检查、aggregate 命令/环境/结果、stale candidate 处理、偏差和残余风险。任何成员未 completed 或整体验证未通过时不得形成父完成证据。
36
+ 父 Implementation Orchestration Evidence 不能替代子 Evidence;至少记录最终 Map revision、成员状态/证据引用、dependency/serialization 实际顺序、跨 change 合同检查、aggregate 命令/环境/结果、漂移处置与残余风险。成员未 completed 或整体验证未通过不能完成父 change。
54
37
 
55
- Evidence 原文不出仓库。对 GitHub 的公共投影由 T-triage publish 按公共投影规则生成,不替代本文件的完整记录。
38
+ Evidence 原文不出仓库。对 GitHub 的公共投影由 T-triage publish 按公共投影规则生成,不替代完整记录。
56
39
 
57
40
  ## 6. 按改动选择检查与复用证据
58
41
 
@@ -1,28 +1,36 @@
1
- # 执行方式与工作区
1
+ # 票据调度、Agent 编排与 change 工作区
2
2
 
3
- I 开始实现、P 安排执行和 dev-worktree 创建/恢复时读取。规格、执行方式、工作区独立选择;共同的工具选择与交接协议见 <Path>{roots.references}/coordination/coordination-contract.md</Path>。
3
+ I 开始实现、P 安排执行和 dev-worktree 创建/恢复时读取。三项决定分别记录,互不推导。工具选择和任务交接读取 <Path>{roots.references}/coordination/coordination-contract.md</Path>。
4
4
 
5
5
  ## 输入和选择
6
6
 
7
- - 获批完整 Spec 可直接进入 I;`ready_for_tickets: true` 继续表示规格已就绪,不要求真的拆票。多个行为、公共接口、迁移或高风险不单独构成强制拆票理由,相应设计、批准、验证和恢复门必须完整。
8
- - README 替代独立 Spec 仍限原轻量边界。用户要求独立 Spec/Ticket/Goal 时按要求交付;缺产品决定不能用执行策略补造。
9
- - 独立调度、依赖 DAG 或逐票追踪确有需要才使用 T;跨任务 Gate、跨 change 或用户要求总控时使用 P。已有 Ticket/父实现不能通过转称 Direct Spec 绕过未完成责任;先由原 owner 处置活动执行和证据,再改路由。
10
- - 没有明确执行方式时,按当前宿主正常执行,App、CLI 等均可;工作区默认 `current`。明确指定 CLI 交互、Herdr 等方式时按选择执行;复用已有明确选择,不逐层重问。只读 C 冻结原候选,不创建实现工作区。
11
- - 已有父 Implementation Plan 的 workspace/Gate/上限优先约束子任务;子 Goal 不得放宽。无父计划使用已有 Goal;无 Goal 时由当前 I owner 在原 Evidence 的执行上下文记录方式、workspace 策略、Lead、路径、验证、原授权来源和恢复依据,不创建 Goal。
12
- - 无 Goal 的实现单元默认串行,集成尝试上限为 3;有明确项目约定时记录其来源并复用更严格上限。有效计划、实际存在的执行限制和平台能力取共同上限。不为这些默认值创建 config。
7
+ - 获批完整 Spec 可直接进入 I;`ready_for_tickets: true` 表示规格就绪,不强制拆票。README 替代独立 Spec 仍限原轻量边界;明确要求的 Spec/Ticket/Goal 必须交付。
8
+ - 需要独立调度、DAG 或逐票追踪时使用 T;跨任务 Gate、跨 change 或明确总控请求进入 P。已有活动责任不能通过改称 Direct Spec 绕过,先由原 owner 处置原记录。
9
+ - 票据调度 `ticket_execution: auto | serial | parallel`:默认 auto,由 Agent 按 DAG、写集、语义资源、用户/项目要求和实际能力决定。serial 完成当前票的实现、独立审查和验证后再开始下一票;parallel 允许同时推进独立票,但不强制派遣或绕过前置门。
10
+ - `max_parallel_tickets` 仅在实际要求上限时记录,计量 in_progress/review 票据,不计 Agent。父计划、子计划及 change 约束取共同上限,serial 为一票。没有显式上限时不填固定数字,不创建 config。
11
+ - Agent 编排按用户、项目初始化选择和当前 Work/Skill 的要求决定。一张票可以由 Lead、subagent 或团队完成。`concurrent_implementation_limit` 和现有 config 的 `max_concurrent_implementations` 仅约束实际实现者人数,显式存在才生效;不能用票据数量代替人数或反向推导。宿主限制仍须遵守。Lead 从真实工具状态核对活动人数,历史 implementation_owners 名单不代表当前全部在写,静态校验不能认证运行期人数。
12
+ - 未指定工作区时复用 current,不询问默认选择。用户已选的 workspace/branch 持续有效。父计划引用成员选择,不重新安排其工作区。
13
13
 
14
- ## 工作区
14
+ ## 工作区与写入
15
15
 
16
- `current` 在当前工作副本执行;同一时刻只有一个代码 writer,包括 Lead、原生 subagent/team 和 Herdr 执行者。派出实现任务后 Lead 等待写入结束再接收,测试、审查不读正在漂移的候选。只读任务可以并行。Ticket 继续 direct-parent 验收;Direct Spec 保留实施前/最终 checkpoint、dirty 状态与提交授权,未授权不提交,不伪造已集成。
16
+ 一个 change 使用一个选定工作区,所有 Ticket、Direct Spec、协作者、修复和验证都在这里完成。`workspace_policy: current` 可为 main、普通分支或已在使用的 worktree;`worktree` 表示本 change 明确选择的独立 checkout。需要新建时调用 <Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>,默认 locator 为 `specdev-worktree/<change>`,branch 为 `speculo/<change>`。按实际用户选择复用已有工作区。
17
17
 
18
- `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 不构成沙箱或执行锁。
18
+ 串并行、Agent 数量、重试、review 均不新增工作区。额外 worktree 或扩大分支范围必须另有具体授权,不从创建一个 change worktree 的要求继承。
19
19
 
20
- ## 记录与恢复
20
+ 同一工作区可由多个实现者写互不冲突的授权路径。共享路径、API、迁移序列、端口、数据库、生成输出须明确唯一 owner 或串行阶段;worktree 不提供锁或沙箱。Git index、commit、checkout、merge 和改变公共依赖的操作由 Lead 协调串行,任何执行者都不能暂存他人改动。审查和整体测试使用固定输入,冻结前协调相关 writer 停止写入;未知运行状态先查询,不以无报告/超时推断结束。
21
21
 
22
- 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 字段沿用现有合同。不允许两种执行记录并存。
22
+ ## 唯一记录与完成
23
23
 
24
- 新建 Direct Spec required 必须记录真实执行对象;current 可以保留原 checkpoint 证据而不制造集成记录,历史无记录 current Evidence 仍可读取。使用结构化 current 记录时必须满足同一 commit/direct-parent 完成门。无论模式,完整 Spec 的完成需要逐 AC 的 Acceptance Verification 与实际双轴审查;未完成或未验证不能标 completed。
24
+ 实际执行开始时,Lead 在 change README 的 `Execution Context` 锚点保存一次工作区事实、基线、owner 和无计划时的调度选择。完整计划拥有票据策略,README 只保留该 change 的实际上下文;工作区只有 README 一个事实源。格式和恢复检查见 <Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/create.md</Path>,current 同样使用该记录而不调用创建操作。纯只读不造执行记录;既有无票 current 证据可按原快照合同读取。
25
25
 
26
- 恢复先核对原 Evidence、实际 writer、Git、候选和权限;未知结果先查询,失败候选不推进父分支。重复同一 blocker 无新证据或达到尝试上限时暂停,Lead 记录下一轮实质变化后才能重试。取消、归档不能抹掉活动 worktree 或未决 candidate。
26
+ 每票原 Evidence 保存自己的 `Workspace Execution Record`,引用 `<Path>{roots.state}/specdev/changes/{change}/README.md</Path>` 的 execution-context 锚点,只记录实际实现者、checkpoint、验证与失败次数;Direct Spec 使用原 evidence/direct-spec.md,不造 Ticket/Map/Goal。使用 <Path>{roots.workflows}/specdev/specdev-i-implement/assets/evidence-template.md</Path>。Lead 是正式状态/Evidence owner,implementation_owners 可有多人。
27
27
 
28
- Direct Spec 整体取消时,原 owner 先按 change-completion 记录真实取消决定、已停止 writer、依赖及 checkpoint/candidate 的保留或交接;这些条件满足后才把本单元记录 status 改为 cancelled。此状态仅适用于 Direct Spec,不表示集成通过或授予清理权限;不能用于 completed。Ticket 状态格式不变。
28
+ 完成以真实改动、AC、独立双轴审查和适用验证为准。未授权提交时使用固定工作副本快照;不要求 empty commit、每票 commit、父分支 result 或额外 candidate checkout。明确承诺的提交、合并、发布等仍按原目标与授权执行;完成声明不得冒充这些动作已发生。整体完成仍按 <Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>。
29
+
30
+ 验证尝试上限来自有效计划、change 上下文或项目约定,缺省 3,已有 config 的更严格上限继续生效。重复同一 blocker 无新证据或达到上限时,Lead 保留历史并形成实质变化后才能重试;仅换 Agent 不构成恢复。
31
+
32
+ ## 恢复和旧记录
33
+
34
+ 恢复重读 README、原计划、Ticket/Evidence、实际 writer、Git branch/base 和工作区;冲突只暂停受影响分支。取消和归档不删除工作区或未决事实,writer 停止仍需真实证据。
35
+
36
+ 旧 per-Ticket/source/candidate 执行记录仅作历史只读依据。活动旧记录必须由原 owner 显式整理:停止或交接旧 writer,盘点全部 branch/worktree/checkpoint/未决动作,确认本 change 的唯一工作区;没有合并授权不能收拢代码。将旧记录原字节移存原 Evidence 的历史段并保留引用,经核对后才写新上下文和新记录,重新核验失效的审查/验证。不自动删除旧工作区、不批量改 done,不由安装刷新转换。未处置完毕保持 blocked。
@@ -16,7 +16,7 @@
16
16
  11. **本地执行权威**:远程 Issue/PR/URL 只作为来源或完成投影;Spec、Ticket、Map、Goal Plan、Evidence 和状态始终以本地工件为准。
17
17
  12. **完成与归档分离**:本地完成按 change completion 合同决定;远程 close 失败不回滚完成,但必须 reconcile 或 waive 后才归档。
18
18
  13. **Lead 与隔离正交**:Lead 固定拥有原计划、Evidence 与父分支;是否派遣 任务执行者 由 Lead 动态决定。执行方式与工作区按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 独立选择,执行方式默认当前宿主正常执行,工作区默认 current;无 Goal 时由 I 在原 Evidence 承接,已有选择不重复询问。
19
- 14. **策略化验收**:current 模式使用当前 workspace 严格串行、direct-parent 验证;required 模式使用 source worktree 与 parent-candidate。只有 required 模式创建独立实现 worktree,单元可以是 Ticket 或整个 Direct Spec change。
19
+ 14. **策略化验收**:按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 在选定 change 工作区冻结真实输入、完成独立审查和验证。票据串并行不决定工作区或 Agent 拓扑,不强制每票提交/合并。
20
20
  15. **父子权威隔离**:父实现 change 只拥有 Ready 子 change 的组合 Ticket DAG、serialization、全局 workspace/资源和实现进度投影;子 change 继续拥有全部行为与实现合同。一个未完成子 change 只能属于一个未完成父实现 change。
21
21
 
22
22
  共享规则:
@@ -9,7 +9,7 @@
9
9
  ## 权威边界
10
10
 
11
11
  - 父 Implementation Map:成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision 的唯一权威投影。
12
- - 父 Implementation Plan:Lead、全局 workspace 策略、implementation agent/integration attempt 上限、frontier、Wave、locks 和 integration queue 的唯一权威。
12
+ - 父 Implementation Plan:Lead、跨 change ticket_execution、可选票据上限、明确实现者限制、Gate/Wave、serialization 和已授权 Git 交付队列;工作区只引用成员上下文。
13
13
  - 子 change:自己的 Spec、Ticket、内部 Goal Gate、workspace、Git、Evidence 和完成状态的唯一权威。
14
14
 
15
15
  父工件不得复制完整子合同。子权威变化时停止旧派单、递增父 Map revision 并重算父 Plan;不能从旧父投影覆盖子工件。
@@ -20,12 +20,14 @@
20
20
 
21
21
  ## I-implement 调用
22
22
 
23
- 父 Plan 可以替代缺失的子 Goal Plan 提供 workspace/integration 策略和全局执行边界。子 Goal Plan 存在时继续拥有子 change 内 Gate,但不得与父策略冲突。I-implement 完成或阻塞一个组合 Ticket 后返回父 P Goal,不要求用户重新激活 change。
23
+ 父 Plan 可替代缺失的子 Goal 提供跨 change 调度/Gate 和执行边界;子计划的约束同时遵守。成员实际工作区由各自 README 唯一记录,父计划不得覆盖已有选择;完成或阻塞组合票后返回父 P。
24
24
 
25
25
  ## 归档与完成
26
26
 
27
27
  未完成父实现 change 的成员不得归档。成员满足普通 change completion 时可以先 completed,但不自动归档。父 change 只有全部成员 completed、Map/Plan completed、aggregate Evidence 完整且无 active dispatch/candidate/lock 后才能 completed;完成或归档均不自动级联。
28
28
 
29
+ 父完成门逐一重验成员选定工作区的实际交付和最终固定审查输入,不要求先合并成员分支。父聚合双轴审查同时绑定当前 Map、Plan、成员 Spec 与各成员最终 Evidence 的 review-input 锚点;可对这些编排工件使用 source-files 固定快照,但不能替代成员的实现变更审查。成员代码、规格或审查输入变化后,重新核验受影响成员与聚合证据;Git 交付仍只执行具体已授权动作。
30
+
29
31
  ## 局部阻塞不升级为全局停机
30
32
 
31
33
  父创建前仍全部成员预检且 all-or-nothing。父开始运行后,单票 blocked/deviated、他人资源冲突或必需 Skill 失效只阻塞该票及其依赖闭包,父 Map/Plan 可保持 in_progress 与有效的全局执行门,继续独立已授权 frontier。只有共享的全局门禁失败、计划整体失效或没有合法 frontier 时,才将父运行暂停;不得为继续运行接管其他任务。
@@ -20,16 +20,18 @@
20
20
  5. 越界前停止并按 deviation control 提出 ownership change;不得先改后报。
21
21
  6. 上游 Ticket 改变目录/合同后,下游基于已集成父分支重新解析路径和 preflight。
22
22
 
23
- ## 3. Ticket workspace strategy
23
+ ## 3. change 工作区与协作
24
24
 
25
- 按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 选择工作区,与当前宿主执行、显式 CLI 交互或 Herdr 等方式正交。默认 current,已有选择直接复用;无 Goal 时 I 在原 Evidence 负责选择与记录。current 严格单代码 writer,前一 Ticket 完成 commit、Lead 验收和 direct-parent 验证后才进入下一票。required 的 Ticket locator 为 `specdev-worktree/<change>/<ticket-id>`,Direct Spec 为 `specdev-worktree/<change>/direct-spec`,两者都走 candidate 集成;只读调查/审查不创建实现 worktree。
25
+ 按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 独立确定票据调度、Agent 编排与工作区。每个 change 的工作区事实只在 README 执行上下文保存,所有票据和执行者复用;不以同一工作区推导单 writer,也不以并行推导独立 worktree。
26
26
 
27
- workspace/implementation owner 可以是 Lead 或动态 实现执行者;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 规则管理。
27
+ Ticket owner 负责本票交付,可以安排多个执行者并细分授权写集;Lead 参与实现也遵守相同路径边界。SpecDev 状态、Evidence 和最终验收仍由 Lead 写入。只读任务可以并行,不占票据并发数;当前 Work 的独立 reviewer 要求仍生效。
28
28
 
29
- ## 4. 并发
29
+ ## 4. 并发与验收时序
30
30
 
31
- required 模式 实现执行者 上限取实际存在的 Goal/父计划、项目约定和平台能力共同约束,无计划默认串行,Lead 参与实现时计入。current 模式保持单 writer 串行安全不变量,Ticket 严格串行。review/research/test-observation agent 不设置 SpecDev 数字上限,但 Lead 必须避免重复工作与可变环境争用。
31
+ 并行候选必须满足依赖、可写路径、shared owner、语义资源和明确并发限制。冲突操作由 owner 排序,不创建额外 worktree 规避共享语义冲突。单票 serial 不限制该票内部 Agent 合作;同一票多个 Agent 的写集仍不得相撞。
32
32
 
33
- 子 change 属于父 Implementation Map 时,再取父 Implementation Plan 的全局 实现执行者 上限与 workspace 策略;该上限跨全部成员合计。无 dependency 的组合 Ready Tickets 若 writable/shared paths 重叠,也必须在父 Map 建立 serialization。相同 repository/ref 的 parent integration 严格串行;一次父 HEAD 推进会使其他成员旧 candidate 失效。
33
+ Git index/提交/切换分支/合并串行协调;不得提交其他票或用户改动。固定审查输入与整体测试前停止相关 writer,记录真实 checkpoint 或工作副本快照,回读发现漂移后使受影响证据失效。Lead 的 E2E Gate 在选定 change 工作区执行。
34
34
 
35
- **完成标准**:每个项目写入映射到唯一 change、已有 Ticket 或 Direct Spec、owner 和来源 worktree;shared 与父分支写入 owner 唯一。
35
+ 父实现存在时,按组合 ID 协调跨 change 依赖和 serialization;保留每个成员工作区,父票据上限计量 Ticket,已有实现者限制单独执行。跨分支交付若要求合并,按具体授权和 Git 事实串行执行,不由单票 Done 自动触发。
36
+
37
+ **完成标准**:每个写集有唯一票据/实现者归属,所有票据可追溯至该 change 的唯一工作区,审查与验证覆盖真实交付。
@@ -27,7 +27,7 @@
27
27
 
28
28
  ## 复盘与交付路由
29
29
 
30
- 开发环境/流程复盘 → <Path>{roots.workflows}/specdev/specdev-r-retro/SKILL.md</Path>。代码与参考资料学习 → <Path>{roots.workflows}/specdev/specdev-l-learn/SKILL.md</Path>;可在实现前直接进入,用户未指定 change 时由 L 新建学习载体。Speculo 产品反馈仍为 retro command。CI/安全/PR/包发布 → <Path>{roots.workflows}/specdev/specdev-t-triage/SKILL.md</Path> 的对应模式;确定性修复回到 D/I,不由 T 接管代码。
30
+ 开发环境/流程复盘、积累独立 RETRO,以及明确要求汇总升级项目 Skills → <Path>{roots.workflows}/specdev/specdev-r-retro/SKILL.md</Path>。代码与参考资料学习 → <Path>{roots.workflows}/specdev/specdev-l-learn/SKILL.md</Path>;可在实现前直接进入,用户未指定 change 时由 L 新建学习载体。Speculo 产品反馈仍为 retro command。CI/安全/PR/包发布 → <Path>{roots.workflows}/specdev/specdev-t-triage/SKILL.md</Path> 的对应模式;确定性修复回到 D/I,不由 T 接管代码。
31
31
 
32
32
  长任务在阶段边界按产物与待决问题选择继续、压缩上下文或 handoff;交接只携带准确 owner、SHA、输入和未闭合动作,不硬编码特定模型的上下文阈值,不自动启动其他会话。
33
33
 
@@ -16,6 +16,10 @@ change 的稳定身份是同一项目、领域内的 `YYYY-MM-DD-topic[-NN]` 目
16
16
 
17
17
  实际外部派遣的输入、报告和按需历史快照按 <Path>{roots.references}/coordination/session-files.md</Path> 保存在 <Path>{roots.state}/specdev/changes/{change}/sessions/</Path>,随 change 整体归档并进入原完整性清单;归档前仍核对 writer 已停止,不因 REPORT 显示 completed 就移动活动工作区。session 只是交接材料分组,不成为整体 Outcome 或执行状态的第二权威。引用按稳定 change 与对象内 locator 解析,历史原件不回填或清理。
18
18
 
19
+ ## 独立开发复盘
20
+
21
+ RETRO 与升级方案使用 <Path>{roots.state}/specdev/retro/</Path>,与 changes、adr、context 平级;具体日期对象、原文来源、确认和执行回执归 <Path>{roots.workflows}/specdev/specdev-r-retro/references/records.md</Path>。R 不创建复盘专用 change,A 通过 RETRO 窄网关移至该目录的 archive。报告不成为 change 的完成依据或永久知识,不预造目录、不维护全局状态镜像。
22
+
19
23
  ## 唯一整体结论
20
24
 
21
25
  每个新 change README 正文恰有一行:
@@ -32,9 +36,9 @@ Outcome: active
32
36
 
33
37
  不默认创建 leadership epoch、空批准槽或每 Work 记录。实际交接、并行、worktree/集成发生时,在原计划、Ticket Evidence 或操作回执记录唯一负责者、获批写集、输入、真实交接与下一步。复杂任务 owner 从原 implementation-plan/goal-plan 的 `lead` 读取。无 Goal 且动作确需 owner 时,README 的 `## Ownership` 内保存 `Owner: <session locator>` 与 `Evidence: <对象内相对路径>[#anchor]`,证据指向实际会话/交接;设计 bootstrap 还保存 `Work: specdev/prototype` 且依据正文绑定该 Work。普通只读不预建所有权记录,字段不创造授权。
34
38
 
35
- 每个实现 Ticket 的 Evidence 在 `## Workspace Execution Record` 下以唯一 JSON object 保留实际执行记录(原 worktree 字段),不创建全局 array 镜像;其中保留 base SHA、父分支、workspace/implementation/integration owner、workspace locator、implementation/source checkpoint、candidate/result SHA、验证与 E2E disposition。current 使用 current/direct-parent;required 使用 source/parent-candidate,清理后也保留集成证据。父计划只导航,不另复制一套结果。
39
+ change README 的 Execution Context 是工作区、branch、base 与 Lead 的唯一事实源;实际执行才创建。每票原 Evidence 的 Workspace Execution Record 引用该上下文,保存实际实现者、固定输入、验证与失败历史;无票沿原 Direct Spec Evidence。格式和兼容边界见 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path>。父计划只导航,不复制 workspace 结果。
36
40
 
37
- 语言、用户工具和数量来自当前请求/既有项目说明;实际并发、worktree 与尝试上限由原 Goal/项目约定负责,原 Goal/Implementation Plan 的 `## Execution Policy Source` 说明实际策略来源;已有 config 仍校验相应上限,Lead 自己实现计入并发。旧 config 的真实远程/验证用途可选保留;未知独有字段不能以简化为由丢弃。默认 UI 3 个、配置 2–4、明确用户数量覆盖,均不变。
41
+ 语言、用户工具和数量来自当前请求/既有项目说明。原 Goal/Implementation Plan 的 Execution Policy Source 说明调度来源;票据并发上限与已配置实现者人数限制分别检查。未知 config 独有字段保留;默认 UI 3 个、配置 2–4、明确用户数量覆盖,均不变。
38
42
 
39
43
  ## 创建、恢复和历史边界
40
44
 
@@ -0,0 +1,67 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:speculo:specdev:execution-context:v1",
4
+ "title": "SpecDev change Execution Context",
5
+ "type": "object",
6
+ "required": [
7
+ "schema_version",
8
+ "change",
9
+ "workspace_policy",
10
+ "workspace_ref",
11
+ "branch",
12
+ "base_sha",
13
+ "owner",
14
+ "ticket_execution"
15
+ ],
16
+ "properties": {
17
+ "schema_version": {
18
+ "const": 1
19
+ },
20
+ "change": {
21
+ "type": "string",
22
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
23
+ },
24
+ "workspace_policy": {
25
+ "enum": [
26
+ "current",
27
+ "worktree"
28
+ ]
29
+ },
30
+ "workspace_ref": {
31
+ "type": "string",
32
+ "minLength": 1
33
+ },
34
+ "branch": {
35
+ "type": "string",
36
+ "minLength": 1
37
+ },
38
+ "base_sha": {
39
+ "type": "string",
40
+ "pattern": "^[a-f0-9]{40}(?:[a-f0-9]{24})?$"
41
+ },
42
+ "owner": {
43
+ "type": "string",
44
+ "minLength": 1
45
+ },
46
+ "ticket_execution": {
47
+ "enum": [
48
+ "auto",
49
+ "serial",
50
+ "parallel"
51
+ ]
52
+ },
53
+ "max_parallel_tickets": {
54
+ "type": "integer",
55
+ "minimum": 1
56
+ },
57
+ "concurrent_implementation_limit": {
58
+ "type": "integer",
59
+ "minimum": 1
60
+ },
61
+ "integration_attempt_limit": {
62
+ "type": "integer",
63
+ "minimum": 1
64
+ }
65
+ },
66
+ "additionalProperties": false
67
+ }