@namewta/speculo 2.0.4 → 2.0.6

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 (89) hide show
  1. package/package.json +1 -1
  2. package/template/canonical/canonical-specdev-goal-plan.md +2272 -1069
  3. package/template/canonical/canonical-specdev-grill-with-docs.md +2164 -661
  4. package/template/canonical/canonical-specdev-spec.md +2163 -660
  5. package/template/canonical/canonical-specdev-tickets.md +2095 -574
  6. package/template/canonical/canonical-specdev-wayfinder.md +2339 -836
  7. package/template/references/coordination/coordination-contract.md +8 -6
  8. package/template/references/coordination/modes/cli.md +1 -1
  9. package/template/references/coordination/modes/herdr.md +2 -2
  10. package/template/references/coordination/modes/orca.md +3 -3
  11. package/template/references/coordination/report-template.md +18 -0
  12. package/template/references/coordination/result-and-recovery.md +4 -4
  13. package/template/references/coordination/session-files.md +49 -56
  14. package/template/references/coordination/task-brief.md +7 -7
  15. package/template/references/coordination/task-template.md +25 -0
  16. package/template/references/retrospective/references/friction-taxonomy.md +1 -1
  17. package/template/references/writing-for-agents/references/project-skill-maintenance.md +29 -0
  18. package/template/references/writing-for-agents/writing-contract.md +2 -0
  19. package/template/workflows/specdev/SKILL.md +1 -1
  20. package/template/workflows/specdev/common/README.md +1 -1
  21. package/template/workflows/specdev/common/rules/artifact-contract.md +1 -1
  22. package/template/workflows/specdev/common/rules/change-completion.md +6 -6
  23. package/template/workflows/specdev/common/rules/domain-runtime.md +2 -2
  24. package/template/workflows/specdev/common/rules/evidence-and-verification.md +17 -34
  25. package/template/workflows/specdev/common/rules/execution-policy.md +24 -16
  26. package/template/workflows/specdev/common/rules/operating-governance.md +1 -1
  27. package/template/workflows/specdev/common/rules/parent-implementation-orchestration.md +4 -2
  28. package/template/workflows/specdev/common/rules/path-ownership.md +9 -7
  29. package/template/workflows/specdev/common/rules/path-reference-contract.md +1 -1
  30. package/template/workflows/specdev/common/rules/workflow-routing.md +1 -1
  31. package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md +7 -3
  32. package/template/workflows/specdev/common/schemas/execution-context.schema.json +67 -0
  33. package/template/workflows/specdev/common/schemas/execution-record.schema.json +154 -0
  34. package/template/workflows/specdev/common/schemas/goal-plan.schema.json +15 -55
  35. package/template/workflows/specdev/common/schemas/implementation-plan.schema.json +15 -55
  36. package/template/workflows/specdev/common/schemas/retro-approval.schema.json +44 -0
  37. package/template/workflows/specdev/common/schemas/retro-archive.schema.json +99 -0
  38. package/template/workflows/specdev/common/schemas/retro-execution.schema.json +112 -0
  39. package/template/workflows/specdev/common/schemas/retro-upgrade.schema.json +163 -0
  40. package/template/workflows/specdev/common/schemas/retrospective.schema.json +119 -14
  41. package/template/workflows/specdev/common/schemas/session-locator.schema.json +15 -0
  42. package/template/workflows/specdev/common/skills/code-review/references/review-evidence.md +3 -3
  43. package/template/workflows/specdev/common/skills/code-review/references/source-discovery.md +2 -0
  44. package/template/workflows/specdev/common/skills/code-review/references/working-tree-review.md +1 -1
  45. package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md +15 -34
  46. package/template/workflows/specdev/common/skills/dev-worktree/references/create.md +27 -56
  47. package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md +10 -54
  48. package/template/workflows/specdev/common/tools/README.md +16 -0
  49. package/template/workflows/specdev/common/tools/delivery-artifacts.mjs +5 -5
  50. package/template/workflows/specdev/common/tools/execution-context.mjs +104 -0
  51. package/template/workflows/specdev/common/tools/plan-contract.mjs +3 -1
  52. package/template/workflows/specdev/common/tools/review-evidence.mjs +2 -2
  53. package/template/workflows/specdev/common/tools/tests/engineering.test.mjs +2 -2
  54. package/template/workflows/specdev/common/tools/tests/review-fixture.mjs +4 -4
  55. package/template/workflows/specdev/common/tools/ticket-control.mjs +17 -12
  56. package/template/workflows/specdev/common/tools/validate-handoff.mjs +108 -0
  57. package/template/workflows/specdev/common/tools/validate-retro.mjs +331 -0
  58. package/template/workflows/specdev/common/tools/validate-specdev.mjs +135 -105
  59. package/template/workflows/specdev/specdev-a-archive-and-consolidate/SKILL.md +2 -1
  60. package/template/workflows/specdev/specdev-a-archive-and-consolidate/references/operation-contract.md +2 -0
  61. package/template/workflows/specdev/specdev-a-archive-and-consolidate/references/retro-archive.md +27 -0
  62. package/template/workflows/specdev/specdev-c-code-review/SKILL.md +1 -1
  63. package/template/workflows/specdev/specdev-i-implement/SKILL.md +3 -3
  64. package/template/workflows/specdev/specdev-i-implement/assets/evidence-template.md +39 -31
  65. package/template/workflows/specdev/specdev-i-implement/references/execution-preflight.md +16 -16
  66. package/template/workflows/specdev/specdev-i-implement/references/implementation-procedure.md +21 -37
  67. package/template/workflows/specdev/specdev-i-implement/references/merge-conflict-protocol.md +8 -18
  68. package/template/workflows/specdev/specdev-p-goal-plan/SKILL.md +3 -3
  69. package/template/workflows/specdev/specdev-p-goal-plan/assets/goal-plan-template.md +23 -26
  70. package/template/workflows/specdev/specdev-p-goal-plan/references/completion-control.md +11 -14
  71. package/template/workflows/specdev/specdev-p-goal-plan/references/lead-orchestration.md +12 -33
  72. package/template/workflows/specdev/specdev-p-goal-plan/references/map-control.md +1 -1
  73. package/template/workflows/specdev/specdev-p-goal-plan/references/multi-change-plan.md +11 -16
  74. package/template/workflows/specdev/specdev-p-goal-plan/references/multi-conflict-and-drift.md +2 -2
  75. package/template/workflows/specdev/specdev-p-goal-plan/references/multi-execution-loop.md +6 -6
  76. package/template/workflows/specdev/specdev-p-goal-plan/references/orchestration-protocol.md +13 -44
  77. package/template/workflows/specdev/specdev-p-goal-plan/references/planning-modes.md +18 -25
  78. package/template/workflows/specdev/specdev-p-goal-plan/references/single-change-plan.md +16 -16
  79. package/template/workflows/specdev/specdev-r-retro/SKILL.md +15 -11
  80. package/template/workflows/specdev/specdev-r-retro/assets/retro-template.md +26 -14
  81. package/template/workflows/specdev/specdev-r-retro/assets/upgrade-plan-template.md +41 -0
  82. package/template/workflows/specdev/specdev-r-retro/references/development-retrospective.md +42 -0
  83. package/template/workflows/specdev/specdev-r-retro/references/records.md +47 -0
  84. package/template/workflows/specdev/specdev-r-retro/references/skill-upgrade.md +13 -0
  85. package/template/workflows/specdev/specdev-t-tickets/SKILL.md +2 -0
  86. package/template/workflows/specdev/specdev-t-tickets/assets/ticket-template.md +1 -1
  87. package/template/workflows/specdev/specdev-t-tickets/assets/tickets-map-template.md +6 -6
  88. package/template/workflows/specdev/specdev-t-tickets/references/planning-procedure.md +2 -2
  89. package/template/workflows/specdev/specdev-t-tickets/references/ticket-readiness.md +3 -3
@@ -8,32 +8,29 @@
8
8
  至少要求:
9
9
 
10
10
  - Spec 验收合同全部有通过 Evidence 或明确批准的 deferred;
11
- - current 模式的非 cancelled Ticket 都有 implementation commit、通过的 direct-parent 验证和父分支 result SHA;required 模式都有 source commit、通过的 candidate 和父分支 result SHA;
11
+ - 非 cancelled Ticket 有真实改动、verified 执行记录、独立双轴审查、AC 和适用验证;commit 或工作副本快照都可固定交付;
12
12
  - shared path、接口、数据、兼容、迁移、调用点与回滚合同闭合;
