@namewta/speculo 0.7.2 → 0.7.3

package/template/canonical/canonical-specdev-grill-with-docs.md

@@ -513,7 +513,7 @@ Ticket 告诉执行者：做什么、为什么、不能改变什么、按什么
 
 ### Deep
 
-任一条件触发：公共 API、schema、wire format、数据迁移、认证授权、隐私、资金、不可逆操作、expand-contract、共享核心路径、多 Agent 复杂协作、多个实质架构方案或高事故半径。
+任一条件触发：公共 API、schema、wire format、数据迁移、认证授权、隐私、资金、不可逆操作、expand-contract、共享核心路径、多个 implementation owner 的跨 Ticket 写入协调、多个实质架构方案或高事故半径。
 
 额外要求：数据流或状态转换、兼容窗口、迁移顺序、可观测性、回滚、风险缓解、收缩条件和人工批准点。
 
@@ -593,7 +593,7 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 
 - 未批准的 ticket、spec、architecture 或 release 偏差不得继续实现。
 - 不得通过扩大 `writable_paths`、删除测试、降低断言或把风险改写成“已知限制”来绕过停止。
-- 偏差影响普通并行执行时，当前集成 owner 必须暂停受影响 Wave，重新计算路径所有权、依赖和 Gate；委派执行由 Lead 承担同一责任。
+- 偏差影响并行执行、source checkpoint 或 candidate 集成时，Lead 必须暂停受影响 Wave，重新计算路径所有权、依赖、Gate 与父分支顺序；任何 subagent 都不能自行改写上层合同。
 
 </deviation-control>
 