13
13
  - 项目定向检查、受影响回归、类型检查、lint/build 和适用 E2E 无未经批准退化;
14
14
  - README Outcome、Ticket、Map 导航、Goal Plan、Evidence 与实际 Git 状态一致;
15
- - 没有未集成 implementation/source checkpoint、活动 integration candidate 或未决高影响偏差。
15
+ - 无活动 writer、未验证交付或未决高影响偏差;明确承诺的 Git/外部交付按约定完成或获明确处置。
16
16
 
17
17
  无需改动的 Ticket 必须转为 `cancelled` 并记录来源事实;不得用 Evidence-only Done 或 empty commit 关闭。
18
18
 
19
- ## 2. 两层验证
19
+ ## 2. 单票与整体验证
20
20
 
21
- - `current-workspace`:current 模式 implementation owner 运行 Ticket 要求的检查,Lead 在同一 workspace 运行受影响集成/回归和适用 E2E;
22
- - `source-worktree`/`parent-candidate`:required 模式由 implementation owner 和 Lead 分别运行非 E2E 与集成/E2E 检查。
23
-
24
- Evidence 必须记录命令运行环境。required 模式任何在 source worktree 声称的 E2E pass 都无效;任务执行者 返回的测试结果在 Lead 核对前保持候选状态。
21
+ 按 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path> 在选定 change-workspace 验证。实现者运行适用检查,Lead 在固定输入上核验集成/回归和适用 E2E;独立 reviewer 按原合同审查。记录真实命令环境,不以执行者自报代替 Lead 验收。整体输入覆盖全部票据,不只最后一票。
25
22
 
26
23
  ## 3. Gate 关闭
27
24
 
28
- Lead 在每个 Gate 汇总覆盖 Evidence、接口/数据/兼容状态、candidate/result SHA、适用 E2E、反向验证、偏差、风险和批准。Gate 不以“完成若干 Ticket”作为唯一关闭条件。
25
+ Lead 在每个 Gate 汇总覆盖 Evidence、接口/数据/兼容状态、固定 checkpoint/快照、适用 E2E、反向验证、偏差、风险和批准。Gate 不以“完成若干 Ticket”作为唯一关闭条件。
29
26
 
30
27
  ## 4. 失败与恢复
31
28
 
32
- - current/source 检查失败:保留当前 workspace 或 source worktree,继续当前 Ticket;
33
- - direct-parent/candidate 冲突或检查失败:父分支不动,integration 记 `failed`,Ticket 回到 `in_progress`/`blocked`;
34
- - 父 HEAD 漂移:integration 记 `stale`,从最新父分支重建并重跑;
35
- - E2E required 失败:父分支不动,保留失败命令、适用 checkpoint 和恢复条件;
36
- - 同一 blocker 反复出现、下一轮没有新证据,或 integration attempts 达到有效上限:停止自动重复,保留 workspace、checkpoint/candidate 和全部失败事实,将受影响 Ticket 标为 `blocked` 并返回有效 Lead;Lead 按 lead-orchestration 在 Evidence 写复盘决定后,才可重置该 Ticket 的 `attempts` 并以有实质变化的新 Packet 重新派发;
29
+ - 单票检查失败:保留选定 change 工作区与快照,修复受影响票;
30
+ - 工作区共享资源或 Git 冲突:停止冲突写入,由 owner 处置,保留当前事实;
31
+ - 固定输入漂移:使受影响证据失效,重新冻结并验证;不新建工作区;
32
+ - required E2E 失败:不能 verified/done,保留失败命令、快照和恢复条件;
33
+ - 同一 blocker 反复出现、下一轮没有新证据,或 integration attempts 达到有效上限:停止自动重复,保留 workspace、checkpoint 和全部失败事实,将受影响 Ticket 标为 `blocked` 并返回有效 Lead;Lead 按 lead-orchestration 在 Evidence 写复盘决定后,才可重置该 Ticket 的 `attempts` 并以有实质变化的新 Packet 重新派发;
37
34
  - 命中当次 Dispatch Packet/候选协议的停止条件、继续修正已无合理收益或需要新产品决定:停止受影响 Wave,按 deviation control 返回契约 owner;
38
35
  - Lead 会话变化:读取 Goal Plan、Ticket、change worktree 状态与最新 Evidence,从最后不可变 checkpoint 恢复。
39
36
 
@@ -43,7 +40,7 @@ Lead 在每个 Gate 汇总覆盖 Evidence、接口/数据/兼容状态、candida
43
40
 
44
41
  Lead 是 Goal Plan change 的唯一完成 owner。没有 Goal Plan 的单 Ticket/Direct Spec 由当前 I-implement owner 按 change completion 规则完成。Archive 不补造完成证据。
45
42
 
46
- **完成标准**:所有通过、阻塞、取消和未验证声明均定位到权威工件、命令与 Git checkpoint;失败不会推进父分支或 Done。
43
+ **完成标准**:所有通过、阻塞、取消和未验证声明均定位到权威工件、命令与 Git checkpoint;失败不能推进 verified 或 Done。
47
44
 
48
45
  ## 完成声明的版本
49
46
 
@@ -1,44 +1,23 @@
1
- > 通用编排方法唯一权威:<Path>{roots.references}/coordination/coordination-contract.md</Path>。本文件仅补充 SpecDev Goal 的既有 DAG、工作区、集成和状态职责。
1
+ # Lead 编排与动态派单
2
2
 
3
- # Lead 编排与动态派单协议
3
+ 共同方法读取 <Path>{roots.references}/coordination/coordination-contract.md</Path>;票据调度和工作区规则读取 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path>。
4
4
 
5
- ## 1. 唯一 Lead
5
+ ## 唯一 Lead 与实际执行者
6
6
 
7
- Lead 是主会话中的唯一编排 owner,保留需求解释、DAG/Wave/Gate、路径分配、权限、SpecDev 状态、Evidence、候选验收、父分支集成和最终回复责任。恢复时以 Goal Plan 的 `lead` locator 和权威工件继续;更换会话只转移 Lead 身份,不产生第二写入者。
7
+ Lead 保留需求解释、DAG/Wave/Gate、路径分配、授权、正式状态、Evidence、整体 E2E 和最终回复。Lead 是职责,不是单 Agent 拓扑;实现可由单 Agent、subagent 或团队完成,按用户/项目/Work 要求安排。独立 reviewer 不参与本范围实现。
8
8
 
9
- ## 2. 派单类型
9
+ ## 调度与并发
10
10
 
11
- - **implementation**:写入 Goal Plan 选择的 current workspace 或 Ticket worktree 的授权项目路径,运行非 E2E 检查并返回 implementation/source commit;
12
- - **review**:只读审查固定 checkpoint,返回 findings;
13
- - **research**:只读收集代码或外部事实,返回来源与结论;
14
- - **test-observation**:只读运行或观察已授权检查,返回命令与结果,不拥有 E2E Gate。
11
+ serial 完成一票的实现、审查和验证后再开始下一票,同票内部仍可合作。auto/parallel 只推进 Ready、依赖满足、路径和语义资源无冲突的票;max_parallel_tickets 计量票据,显式实现者限制另行核对。Wave 不是填满 Agent 数的目标。review/research/test-observation 默认只读,不额外占票据槽;review 状态的原票仍计入活动票数。
15
12
 
16
- Lead 在 Ticket 可以独立执行、写路径不冲突、上下文足够且平台支持时派单。派单是执行期决定,不写回 Goal Plan 作为固定拓扑。
13
+ ## 写集与派单
17
14
 
18
- ## 3. 并发
15
+ 所有本 change 执行者使用 README 的同一工作区;细分授权写集,shared path 有唯一 owner。Git index、commit/checkout/merge 串行协调;没有具体授权不操作。正式 Ticket/Map/Goal/Evidence/Outcome 只由 Lead 写入。
19
16
 
20
- required 模式 实现执行者 上限取 Goal Plan、实际存在的 config 与平台能力的最小值;current 模式保持单 writer 串行安全不变量;Lead 参与实现时计入。review/research/test-observation agent 不设置 SpecDev 数字上限,但 Lead 必须避免测试资源冲突、重复工作和上下文失控。
17
+ 实际派遣按 <Path>{roots.references}/coordination/task-brief.md</Path> 绑定票据/Spec、依赖证据、不可变基线、选定工作区、允许路径/动作、验证、停止条件和返回位置。外部交接使用原 sessions;TASK 派遣前冻结,派遣后准确确认的会话日志绝对路径只写同任务 session-locator.json 的 path 字段,新合同在投递/回收时分别运行交接校验。原生协作按需交接,不建 Agent 注册表。返回包含实际实现者、路径、checkpoint 或快照、dirty 状态、命令结果、未验证项及 blocker。
21
18
 
22
- ## 4. 写入边界
19
+ ## 验收与恢复
23
20
 
24
- 实现执行者 只写分配的 current workspace 或 worktree 中的项目路径和其 Git commit,不写 Ticket、Map、Goal Plan、Evidence、README Outcome 或父分支。current 模式 commit 直接落在 parent branch;required 模式 commit 落在 source branch。其他 任务执行者 全部只读。Lead 接收返回后独立核对,再写本次负责工件的独有事实。
21
+ Lead 回读实际工具和工作区事实,在稳定输入上完成审查和检查;REPORT completed 不等于 Ticket done。E2E Gate 仍由 Lead 执行并核验,实施者自报不替代。输入漂移后仅使相关证据失效。
25
22
 
26
- ## 5. 动态 Dispatch Packet
27
-
28
- 每次派单必须绑定 Ticket、Goal Plan、依赖 Evidence、不可变 `base_sha`、branch/workspace locator、workspace strategy、writable/read-only/shared paths、provider、允许动作、非 E2E 验证、停止条件和返回格式。provider 或模型按当次能力与授权选择;外部 provider 需要独立的数据发送授权。
29
-
30
- implementation 返回至少包含:Ticket ID、workspace locator、最终 commit、dirty 状态、修改路径、检查命令/结果、未验证项、冲突与阻塞。review/research 返回固定输入、findings、来源和未验证声明。
31
-
32
- ## 6. Lead 验收
33
-
34
- Lead 核对基线、路径、commit、dirty 状态、项目事实与非 E2E 结果;不接受 任务执行者 自报的 Evidence 或 E2E pass。required implementation 候选进入 dev-worktree candidate-merge;current implementation 由 Lead 在同一 parent branch/current workspace 做 direct-parent 验证。read-only 结果由 Lead 复核后写入对应权威工件。首次失败可返回同一 workspace/worktree 修正或标记 blocked。
35
-
36
- 同一 Ticket 在 implementation/review 反复返回相同 blocker、下一轮没有产生新证据,或 integration attempts 达到有效 Plan 的 `integration_attempt_limit` 时,停止把相同请求直接退回原 implementation owner。Lead 保留 workspace、commit/candidate 与失败事实,在现有 Ticket Evidence 中回答四项:共同失败模式、最可能原因、下一轮具体改变、下一 owner/路由。Lead 可改写指导、调整 Ticket 内实现路径、更换 implementation owner 或自行实现;若发现 Ticket、Goal、父 Plan、Spec/ADR 已失效,则返回对应 owner。
37
-
38
- 只有 Lead 的复盘决定已写入 Evidence,才可将当前 Ticket 的 `attempts` 重置为 `0` 并发出新 Dispatch Packet;新 Packet 必须引用该 Evidence 并明确相较上一轮改变了什么。没有实质变化时不得重新派发同一请求。上限因此是 Lead 复盘触发点,不是 Ticket 的永久失败终态。
39
-
40
- **完成标准**:每次写入只有一个 Ticket/owner/worktree;所有 SpecDev 状态由 Lead 落盘;派单、返回与重复失败后的 Lead 决定可从 Evidence 恢复。
41
-
42
- ## 可解释的再派发
43
-
44
- 重复 blocker 且没有新证据时保持原停滞停止。新的 Dispatch 明确改变输入、方法、范围、环境或处置的哪一项;仅更换 Agent、重置 attempts、让用户再答相同问题不构成恢复。旧历史保留,按原 owner 和依赖闭包处理。
23
+ 重复同一 blocker 无新证据或达到有效尝试上限时停止重复派单;原 Evidence 保存共同失败模式、可能原因、下一轮改变和 owner/路由。形成有实质变化的新 Dispatch Packet 才能重置 attempts;仅换 Agent、重置计数或重问同一问题不构成恢复。契约失效返回真正 owner,其他独立票可继续。
@@ -14,7 +14,7 @@ Lead 将输出保存到调用方自己的既有 Evidence 位置;不创建独
14
14
 
15
15
  1. 重读当前 map、Ticket frontmatter、Gate 与 owner;机器检查依赖、Skill、语义资源和路径,Lead 核验真实授权及当前 Git 事实。
16
16
  2. 只有依赖成功满足、ready、owner 可判定且无冲突的票才能进入 dispatch。单 change 的未来 draft 票只阻塞自身及依赖闭包;上游 done 后仍需 Lead 按真实产物重审 DoR,不自动提升 Ready。cancelled 不是成功交付:下游必须重规划依赖,不能自动视为 satisfied。
17
- 3. current 策略严格单 writer;required 使用原计划 `Execution Policy Source` 确定的并发与尝试上限,核对实际存在的 config/宿主限制,Lead 实际参与实现时计入。写集、语义资源、integration queue 无冲突才并行。不同文件可能共享 API、数据表、锁文件或公共契约,因此不能只比较文件名。
17
+ 3. 按 auto/serial/parallel、父子票据上限和 DAG/路径/语义资源选择 frontier;max_parallel_tickets 只计票,显式人数限制由 Lead 根据实际协作另行核对。所有票复用所属 change 工作区,Git index/ref 和共享验证资源串行协调。
18
18
  4. 按票的调用阶段读取并实际执行必需 Skill;按项目协议调用的“技能”可以是宿主技能调用,也可以是完整执行该 SKILL 的程序步骤,但必须记录对应步骤/工具轨迹与输出,不得仅记录阅读完成。
19
19
  5. I 返回后核对实现、Skill 执行记录、验证矩阵、实际交付数量和集成证据。失败保留 blocker;不能用减少测试或替换工具来“修好”状态。
20
20
  6. 核验后只更新原 Ticket 的权威状态和本票 Evidence;跨票 Gate 的独有结果留原 Goal。仅当导航、依赖或合同覆盖发生变化时修订 Map,不为票级进度生成持久投影。恢复回读这些原工件与实际 Git,已完成票不重跑副作用;证据持久化失败不推进 done。
@@ -5,7 +5,7 @@
5
5
 
6
6
  本 Work 只编排实现。它不创建或补写子 change 的 Triage、Grill、Wayfinder、Spec、Ticket 或普通 Goal Plan。父 change 创建前,每个输入 change 都必须已有 Ready Spec、Tickets Map 和决策完备的 Ready Tickets;缺一项就停止并报告具体缺口。
7
7
 
8
- 父 change 将所有子 Ticket 投影为 `<member-change>::<ticket-id>` 组合节点,以跨 change implementation super-DAG、全局 workspace 策略、serialization、agent 配额和 integration queue 持续驱动 I-implement。子 Spec/Ticket/Evidence/Git 继续是行为与实现权威,父工件只拥有跨 change 实现编排。
8
+ 父 change 将所有子 Ticket 投影为 `<member-change>::<ticket-id>` 组合节点,以跨 change implementation super-DAG、成员工作区引用、serialization、票据配额与独立实现者约束和 integration queue 持续驱动 I-implement。子 Spec/Ticket/Evidence/Git 继续是行为与实现权威,父工件只拥有跨 change 实现编排。
9
9
 
10
10
  父 change 的主产物是 `<Path>{roots.state}/specdev/changes/{change}/implementation-map.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>`;整体验证写入 `<Path>{roots.state}/specdev/changes/{change}/evidence/implementation-orchestration.md</Path>`。
11
11
 
@@ -53,20 +53,15 @@
53
53
 
54
54
  **完成标准**:父 Map 的 members/tasks/internal edges 与全部子工件精确一致;跨 change 边有来源;DAG 无环;每个并行冲突已依赖化、串行化或阻塞。
55
55
 
56
- ### 3. 一次决定全局执行策略
56
+ ### 3. 确定跨 change 调度
57
57
 
58
- 只询问一次是否开启 Ticket worktree,默认不开启,并把选择写入父 Plan:
58
+ 父 Plan 使用 schema_version: 3、orchestration: lead-directed、唯一 lead、ticket_execution: auto|serial|parallel、integration_attempt_limit 和 ready_for_execution;有明确票据上限才记录 max_parallel_tickets,显式实现者上限用 concurrent_implementation_limit。实际来源写 Execution Policy Source,不把人数、票数、workspace 数量互相换算。
59
59
 