@@ -656,16 +656,14 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 
 ```json
 {
-  "schema_version": 3,
+  "schema_version": 4,
   "interaction_language": "zh-CN",
   "artifact_language": "zh-CN",
   "git": {
-    "auto_commit": false,
-    "default_branch": null,
-    "worktree_for_parallel": true
+    "default_branch": null
   },
   "execution": {
-    "max_parallel": 3,
+    "max_implementation_agents": 3,
     "deep_ticket_human_approval": true,
     "shared_path_owner": "explicit"
   },
@@ -690,33 +688,31 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 ```json
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:config:v3",
+  "$id": "urn:speculo:specdev:config:v4",
   "title": "SpecDev Configuration",
   "type": "object",
   "required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
   "properties": {
-    "schema_version": {"const": 3},
+    "schema_version": {"const": 4},
     "interaction_language": {"type": "string", "minLength": 1},
     "artifact_language": {"type": "string", "minLength": 1},
     "git": {
       "type": "object",
-      "required": ["auto_commit", "default_branch", "worktree_for_parallel"],
+      "required": ["default_branch"],
       "properties": {
-        "auto_commit": {"type": "boolean"},
-        "default_branch": {"type": ["string", "null"]},
-        "worktree_for_parallel": {"type": "boolean"}
+        "default_branch": {"type": ["string", "null"]}
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "execution": {
       "type": "object",
-      "required": ["max_parallel", "deep_ticket_human_approval", "shared_path_owner"],
+      "required": ["max_implementation_agents", "deep_ticket_human_approval", "shared_path_owner"],
       "properties": {
-        "max_parallel": {"type": "integer", "minimum": 1},
+        "max_implementation_agents": {"type": "integer", "minimum": 1, "maximum": 3},
         "deep_ticket_human_approval": {"type": "boolean"},
         "shared_path_owner": {"type": "string", "minLength": 1}
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "verification": {
       "type": "object",
@@ -740,7 +736,7 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
       "additionalProperties": true
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }
 ```
 
@@ -750,7 +746,7 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 
 ```json
 {
-  "schema_version": 4,
+  "schema_version": 5,
   "workflow": "specdev",
   "active": [],
   "archived": []
@@ -764,83 +760,27 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 ```json
 {
   "$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",
@@ -861,11 +801,24 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 
 ```json
 {
-  "schema_version": 3,
+  "schema_version": 5,
   "artifact": "change-status",
   "change": "<YYYY-MM-DD-topic>",
   "change_status": "active",
   "current_work": null,
+  "works_run": [],
+  "claimed_investigations": [],
+  "execution_authorization": {
+    "implementation_commit": {"status": "not-authorized", "source": null, "granted_at": null, "scope": "Ticket source commits"},
+    "local_candidate_integration": {"status": "not-authorized", "source": null, "granted_at": null, "scope": "Lead-owned local parent candidate integration and parent update"},
+    "source_cleanup": {"status": "not-authorized", "source": null, "granted_at": null, "scope": "Source worktree and branch cleanup"}
+  },
+  "leadership": {
+    "current": "<owner-or-session-locator>",
+    "epoch": 1,
+    "assigned_at": "<ISO-8601>",
+    "history": []
+  },
   "created_at": "<ISO-8601>",
   "updated_at": "<ISO-8601>",
   "completed_at": null,
@@ -884,394 +837,157 @@ Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
 ```json
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:change-status:v3",
+  "$id": "urn:speculo:specdev:change-status:v5",
   "title": "SpecDev Change Status",
   "type": "object",
   "required": [
-    "schema_version",
-    "artifact",
-    "change",
-    "change_status",
-    "current_work",
-    "created_at",
-    "updated_at",
-    "completed_at",
-    "archived",
-    "archive_path",
-    "blockers",
-    "deviations"
+    "schema_version", "artifact", "change", "change_status", "current_work", "works_run",
+    "claimed_investigations", "execution_authorization", "leadership", "created_at", "updated_at",
+    "completed_at", "archived", "archive_path", "blockers", "deviations", "worktrees"
   ],
   "properties": {
-    "schema_version": {
-      "const": 3
-    },
-    "artifact": {
-      "const": "change-status"
-    },
-    "change": {
-      "type": "string",
-      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
-    },
-    "change_status": {
-      "enum": [
-        "active",
-        "blocked",
-        "completed",
-        "archived"
-      ]
-    },
-    "current_work": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "created_at": {
-      "type": "string",
-      "minLength": 1
-    },
-    "updated_at": {
-      "type": "string",
-      "minLength": 1
+    "schema_version": {"const": 5},
+    "artifact": {"const": "change-status"},
+    "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "change_status": {"enum": ["active", "blocked", "completed", "archived"]},
+    "current_work": {"type": ["string", "null"], "pattern": "^specdev/"},
+    "works_run": {"type": "array", "items": {"type": "string", "pattern": "^specdev/"}, "uniqueItems": true},
+    "claimed_investigations": {"type": "array", "items": {"$ref": "#/$defs/claim"}},
+    "execution_authorization": {"$ref": "#/$defs/authorization"},
+    "leadership": {"$ref": "#/$defs/leadership"},
+    "created_at": {"type": "string", "minLength": 1},
+    "updated_at": {"type": "string", "minLength": 1},
+    "completed_at": {"type": ["string", "null"]},
+    "archived": {"type": "boolean"},
+    "archive_path": {"anyOf": [{"type": "null"}, {"type": "string", "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"}]},
+    "blockers": {"type": "array", "items": {"type": "string"}},
+    "deviations": {"type": "array", "items": {"type": "string"}},
+    "worktrees": {"type": "array", "items": {"$ref": "#/$defs/worktree"}}
+  },
+  "$defs": {
+    "claim": {
+      "type": "object",
+      "required": ["id", "owner", "session", "claimed_at"],
+      "properties": {
+        "id": {"type": "string", "minLength": 1},
+        "owner": {"type": "string", "minLength": 1},
+        "session": {"type": ["string", "null"]},
+        "claimed_at": {"type": "string", "minLength": 1}
+      },
+      "additionalProperties": false
     },
-    "completed_at": {
-      "type": [
-        "string",
-        "null"
-      ]
+    "authorization-entry": {
+      "type": "object",
+      "required": ["status", "source", "granted_at", "scope"],
+      "properties": {
+        "status": {"enum": ["authorized", "not-authorized", "revoked"]},
+        "source": {"type": ["string", "null"]},
+        "granted_at": {"type": ["string", "null"]},
+        "scope": {"type": "string", "minLength": 1}
+      },
+      "allOf": [{
+        "if": {"properties": {"status": {"const": "authorized"}}, "required": ["status"]},
+        "then": {"properties": {"source": {"type": "string", "minLength": 1}, "granted_at": {"type": "string", "minLength": 1}}}
+      }],
+      "additionalProperties": false
     },
-    "archived": {
-      "type": "boolean"
+    "authorization": {
+      "type": "object",
+      "required": ["implementation_commit", "local_candidate_integration", "source_cleanup"],
+      "properties": {
+        "implementation_commit": {"$ref": "#/$defs/authorization-entry"},
+        "local_candidate_integration": {"$ref": "#/$defs/authorization-entry"},
+        "source_cleanup": {"$ref": "#/$defs/authorization-entry"}
+      },
+      "additionalProperties": false
     },
-    "archive_path": {
-      "anyOf": [
-        {
-          "type": "null"
-        },
-        {
-          "type": "string",
-          "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"
-        }
-      ]
+    "leadership-history": {
+      "type": "object",
+      "required": ["owner", "epoch", "assigned_at", "ended_at"],
+      "properties": {
+        "owner": {"type": "string", "minLength": 1},
+        "epoch": {"type": "integer", "minimum": 1},
+        "assigned_at": {"type": "string", "minLength": 1},
+        "ended_at": {"type": "string", "minLength": 1}
+      },
+      "additionalProperties": false
     },
-    "blockers": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
+    "leadership": {
+      "type": "object",
+      "required": ["current", "epoch", "assigned_at", "history"],
+      "properties": {
+        "current": {"type": "string", "minLength": 1},
+        "epoch": {"type": "integer", "minimum": 1},
+        "assigned_at": {"type": "string", "minLength": 1},
+        "history": {"type": "array", "items": {"$ref": "#/$defs/leadership-history"}}
+      },
+      "additionalProperties": false
     },
-    "deviations": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
+    "full-suite": {
+      "type": "object",
+      "required": ["required", "status", "reason", "evidence"],
+      "properties": {
+        "required": {"type": "boolean"},
+        "status": {"enum": ["not-required", "pending", "passed", "failed"]},
+        "reason": {"type": ["string", "null"]},
+        "evidence": {"type": ["string", "null"]}
+      },
+      "allOf": [{
+        "if": {"properties": {"required": {"const": false}}, "required": ["required"]},
+        "then": {"properties": {"status": {"const": "not-required"}, "reason": {"type": "string", "minLength": 1}}}
+      }],
+      "additionalProperties": false
     },
-    "worktrees": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": [
-          "ticket_id",
-          "owner",
-          "provider",
-          "base_sha",
-          "branch",
-          "workspace_ref",
-          "status",
-          "updated_at"
-        ],
-        "properties": {
-          "ticket_id": {
-            "type": "string",
-            "pattern": "^T-[0-9]{2,}$"
-          },
-          "owner": {
-            "type": "string",
-            "minLength": 1
-          },
-          "integration_owner": {
-            "type": "string",
-            "minLength": 1
-          },
-          "provider": {
-            "enum": [
-              "native",
-              "git",
-              "external"
-            ]
-          },
-          "base_sha": {
-            "type": "string",
-            "minLength": 1
-          },
-          "parent_branch": {
-            "type": "string",
-            "minLength": 1
-          },
-          "branch": {
-            "type": "string",
-            "minLength": 1
-          },
-          "workspace_ref": {
-            "type": "string",
-            "minLength": 1,
-            "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
-          },
-          "terminal_action": {
-            "enum": [
-              "integrate",
-              "retain"
-            ]
-          },
-          "source_checkpoint": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "integration": {
-            "type": "object",
-            "required": [
-              "status",
-              "parent_before_sha",
-              "source_sha",
-              "result_sha",
-              "method",
-              "conflict_paths",
-              "verification",
-              "evidence",
-              "attempts"
-            ],
-            "properties": {
-              "status": {
-                "enum": [
-                  "pending",
-                  "running",
-                  "passed",
-                  "blocked"
-                ]
-              },
-              "parent_before_sha": {
-                "type": ["string", "null"]
-              },
-              "source_sha": {
-                "type": ["string", "null"]
-              },
-              "result_sha": {
-                "type": ["string", "null"]
-              },
-              "method": {
-                "enum": [null, "fast-forward", "merge-commit"]
-              },
-              "conflict_paths": {
-                "type": "array",
-                "items": {"type": "string"}
-              },
-              "verification": {
-                "enum": ["pending", "passed", "failed"]
-              },
-              "evidence": {
-                "type": "string",
-                "pattern": "^\\{roots\\.state\\}/specdev/changes/[^<]+/evidence/T-[0-9]{2,}\\.md$"
-              },
-              "attempts": {
-                "type": "integer",
-                "minimum": 0
-              }
-            },
-            "additionalProperties": true
-          },
-          "status": {
-            "enum": [
-              "planned",
-              "active",
-              "review",
-              "integrating",
-              "integrated",
-              "removed",
-              "blocked"
-            ]
-          },
-          "updated_at": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "dependentRequired": {
-          "terminal_action": [
-            "integration_owner",
-            "parent_branch",
-            "source_checkpoint",
-            "integration"
-          ]
-        },
-        "allOf": [
-          {
-            "if": {
-              "properties": {
-                "status": {"const": "integrating"}
-              },
-              "required": ["status"]
-            },
-            "then": {
-              "required": [
-                "terminal_action",
-                "integration_owner",
-                "parent_branch",
-                "source_checkpoint",
-                "integration"
-              ],
-              "properties": {
-                "terminal_action": {"const": "integrate"}
-              }
-            }
-          },
-          {
-            "if": {
-              "properties": {
-                "status": {"enum": ["integrating", "integrated"]},
-                "terminal_action": {"const": "integrate"}
-              },
-              "required": ["status", "terminal_action"]
-            },
-            "then": {
-              "properties": {
-                "source_checkpoint": {"type": "string", "minLength": 1},
-                "integration": {
-                  "properties": {
-                    "parent_before_sha": {"type": "string", "minLength": 1},
-                    "source_sha": {"type": "string", "minLength": 1},
-                    "attempts": {"type": "integer", "minimum": 1}
-                  }
-                }
-              }
-            }
-          },
-          {
-            "if": {
-              "properties": {
-                "status": {"const": "integrating"},
-                "terminal_action": {"const": "integrate"}
-              },
-              "required": ["status", "terminal_action"]
-            },
-            "then": {
-              "properties": {
-                "integration": {
-                  "properties": {
-                    "status": {"const": "running"}
-                  }
-                }
-              }
-            }
-          },
-          {
-            "if": {
-              "properties": {
-                "status": {"const": "integrated"},
-                "terminal_action": {"const": "integrate"}
-              },
-              "required": ["status", "terminal_action"]
-            },
-            "then": {
-              "properties": {
-                "integration": {
-                  "properties": {
-                    "status": {"const": "passed"},
-                    "result_sha": {"type": "string", "minLength": 1},
-                    "method": {"enum": ["fast-forward", "merge-commit"]},
-                    "verification": {"const": "passed"}
-                  }
-                }
-              }
-            }
-          },
-          {
-            "if": {
-              "properties": {
-                "terminal_action": {"const": "retain"}
-              },
-              "required": ["terminal_action"]
-            },
-            "then": {
-              "properties": {
-                "status": {
-                  "not": {"enum": ["integrating", "integrated"]}
-                }
-              }
-            }
-          }
-        ],
-        "additionalProperties": true
-      }
-    }
-  },
-  "allOf": [
-    {
-      "if": {
-        "properties": {
-          "worktrees": {
-            "contains": {
-              "properties": {
-                "provider": {
-                  "const": "git"
-                }
-              },
-              "required": [
-                "provider"
-              ]
-            }
-          }
-        }
+    "worktree": {
+      "type": "object",
+      "required": ["ticket_id", "owner", "implementation_owner", "integration_owner", "provider", "base_sha", "parent_branch", "branch", "workspace_ref", "source_checkpoint", "integration", "status", "updated_at"],
+      "properties": {
+        "ticket_id": {"type": "string", "pattern": "^T-[0-9]{2,}$"},
+        "owner": {"type": "string", "minLength": 1},
+        "implementation_owner": {"type": "string", "minLength": 1},
+        "integration_owner": {"type": "string", "minLength": 1},
+        "provider": {"const": "git"},
+        "base_sha": {"type": "string", "minLength": 1},
+        "parent_branch": {"type": "string", "minLength": 1},
+        "branch": {"type": "string", "minLength": 1},
+        "workspace_ref": {"type": "string", "pattern": "^specdev-worktree/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*/T-[0-9]{2,}$"},
+        "source_checkpoint": {"type": ["string", "null"]},
+        "integration": {"$ref": "#/$defs/integration"},
+        "status": {"enum": ["planned", "active", "review", "integrating", "integrated", "removed", "blocked"]},
+        "updated_at": {"type": "string", "minLength": 1}
       },
-      "then": {
-        "properties": {
-          "worktrees": {
-            "items": {
-              "if": {
-                "properties": {
-                  "provider": {
-                    "const": "git"
-                  }
-                },
-                "required": [
-                  "provider"
-                ]
-              },
-              "then": {
-                "properties": {
-                  "workspace_ref": {
-                    "pattern": "^specdev-worktree/T-[0-9]{2,}$"
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
+      "additionalProperties": false
     },
-    {
-      "if": {
-        "properties": {
-          "change_status": {
-            "const": "archived"
-          }
-        }
+    "integration": {
+      "type": "object",
+      "required": ["status", "parent_ref", "parent_before_sha", "source_sha", "candidate_sha", "candidate_tree_sha", "candidate_branch", "candidate_workspace_ref", "result_sha", "method", "conflict_paths", "verification", "full_suite", "e2e", "evidence", "attempts", "promotion_status"],
+      "properties": {
+        "status": {"enum": ["pending", "candidate", "passed", "failed", "stale"]},
+        "parent_ref": {"type": ["string", "null"]},
+        "parent_before_sha": {"type": ["string", "null"]},
+        "source_sha": {"type": ["string", "null"]},
+        "candidate_sha": {"type": ["string", "null"]},
+        "candidate_tree_sha": {"type": ["string", "null"]},
+        "candidate_branch": {"type": ["string", "null"]},
+        "candidate_workspace_ref": {"anyOf": [{"type": "null"}, {"type": "string", "pattern": "^specdev-worktree/\\.integration/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*/T-[0-9]{2,}$"}]},
+        "result_sha": {"type": ["string", "null"]},
+        "method": {"enum": [null, "fast-forward", "merge-commit"]},
+        "conflict_paths": {"type": "array", "items": {"type": "string"}},
+        "verification": {"enum": ["pending", "passed", "failed"]},
+        "full_suite": {"$ref": "#/$defs/full-suite"},
+        "e2e": {"$ref": "#/$defs/full-suite"},
+        "evidence": {"type": "string", "pattern": "^\\{roots\\.state\\}/specdev/changes/[^<]+/evidence/T-[0-9]{2,}\\.md$"},
+        "attempts": {"type": "integer", "minimum": 0},
+        "promotion_status": {"enum": ["pending", "applying", "applied", "failed", "stale"]}
       },
-      "then": {
-        "properties": {
-          "archived": {
-            "const": true
-          },
-          "archive_path": {
-            "type": "string",
-            "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"
-          }
-        }
-      }
+      "additionalProperties": false
     }
-  ],
-  "additionalProperties": true
+  },
+  "allOf": [{
+    "if": {"properties": {"change_status": {"const": "archived"}}, "required": ["change_status"]},
+    "then": {"properties": {"archived": {"const": true}, "archive_path": {"type": "string", "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"}}}
+  }],
+  "additionalProperties": false
 }
 ```