60
- - `current/direct-parent`:全部成员的待实现 Ticket 全局严格串行,只允许一个 current workspace implementation writer;
61
- - `required/candidate-merge`:依赖满足且无 serialization/path/resource 冲突的 Tickets 可跨 change 并行,每个 Ticket 使用自己的 source worktree。
60
+ 按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 引用各成员 README 的 Execution Context。成员可分别使用 current 或自己的 change worktree;父计划不覆盖已有选择、不因派单新建 worktree。一个需求内所有票据及协作者复用其选定工作区。
62
61
 
63
- 在父 Plan 的 Execution Policy Source 记录实际 implementation agent 与 integration attempt 上限来源;已有 config 的有效上限不可提高,缺 config 使用明确项目/本次约定和宿主能力,默认 current 单写入者。Lead 参与实现时计入实现 agent 数;review/research/test-observation agents 只读且不受该数字限制。同一 repository/ref 的 integration 永远串行。
62
+ 父约束与子计划共同作用于票据 DAG、资源和 Gate;serial 全局逐票完成,auto/parallel 选择无冲突 Ready 集合。Agent 的内部合作方式按用户/项目/Work 要求决定。相同 Git index/ref 或测试资源的动作串行协调;跨分支合并仅在明确交付约定与授权下执行。
64
63
 
65
- 使用 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/assets/goal-plan-template.md</Path>` 写父 Plan。已有子 Goal Plan 只提供子 change 内的额外 Gate/约束;其 workspace 策略与父 Plan 冲突时阻塞,不能覆盖父级全局选择。
66
-
67
- Implementation Plan 固定使用 `orchestration: lead-directed`,并显式持久化 `concurrent_implementation_limit`、`integration_attempt_limit`、workspace/integration 策略和唯一 Lead;恢复时不得从会话记忆重建这些值。
68
-
69
- **完成标准**:Lead、workspace/integration 策略、全局 agent 上限、frontier、Wave、serialization owner 和 integration queue 可从父 Plan 恢复。
64
+ **完成标准**:票据调度、成员工作区引用、跨 change Gate、原 owner 和恢复边界均可回读。
70
65
 
71
66
  随后用 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/goal-tickets-map-template.md</Path>` 写父无状态总控入口,并执行 `<Path>{roots.workflows}/specdev/common/skills/plan-quality-review/SKILL.md</Path>`。plan 到此返回计划、门禁和缺失授权;不得自行进入执行循环。
72
67
 
@@ -76,17 +71,17 @@ Implementation Plan 固定使用 `orchestration: lead-directed`,并显式持
76
71
 
77
72
  1. 重读父 Map/Plan、所有子 Ticket/README/Evidence 和 Git;
78
73
  2. 计算依赖满足、lock 可用且配额允许的 ready frontier;
79
- 3. current 模式选择一个 Ticket,required 模式选择一组互不冲突的 Tickets;
74
+ 3. 按 ticket_execution、父子票据上限与路径/资源选择本轮 Ready 票,不从 workspace 类型决定串并行;
80
75
  4. 由父 Plan 记录实际 Dispatch 与 owner,按组合 ID 调用 I-implement;
81
- 5. implementation agent 仅写授权 workspace,Lead 验收 commit/diff/验证/Evidence;
82
- 6. 按 repository/ref queue 串行完成 direct-parent 或 candidate integration;
76
+ 5. 实现者只写成员选定工作区的授权路径,Lead 核验实际 checkpoint/快照、diff 与 Evidence;
77
+ 6. 在稳定输入上验收;Git index/ref 操作和共享验证资源串行协调,只有明确要求才执行跨分支集成;
83
78
  7. 先写回子 Ticket/Evidence 的负责事实,再更新父 Plan 导航/集成 Gate;
84
79
  8. 父 HEAD、Map revision 或子合同变化后使旧 dispatch/candidate stale,并重新 preflight;
85
80
  9. 仍有 frontier 时立即进入下一轮,否则完成或持久化 blocker。
86
81
 
87
82
  I-implement 是实际实现 owner;父 Work 不复制 TDD、代码审查、Evidence 或 worktree 逻辑。用户只在合同冲突、高影响偏差、缺失授权、不可逆动作或无合法 frontier 时被打断。
88
83
 
89
- **完成标准**:单次父激活可以连续完成多个子 Ticket;没有第二个 SpecDev 状态 writer、超限 agent、并发 parent integration 或绕过子 I-implement 完成门。
84
+ **完成标准**:单次父激活可以连续完成多个子 Ticket;没有第二个 SpecDev 状态 writer、超限票据或实现者、并发 parent integration 或绕过子 I-implement 完成门。
90
85
 
91
86
  ### 5. 关闭子 Changes 与父 Change
92
87
 
@@ -109,7 +104,7 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
109
104
  - 父 change 只接受 Spec/Tickets 已 Ready 的成员;
110
105
  - Implementation Map/Plan 可恢复完整组合 DAG、全局策略、frontier 和 integration queue;
111
106
  - 子工件保持权威,父投影与子 Ticket 精确一致;
112
- - current 全局串行,required 只并行无冲突 Ticket,全部实现受父级 agent cap 约束;
107
+ - serial 全局逐票完成;auto/parallel 只推进无冲突票,各成员保留自己的唯一工作区;
113
108
  - I-implement 自动回到父循环,全部子 change 和父 change completed;
114
109
  - aggregate Evidence 与 validator 通过;
115
110
  - 无未经授权的归档、远程 Git、部署或生产副作用。
@@ -13,6 +13,6 @@
13
13
 
14
14
  同一共享 API/schema/锁文件/迁移索引即使路径预测不重叠,也必须根据实际消费者和集成事实决定 dependency 或 serialization。
15
15
 
16
- ## 集成冲突
16
+ ## 共享工作区和 Git 冲突
17
17
 
18
- 同一 repository/ref 的 direct-parent/candidate integration 严格串行。一次父 HEAD 推进后,其他 candidate 全部 stale;必须在最新父状态重新组合并重跑要求的 full suite/E2E。需要新行为或上层决定的 merge conflict 立即停止。
18
+ 同一 workspace 的 Git index/commit/checkout/merge 及共享验证资源串行协调;不同票据的无冲突路径可并行。固定输入漂移后重新冻结并验证,不增加 candidate worktree。只有明确要求跨分支集成交付且授权匹配时才合并;需要新行为或上层决定的冲突停止并保留现场。
@@ -5,26 +5,26 @@
5
5
  1. 重读父 status、Map、Plan、成员 status/Tickets 和 repository;
6
6
  2. 校验 Map revision、Plan source revision、当前 Lead 身份、授权、active dispatch、workspace 与 integration queue;
7
7
  3. 重建 super-DAG 并计算 ready frontier;
8
- 4. 根据 current/required 策略选择本轮节点;
8
+ 4. 根据 auto/serial/parallel、父子票据上限、DAG 与路径/语义资源选择节点;
9
9
  5. 为每个节点形成不可变 Dispatch Packet,task ID 使用组合身份;
10
- 6. 调用 I-implement 完成设计检查、TDD、commit、双轴审查、验证和 Evidence;
11
- 7. Lead 独立验收返回事实并按 repository/ref 串行集成;
10
+ 6. 调用 I 完成设计、TDD、固定 checkpoint/快照、双轴审查、验证和 Evidence;
11
+ 7. Lead 在成员选定工作区独立验收返回,Git index/ref 和公共验证资源串行协调;
12
12
  8. 先写子 Ticket/Evidence 的实际结果,再写 Map 导航与父 Plan 集成/Gate;
13
13
  9. 重读实际 Git 和全部受影响工件,运行 validator;
14
14
  10. 有 frontier 则继续,无 frontier 则完成或持久化 blocker。
15
15
 
16
16
  ## 唯一写入者
17
17
 
18
- 父 Lead 是全部 SpecDev 工件、E2E、integration queue 和父分支推进的唯一 owner。Implementation agent 在 current 模式写唯一当前 workspace,或在 required 模式写绑定 Ticket 的 source worktree;不得写父/子状态、Evidence、其他成员或父分支。
18
+ 父 Lead 拥有本轮正式状态、Evidence、E2E 和验收。实现者只写本成员选定工作区的授权路径,可以按要求组成团队,不能写父/子状态或其他成员文件;同一 change 不另开票据 worktree。
19
19
 
20
20
  ## 自动继续边界
21
21
 
22
- 子 Ticket 正常完成、candidate stale 后可机械重建、已批准且产生新证据的局部实现修正和下一 frontier 选择不再次询问用户。同一 Ticket 反复返回相同 blocker、没有新证据或达到 integration attempt 上限时,停止该 Ticket 的自动重复并回到父 Lead 决策点;父 Lead 重读其全部 Evidence,记录共同失败模式、最可能原因、下一轮改变和下一 owner/路由,再决定改写指导、换 owner、自行实现或返回上游契约 owner。只有形成有实质变化的新 Dispatch Packet 后,才可重置该 Ticket attempts 并重新派发。
22
+ 子 Ticket 正常完成、固定输入漂移后重新核验、已批准且产生新证据的局部实现修正和下一 frontier 选择不再次询问用户。同一 Ticket 反复返回相同 blocker、没有新证据或达到 integration attempt 上限时,停止该 Ticket 的自动重复并回到父 Lead 决策点;父 Lead 重读其全部 Evidence,记录共同失败模式、最可能原因、下一轮改变和下一 owner/路由,再决定改写指导、换 owner、自行实现或返回上游契约 owner。只有形成有实质变化的新 Dispatch Packet 后,才可重置该 Ticket attempts 并重新派发。
23
23
 
24
24
  这个回转不自动终止整个父循环;父 Lead 可以继续其他不受影响的 ready frontier。以下情况才停止并等待用户或上游新决定:
25
25
 
26
26
  - 高影响合同、范围、架构、数据、安全、迁移或验收需要新决定;
27
- - implementation commit、integration 或不可逆动作缺少授权;
27
+ - 明确承诺的 Git 集成或不可逆动作缺少授权;普通快照验收不以提交为前提;
28
28
  - dependency/serialization/path owner 无法由权威事实裁决;
29
29
  - 无合法 frontier 但仍有非终态 Ticket。
30
30
 
@@ -1,58 +1,27 @@
1
- > 通用编排方法唯一权威:<Path>{roots.references}/coordination/coordination-contract.md</Path>。本文件仅补充 SpecDev Goal 的既有 DAG、工作区、集成和状态职责。
2
-
3
1
  # Goal Plan 核心编排协议
4
2
 
5
- 本文件定义 DAG、Wave、Gate、路径所有权、Ticket workspace 策略、Evidence 返回和父分支集成队列。
6
-
7
- ## 1. DAG 与关键路径
8
-
9
- - 依赖权威来自 Ticket frontmatter 的 `blocked_by`;Tickets Map 是投影;
10
- - 计算根节点、扇出、汇合点、关键路径、共享合同 owner 和最终收缩点;
11
- - 依赖只表示真实开始条件,不表达偏好、Agent 交接或“最好先做”;
12
- - 无法独立保持可验证状态的迁移批次必须有明确 Gate 和恢复策略。
13
-
14
- ## 2. Wave 与实现并发
15
-
16
- required 模式的 Wave 内 Ticket 必须 Ready、依赖 Evidence 完整、项目写路径不相交、shared owner 已稳定、适用 Gate 已打开且基线一致。current 模式即使 DAG 存在可并行节点,也强制一次只执行一个 Ticket。
17
-
18
- Lead 根据当前事实决定自行实现或派单。required 模式同时活跃的 实现执行者 不得超过 Goal Plan、实际存在的 config 与平台能力的共同上限;current 模式保持单 writer 串行安全不变量。Lead 参与实现时计入。Wave 是可并发性,不是必须填满的目标。只读 review/research/test-observation agent 不写固定数字上限,但不得写项目或 SpecDev 状态,也不得争用同一可变测试环境。
19
-
20
- ## 3. Gate
21
-
22
- Gate 用可验证状态定义,必须写明:工程/业务状态、开启条件、关闭证据、阻塞范围、Lead/批准人和失败恢复。常见 Gate 包括共享合同稳定、首条垂直路径、迁移完成、旧调用点归零、候选合并通过、发布就绪和观察期结束。
23
-
24
- ## 4. Shared path 与合同
3
+ 共同编排见 <Path>{roots.references}/coordination/coordination-contract.md</Path>;执行选择见 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path>。
25
4
 
26
- 遵循 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`:
5
+ ## DAG、Wave 与调度
27
6
 
28
- 1. 专用 owner Ticket 修改共享路径;
29
- 2. required 模式在其 source worktree 形成 commit 与非 E2E 证据;current 模式在当前 workspace 形成 commit 与证据;
30
- 3. required 模式通过 Lead candidate-merge 进入父分支;current 模式由 Lead 在父分支 direct-parent 验证并推进;
31
- 4. required 模式下游 Ticket 基于新的父分支 checkpoint 创建或刷新 worktree;current 模式仅在前一 Ticket 完成后开始下一个;
32
- 5. 共享合同变化时暂停消费者并修订上游,不让多个执行者竞争写入。
7
+ 依赖权威来自 Ticket blocked_by,Map 是投影。边只表示真实开始条件,不表达 Agent 交接偏好。计算关键路径、扇出/汇合与共享合同 owner;Wave 内票据 Ready、依赖 Evidence 完整、路径与语义资源无冲突且 Gate 已打开。
33
8
 
34
- ## 5. 每 Ticket workspace 记录
9
+ serial 逐票实现、审查和验证;auto/parallel 按条件推进合法集合,不受 current/worktree 类型影响。max_parallel_tickets 计票,既有实现者限制单独遵守。只读探索和同票团队协作不改变票据调度。
35
10
 
36
- 每个进入 I-implement 的 Ticket 建立唯一记录。current 模式使用 `workspace_ref=current`、`branch=parent_branch`,记录 implementation/source/result SHA 与 direct-parent 验证;required 模式使用唯一 `specdev-worktree/<change>/<ticket-id>`,记录 source/candidate/result SHA 与验证状态。Lead 自行实现或派 任务执行者 不改变所选策略。
11
+ ## Gate 与 shared owner
37
12
 
38
- required 模式同一 Ticket 在 candidate 验证失败后保留来源 worktree 并继续修正。新的 source commit 替换当前 `source_checkpoint`,旧 commit 继续由 Git/Evidence 可追溯。成功集成不自动清理 branch/worktree。
13
+ Gate 写明工程/业务状态、开启条件、关闭证据、阻塞范围、owner/批准人和失败恢复。共享合同稳定、垂直路径、迁移、发布、观察期均按实际风险设门,不以完成票数代替。
39
14
 
40
- ## 6. 父分支集成队列
15
+ 按 <Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path> 指定 shared path 的专用 owner Ticket,消费者等其验收后开始。每票都在 change 选定工作区工作;输入变化重新 preflight,不为下游创建 worktree。
41
16
 
42
- required 模式 Lead 串行集成 Ready 候选:
17
+ ## 稳定输入与验收顺序
43
18
 
44
- 1. 冻结最新 `parent_before_sha`;
45
- 2. 在 Lead-owned parent integration checkout 组合父分支与 `source_checkpoint`;
46
- 3. 生成可定位的 `candidate_sha`;
47
- 4. 在 candidate 状态运行集成检查和适用 E2E;
48
- 5. 重读父 HEAD;若变化,将候选标记 `stale` 并重建;
49
- 6. 检查通过且父 HEAD 未变时,父分支 fast-forward 到 candidate;
50
- 7. 重读父 HEAD/tree,写入 `result_sha` 后才允许 Ticket Done。
19
+ Git index 操作和共享环境检查串行协调;停止相关 writer 后冻结实际交付,独立 reviewer 和 Lead 检查相同输入。单票可用实际 commit 或未提交快照,Evidence 引用 README 唯一工作区,不复制生命周期。整体 Gate 覆盖全部票据交付。
51
20
 
52
- 父分支是 source checkpoint 的祖先时 candidate/result 可等于 source SHA,方法为 `fast-forward`;否则 candidate 必须是独立 merge commit。候选失败时父分支保持不变,Ticket 回到 `in_progress` 或 `blocked`。current 模式跳过候选 checkout,Lead 在 current workspace 核对 implementation commit、运行集成检查并记录 `method=direct-parent`;失败时父 HEAD 不推进。
21
+ 验证失败保留现场,按原上限复盘;不创建候选 worktree、不强制每票提交/合并。明确承诺的跨分支集成按具体授权串行执行并重验结果。
53
22
 
54
- ## 7. Expand-contract
23
+ ## Expand-contract
55
24
 
56
- 标准顺序为 expand → migrate → observe → contract → verify。每批迁移独立 commit、按所选策略验证和父分支集成;收缩依据旧调用/数据/协议归零证据,不依据 Ticket 数量推断。
25
+ 顺序保持 expand → migrate → observe → contract → verify,每批有可恢复 checkpoint、验证和所需批准;提交与部署按实际项目交付约定执行。收缩依据旧调用/数据/协议归零证据。
57
26
 
58
- **完成标准**:每个 Ticket 从父基线、implementation/source commit、对应 integration 到 result 都可恢复;父分支只包含已通过所选门禁的 Ticket。
27
+ **完成标准**:票据依赖、资源和验收可恢复,实际交付与 Evidence 一致,额外 Git/发布动作有独立授权和结果。
@@ -1,6 +1,6 @@
1
1
  # Goal Plan 规划模式与输入门禁
2
2
 
3
- 规划模式描述 Goal Plan 需要额外解决的工程问题。Goal Plan 按共享执行策略分别记录执行方式与工作区;执行方式默认当前宿主正常执行,工作区默认 current,复用已有选择,current/direct-parent 与 required/candidate-merge 保持配对。
3
+ 规划模式描述 Goal 额外解决的工程问题;票据调度、Agent 编排与 change 工作区独立,默认 auto 和复用 current。
4
4
 
5
5
  本文件定义单 change 的规划与全局执行门。多 change 父编排创建仍要求成员全员 Ready,遵守 `<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`。
6
6
 
@@ -13,15 +13,15 @@
13
13
  - 等待真实上游产物的未来 Ticket 保持 `status: draft`、`ready: false`,在未决问题中记录缺口、生产者 Ticket、所需证据和 DoR 重审条件;不编造版本、路径或验证入口;
14
14
  - 每个验收合同被 Ticket 覆盖;
15
15
  - writable/shared path 有唯一 owner,Wave 候选无写冲突;
16
- - 原计划的 `Execution Policy Source` 指向项目/本次约定,确定正整数并发与集成尝试上限;实际存在 config 时验证 schema v7 及对应限制,不为规划补建配置;UI 设计候选只在相关分支读取实际 planning 配置;
17
- - 父分支可定位,implementation commit 与本地 integration 的授权状态已记录;`plan` 可以列出待批准项并保持 `ready_for_execution: false`;
16
+ - Execution Policy Source 记录票据调度、明确的票数/人数限制与验证尝试上限;已有 config schema v7 按原义核对,不补建配置;
17
+ - 选定工作区与原授权可定位;commit/merge 仅明确承诺时另行核对,plan 可列待批准项并保持未就绪;
18
18
  - 待执行 Deep Ticket 的迁移、兼容、监控、恢复和不可逆批准点完整。
19
19
  - Ticket 与 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>` 和当前代码事实不存在未处理冲突;
20
20
  - 项目声明的验证命令真实存在,并能观察目标行为;不可运行项有替代证据或明确 blocker;
21
21
  - 当前源码基线、父分支、工作区状态和现有用户改动已经实测;
22
22
  - 外部合同、标准、参考实现或依赖版本已经固定,不使用浮动的“最新”描述。
23
23
 
24
- 影响整体范围、DAG、合同覆盖或所有权的上游事实缺失时返回其 owner。已定位到未来 Ticket 的局部缺口只阻塞该票及其依赖闭包,不阻塞独立 Ready 生产者。非 v7 Goal Plan 必须按当前合同重新规划,不能只修改版本号。
24
+ 影响整体范围、DAG、合同覆盖或所有权的上游事实缺失时返回其 owner。已定位到未来 Ticket 的局部缺口只阻塞该票及其依赖闭包,不阻塞独立 Ready 生产者。非 v8 Goal Plan 必须按当前合同重新规划,不能只修改版本号。
25
25
 
26
26
  ## 2. 可组合模式
27
27
 
@@ -32,24 +32,18 @@
32
32
 
33
33
  没有适用模式时 `modes: []`。模式只增加对应 Gate、证据和恢复,不改变 Lead、worktree 或集成基本合同。
34
34
 
35
- ## 3. Goal Plan 工作区选择
35
+ ## 3. 独立执行选择
36
36
 
37
- - 创建 Goal Plan 时读取 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path>,复用实际工作区选择;未指定默认 current;
38
- - 用户选择 `否` 时写入 `ticket_workspace_policy: current` 与 `integration_gate: direct-parent`;
39
- - 用户选择 `是` 时写入 `ticket_workspace_policy: required` 与 `integration_gate: candidate-merge`;
40
- - 该选择只作用于当前 Goal Plan,不读取或修改全局配置;
41
- - `current` 模式下所有 Ticket 必须串行,并持有唯一 implementation writer 锁;
42
- - `required` 模式继续使用每 Ticket source worktree 和 Lead-owned candidate integration;
43
- - `orchestration` 固定为 `lead-directed`;实现与集成尝试上限来自 `Execution Policy Source`,实际存在 config 时不得超过其限制。未选 worktree 时缺省 current/direct-parent、单 writer;Lead 实际参与实现也计入实现上限。
37
+ 按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 分别记录票据调度、Agent 编排与工作区。默认 ticket_execution:auto,工作区复用 current;用户明确要求才为 change 创建一个 worktree。所有票据与协作者复用它,不询问默认选项,不从串并行派生工作区。
44
38
 
45
39
  ## 4. Ready 停止条件
46
40
 
47
41
  Goal 全局执行门与 Ticket DoR 分开判断。以下任一全局条件未满足时 `ready_for_execution: false`;局部 Ticket 的缺口、资源冲突或未通过 DoR 由逐票检查阻塞对应依赖闭包,不升级成全员停止:
48
42
 
49
43
  - Goal Plan 工作区选择未记录;
50
- - `current` 模式下 Ticket 无法串行排序或当前 workspace 不是唯一项目写入 owner;
51
- - `required` 模式下 Ticket 无法建立独立 worktree 或父分支不明确;
52
- - 当前模式所需的 implementation commit 或 direct-parent/candidate integration 授权缺失;
44
+ - 所选调度存在未解决的依赖、路径或语义资源冲突;
45
+ - 用户选择的 change 工作区无法创建/复用或与实际 Git 冲突;
46
+ - 实现或明确要求的额外 Git/不可逆动作缺少具体授权;
53
47
  - shared path 没有唯一 owner;
54
48
  - E2E 是否需要会改变验收结论但尚未确定;
55
49
  - 整体目标的验证命令不能执行或无法观察目标行为,且没有批准的替代证据;
@@ -60,18 +54,17 @@ Goal 全局执行门与 Ticket DoR 分开判断。以下任一全局条件未满
60
54
 
61
55
  全局门通过后仍只调度自身 Ready、依赖成功完成、owner 明确且资源/并发条件满足的 Ticket。上游 done 不自动修改消费者 Ready;Lead 回读真实产物,按 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/ticket-readiness.md</Path>` 重审后才能更新该票。frontier 为空且仍有未完成票时报告精确缺口与重审条件。
62
56
 
63
- ## 5. 固定执行拓扑
57
+ ## 5. 执行字段
64
58
 
65
- - `orchestration: lead-directed`;
66
- - `ticket_workspace_policy: current | required`;
67
- - `integration_gate: direct-parent | candidate-merge`;
68
- - `current` 与 `direct-parent` 必须成对;`required` 与 `candidate-merge` 必须成对;
69
- - `concurrent_implementation_limit` 与 `integration_attempt_limit` 由 `Execution Policy Source` 说明,实际存在 config 时不超过其限制,实际实现并发不超过宿主能力;current 模式保持单 writer 串行安全不变量;
70
- - Lead 参与实现时计入 实现执行者 数量;
71
- - review/research/test-observation agent 无 SpecDev 固定数字上限,但必须保持只读且不竞争同一可变环境;
72
- - provider 与派单在执行期决定,不成为 Goal Plan 的静态枚举。
59
+ - orchestration: lead-directed 只固定正式状态与验收 owner;
60
+ - ticket_execution: auto | serial | parallel,默认 auto;
61
+ - max_parallel_tickets 为可选正整数,计同时 in_progress/review 的票;
62
+ - concurrent_implementation_limit 仅在明确要求时记录,计实际实现者,包括参与实现的 Lead;
63
+ - integration_attempt_limit 为检查失败后的复盘上限,来源可回读,已有 config 更严格上限继续适用;
64
+ - README Execution Context 唯一记录 change 工作区,计划只导航;
65
+ - provider/模型/具体协作在执行期按用户、项目、Work 和宿主能力决定,不固定 Agent 拓扑。
73
66
 
74
- **完成标准**:所有固定字段、适用模式、授权、Lead、父分支和阻塞均可验证;没有替代编排模型或空占位。
67
+ **完成标准**:调度、工作区、实际约束、权限和 Lead 可恢复,没有用人数、票数或工作区数互相推导。
75
68
 
76
69
  ## 按风险选择 Gate
77
70
 
@@ -3,7 +3,7 @@
3
3
 
4
4
  Goal Plan 只拥有单个 Ticket 无法独立决定的事情:整体 Outcome、跨 Ticket 顺序与并发、共享所有权、里程碑 Gate、动态派单边界、父分支集成、迁移/发布顺序、偏差升级和恢复。Ticket 继续拥有局部实现合同。
5
5
 
6
- 每次 Goal Plan 都采用 `lead-directed`:当前主会话是唯一 Lead,负责计划、SpecDev 状态、Evidence、派单、验收、父分支推进和最终回复。形成 Goal Plan 时按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 分别确定执行方式和工作区,复用已有选择;未指定时按当前宿主正常执行,工作区默认 current,选择写入当前 Goal Plan,不修改全局配置。不开启时 Ticket 严格串行,允许动态派遣 实现执行者,但同一时间只有一个 implementation owner 可写当前 workspace;开启时沿用每 Ticket 独立 worktree 与 candidate-merge。
6
+ 每次 Goal Plan 使用 lead-directed 表示唯一状态和验收 owner;实现团队按要求决定。按 <Path>{roots.workflows}/specdev/common/rules/execution-policy.md</Path> 分别确定票据调度、Agent 编排和 change 工作区;复用已有选择,不修改全局配置。
7
7
 
8
8
  产物写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`。
9
9
 
@@ -59,11 +59,11 @@ Goal Plan 只拥有单个 Ticket 无法独立决定的事情:整体 Outcome、
59
59
  1. 验证 Spec、Tickets、合同覆盖、DAG、路径所有权和待执行 Deep Ticket 完整性;未来 draft 票按规划输入门记录局部缺口;
60
60
  2. 只读探索影响调度的代码与项目事实;
61
61
  3. 识别 migration、high-assurance、reference-conformance、release-coordination 等适用模式;
62
- 4. 从项目/本次约定读取实际并发与尝试上限,在 `Execution Policy Source` 记录来源并填写既有 `concurrent_implementation_limit` 与 `integration_attempt_limit`;存在 config 时不得超过其有效上限或平台能力,Lead 参与实现时计入;
63
- 5. 根据 workspace 策略记录实现 commit 与 direct-parent/candidate integration 授权事实;缺失时仍可完成 plan 文档,但 ready_for_execution 保持 false,并列为 run 的阻塞条件;
62
+ 4. 在 Execution Policy Source 记录 ticket_execution、可选 max_parallel_tickets 及验证尝试上限;显式实现者限制独立核对,不把人数换成票数;
63
+ 5. 核对本次实现与工作区创建的实际授权;commit/merge 仅在明确交付要求下另行核对,不作为默认每票执行门;
64
64
  6. 只询问无法发现且会改变 Gate、Wave、owner、迁移、批准或验收的问题。
65
65
 
66
- **完成标准**:计划内 Ticket、范围、覆盖、DAG 与所有权完整;未来 draft 票已记录真实缺口、生产者证据和 DoR 重审条件;Lead、授权状态、实现并发上限和父分支可判定。缺执行授权时可交付规划,但 `ready_for_execution` 保持 `false`。
66
+ **完成标准**:计划内 Ticket、范围、覆盖、DAG 与所有权完整;未来 draft 票已记录真实缺口、生产者证据和 DoR 重审条件;Lead、授权状态、票据策略、明确存在的实现者限制和工作区选择可判定。缺执行授权时可交付规划,但 `ready_for_execution` 保持 `false`。
67
67
 
68
68
  ### 2. 构建 Outcome、DAG、Wave 与 Gate
69
69
 
@@ -72,20 +72,20 @@ Goal Plan 只拥有单个 Ticket 无法独立决定的事情:整体 Outcome、
72
72
  1. 压缩 Outcome、成功/伪完成、非目标和权威来源;
73
73
  2. 从 Ticket frontmatter 构建 DAG、关键路径、扇出与汇合点;
74
74
  3. 为 shared path、共享合同和集中修改指定唯一 owner;
75
- 4. 将依赖满足且项目写路径不相交的 Ticket 分入 Wave;current 模式仍按依赖顺序串行执行,不得把 Wave 当作并发授权;
75
+ 4. 将依赖满足、路径与语义资源无冲突的票分入候选 Wave,按 serial/auto/parallel 和票据上限实际推进;
76
76
  5. 为合同稳定、垂直路径、迁移完成、发布就绪等状态定义 Gate;
77
77
  6. 为每个 Ticket 记录开始条件、workspace 策略、验证层级、Evidence 目标、集成顺序和失败恢复。
78
78
 
79
- **完成标准**:DAG、Wave、Gate 与 Tickets Map 一致;每个 Ticket 有唯一项目写 owner、worktree 合同和可验证集成出口。
79
+ **完成标准**:DAG、Wave、Gate 与 Tickets Map 一致;每个 Ticket 有明确写集 owner、change 工作区引用和可验证出口。
80
80
 
81
81
  ### 3. 固定 Lead 编排与动态派单合同
82
82
 
83
83
  加载 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/lead-orchestration.md</Path>`,并按规划阶段读取 `<Path>{roots.references}/coordination/task-brief.md</Path>`:
84
84
 
85
85
  1. 固定 Lead 的可恢复 owner/session locator;
86
- 2. 按 `Execution Policy Source` 声明实现与集成尝试上限,核对实际存在的 config/平台限制,Lead 实际参与实现时计入;
86
+ 2. 按 `Execution Policy Source` 声明票据策略、验证尝试上限和明确存在的票据/实现者上限,核对实际 config/平台限制,Lead 实际参与实现时计入人数;
87
87
  3. 不为只读 review/research/test-observation agent 写 SpecDev 数字上限;
88
- 4. current 模式固定只有一个 implementation writer 写项目路径,Lead 仍是唯一 SpecDev 工件与状态写入者;required 模式 implementation owner 写自己的 Ticket worktree;
88
+ 4. 所有执行者复用 change 选定工作区并细分写集;正式状态/Evidence 仍由 Lead 写入;
89
89
  5. 定义执行期动态 Dispatch Packet、候选返回和 Lead 验收;
90
90
  6. provider、模型和具体派单在 Ticket 开始时按事实选择,不在 Goal Plan 中预分配。
91
91
 
@@ -97,12 +97,12 @@ Goal Plan 只拥有单个 Ticket 无法独立决定的事情:整体 Outcome、
97
97
 
98
98
  1. 定义整体 Definition of Done 和每个 Gate 的关闭证据;
99
99
  2. 固化不可协商约束与允许的局部实现自由;
100
- 3. 按 workspace 策略为每个 Ticket 明确 current-workspace/direct-parent 检查或 source-worktree/parent-candidate 检查;
100
+ 3. 每票在选定 change-workspace 冻结实际输入并完成本票检查,Lead 核验整体 Gate;
101
101
  4. E2E 按 Ticket 实际跨边界风险标记 required 或 not-required;
102
- 5. 定义 direct-parent 验证失败、candidate 冲突/失败、父 HEAD 漂移、偏差、暂停、批准和恢复动作;
102
+ 5. 定义共享资源冲突、检查失败、快照漂移、偏差、暂停和恢复;
103
103
  6. 定义 change 完成、远程 reconcile、残余风险和回滚要求。
104
104
 
105
- **完成标准**:每个完成声明映射到不可变 commit、候选/父分支 SHA、命令、Evidence 或人工批准。
105
+ **完成标准**:每个完成声明映射到固定 commit 或工作副本快照、命令、Evidence 或人工批准。
106
106
 
107
107
  ### 5. 写入、导航与验证
108
108
 
@@ -120,7 +120,7 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
120
120
  ```
121
121
 
122
122
  5. 写回 Goal Plan 的 Gate/执行事实与 Map 导航,README 只保留目标/接续并重新读取;
123
- 6. 向用户报告 Outcome、关键路径、Wave/Gate、Lead、实现 agent 上限、shared owner、E2E disposition、迁移与主要风险;
123
+ 6. 向用户报告 Outcome、关键路径、Wave/Gate、Lead、票据调度与已明确的实现者限制、shared owner、E2E disposition、迁移与主要风险;
124
124
  7. 未经用户要求,不自动进入实现。
125
125
 
126
126
  ## 决策完备标准
@@ -131,19 +131,19 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
131
131
  - 跨 Ticket 先后、Wave、Gate 和关键汇合点;
132
132
  - shared path 与共享合同 owner;
133
133
  - 实现执行者 上限及动态派单边界;
134
- - 每 Ticket workspace、implementation commit、对应验证和父分支推进规则;
134
+ - change 唯一工作区、每票固定输入和验证出口,以及明确承诺的 Git 交付;
135
135
  - E2E disposition、偏差、暂停、批准和恢复路径。
136
136
 
137
137
  Goal Plan 不复制 Ticket 的局部施工路线、全部文件预测或逐项验收清单。
138
138
 
139
139
  ## 完成标准
140
140
 
141
- - Goal Plan schema v7 且 `ready_for_execution` 与状态一致;
141
+ - Goal Plan schema v8 且 `ready_for_execution` 与状态一致;
142
142
  - 规划完成与执行就绪分别报告;允许交付 `draft / ready_for_execution: false`,单 change 不创建父 Implementation Map/Plan;
143
143
  - 等待上游产物的未来票保持 draft,局部缺口只阻塞依赖闭包;进入执行的票必须重新通过 DoR,上游完成不自动提升 Ready;
144
144
  - Lead 唯一,Execution Policy Source 可回读,实际存在的 config/平台限制已核对,Lead 实际参与实现时计入;review/research agent 不受 SpecDev 数字限制;
145
- - 每个实现 Ticket 都有 workspace、commit、对应 integration gate 和 Evidence 出口;
146
- - current 模式不创建 source/candidate worktree,适用 E2E 由 Lead 在 current workspace 运行;required 模式保持 source/parent-candidate 边界;
145
+ - 每张票有真实工作区引用、checkpoint/快照、验证和 Evidence 出口;
146
+ - current/worktree 均可串行或并行票据;所有执行者复用 change 工作区,E2E 由 Lead 在稳定输入上执行;
147
147
  - 计划只保留当前固定 Lead 与选定 workspace/integration 合同;
148
148
  - validator 无 error,Tickets Map 导航与合同覆盖正确,用户收到下一步选择。
149
149
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: specdev-r-retro
3
- description: "对指定开发活动、环境或协作流程的已观察摩擦做证据化复盘,形成根因、改进 owner 与可检验提案;代码讲解使用 L-learn,Speculo 产品反馈使用 retro 命令。"
3
+ description: "复盘开发会话并积累有原文来源的独立 RETRO;明确要求时汇总未归档报告,先提出项目 Skill 升级方案,确认后更新或新增 Skill 并归档已处置报告。"
4
4
  metadata:
5
5
  speculo-kind: work-skill
6
6
  speculo-id: specdev/retro
@@ -8,24 +8,28 @@ metadata:
8
8
  speculo-contract-version: "2"
9
9
  ---
10
10
 
11
- # 开发复盘
11
+ # 开发复盘与项目 Skill 迭代
12
12
 
13
- 先读 <Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>。本 Work 不自动修代码、提 Issue 或改永久知识。
13
+ 先读 <Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>,再读 <Path>{roots.references}/writing-for-agents/writing-contract.md</Path>。本 Work 改善后续开发 Agent 的环境;默认只复盘,明确要求迭代才进入方案分支。代码讲解使用 L-learn,Speculo 产品反馈使用 retro Command。
14
14
 
15
15
  ## 流程
16
16
 
17
- 1. 固定本次会话/活动范围,按来源 ID 定位 change、测试、CI、交接和失败证据,不全读历史。缺失资料列 unknown;范围清楚且证据可定位才开始分析。
18
- 2. 未归档且尚未 completed 的当前 change 使用其 retro 目录。completed 或 archived 来源以及独立复盘建立非实现 review change,引用原 locator;不重开来源状态或改写归档。按 <Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path> 初始化/恢复;存在重叠实际 writer 时先由原 owner 停止或真实交接。
19
- 3. 调用 <Path>{roots.references}/retrospective/retrospective-contract.md</Path>,检查约束是否缺失、已有检查是否失效或未接入;区分环境事实、机械检查和判断规则。每个发现有因果证据或明确假设,建议有 owner、正反验收与路由。
20
- 4. 按 <Path>{roots.workflows}/specdev/specdev-r-retro/assets/retro-template.md</Path> 创建 <Path>{roots.state}/specdev/changes/{change}/retro/RETRO-###.md</Path>,选择最小未占用 ID。原子保存并重读,运行 SpecDev --stage retro;修订保留来源与被替代结论。
21
- 5. 验证通过后回读原 RETRO 并在 README 导航接续;证据不足可完成一份 outcome=insufficient-evidence 的诚实报告,不冒充解决问题。只读复盘不创建 Spec/Ticket 或 implementation Evidence。review-only change 按专用完成门关闭。
17
+ 1. 识别用户要日常复盘,还是梳理/执行升级方案。日常复盘未指定会话时使用当前会话;批量梳理默认使用当前项目尚未归档的 RETRO。只有用户指定才扩大来源范围。
18
+ 2. 日常复盘按 [开发复盘方法](references/development-retrospective.md) 定位一手记录、检查七类环境问题,并给每个发现保留原文、来源 change 或会话、根因或假设、影响、频率、owner 和正反验收。按严重程度呈现候选,允许没有发现。
19
+ 3. 按 [报告模板](assets/retro-template.md) 和 [独立工件合同](references/records.md) 保存 <Path>{roots.state}/specdev/retro/{retro}/RETRO.md</Path>。`retro` 为首次创建时未占用的日期主题 ID;证据快照只保留相关原文。原子写后回读并运行独立校验;不创建 change,不修改来源 change 的 Outcome。
20
+ 4. 明确要求集中迭代时读取 [升级流程](references/skill-upgrade.md),固定未归档报告清单、去重并复核当前项目事实,形成 <Path>{roots.state}/specdev/retro/{upgrade}/PLAN.md</Path>。先交付完整具体方案;确认前仅保存方案及候选,不更新项目 Skill、不归档。
21
+ 5. 用户确认方案后,用 <Path>{roots.references}/writing-for-agents/references/project-skill-maintenance.md</Path> 更新或新增获批项目 Skill,逐项验证并保存原方案的执行回执。只有全部计划内升级通过,才调用 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/retro-archive.md</Path> 归档方案指定且全部发现已处置的报告;仍有待处理项的报告留在现役目录。
22
22
 
23
23
  ## 改进必须能被证伪
24
24
 
25
- 逐项判断是规则缺失、规则未接入、规则判断错、测试不能失败或环境事实变化。建议说明真正修改位置、owner、正反验收、恢复影响和新增维护成本;不要对每个问题都增加一条提示词。记录已观察因果、尚未验证解释和不采纳理由,复盘报告不等于修复完成。
25
+ 逐项判断是规则缺失、规则未接入、规则判断错、测试不能失败或环境事实变化。建议说明真正修改位置、owner、正反验收、恢复影响和新增维护成本。机械问题进入检查工具,判断性规则进入 reviewer 的标准;Skill 承载可复用过程,不把每次失误都变成一条指令。成功经验也须有适用条件及重复使用价值。
26
26
 
27
27
  ## 结果与路由
28
28
 
29
- 合法 outcome:findings、no-findings、insufficient-evidence。发现的 disposition 为 file-issue / lesson-only / discard / duplicate;每项记录理由,允许没有发现。
29
+ 报告 outcome 为 findings、no-findings、insufficient-evidence;报告完成不表示建议已实施。方案逐项 adopt / reject / defer,合并项通过共同目标与理由保留全部来源。事实不足时保持 defer,不用多数历史记录覆盖当前相反证据。
30
30
 
31
- 代码问题交 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/SKILL.md</Path>,计划改进交 <Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>,远程反馈交 <Path>{roots.workflows}/specdev/specdev-t-triage/SKILL.md</Path>;永久知识交 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/SKILL.md</Path>。返回完整报告、已验证与未验证项、下一入口;不自动推进这些后续副作用。
31
+ 代码问题交 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/SKILL.md</Path>,代码/CI 检查实施交 <Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>,远程反馈交 <Path>{roots.workflows}/specdev/specdev-t-triage/SKILL.md</Path>;ADR/context 写入交 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/SKILL.md</Path> 的原网关。这些动作不由 Skill 升级授权隐式覆盖。
32
+
33
+ ## 完成标准
34
+
35
+ 日常复盘的范围、原文来源、全部候选与未知可追溯,报告已保存并通过校验。升级方案确认前返回具体候选及未决项;确认后返回实际更新/新增/保留的 Skill、命令及退出码、未验证项、归档结果和恢复入口。未通过验证或存在漂移的分支保持阻塞,已落地结果据实保留;语法验证不认证宿主触发、用户授权或未来效果。