@namewta/speculo 0.7.1 → 0.7.3

package/template/canonical/canonical-specdev-wayfinder.md

@@ -324,16 +324,14 @@ resolution: answered
 
 ```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"
   },
@@ -358,33 +356,31 @@ resolution: answered
 ```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",
@@ -408,7 +404,7 @@ resolution: answered
       "additionalProperties": true
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }
 ```
 
@@ -418,7 +414,7 @@ resolution: answered
 
 ```json
 {
-  "schema_version": 4,
+  "schema_version": 5,
   "workflow": "specdev",
   "active": [],
   "archived": []
@@ -432,83 +428,27 @@ resolution: answered
 ```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",
@@ -529,11 +469,24 @@ resolution: answered
 
 ```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,
@@ -552,216 +505,157 @@ resolution: answered
 ```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
-          },
-          "provider": {
-            "enum": [
-              "native",
-              "git",
-              "external"
-            ]
-          },
-          "base_sha": {
-            "type": "string",
-            "minLength": 1
-          },
-          "branch": {
-            "type": "string",
-            "minLength": 1
-          },
-          "workspace_ref": {
-            "type": "string",
-            "minLength": 1,
-            "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
-          },
-          "status": {
-            "enum": [
-              "planned",
-              "active",
-              "review",
-              "integrated",
-              "removed",
-              "blocked"
-            ]
-          },
-          "updated_at": {
-            "type": "string",
-            "minLength": 1
-          }
-        },
-        "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
 }
 ```
 

package/template/skills/migrate-runtime-state/SKILL.md

@@ -43,25 +43,25 @@ node scripts/migrate-runtime-state.mjs inspect --project-root <project-root>
 
 ### 3. 生成确定性计划
 
-生成 schema v1 JSON plan。`backup_manifest_sha256` 锁定 inspect 现场；`source_decisions` 必须逐项覆盖 manifest 中的每个文件且不得包含 `unresolved`；`actions` 仅使用脚本支持的动作：
+生成 schema v2 JSON plan。`backup_manifest_sha256` 锁定 inspect 现场；`source_decisions` 必须逐项覆盖 manifest 中的每个文件且不得包含 `unresolved`；每个 action 必须以 `source_decision` 显式引用唯一来源决策，且动作、decision disposition 与目标一一对应：
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "backup_manifest_sha256": "<inspect 返回的 sha256>",
   "source_decisions": [
     {"path": "config.json", "disposition": "merge-json", "target": "config.json"},
+    {"path": "state/specdev/context.md", "disposition": "restore", "target": ".speculo/specdev/context.md"},
     {"path": "state/workspace.json", "disposition": "keep-current", "target": ".speculo/workspace.json"}
   ],
   "actions": [
-    {"kind": "copy", "from": "state/specdev/context", "to": ".speculo/specdev/context", "expected_target": "absent"},
-    {"kind": "replace-json", "to": ".speculo/specdev/status.json", "value": {}, "expected_target": "file:<sha256>"},
-    {"kind": "keep-current", "to": "config.json", "expected_target": "file:<sha256>"}
+    {"kind": "copy", "source_decision": "state/specdev/context.md", "from": "state/specdev/context.md", "to": ".speculo/specdev/context.md", "expected_target": "absent"},
+    {"kind": "replace-json", "source_decision": "config.json", "to": "config.json", "value": {}, "expected_target": "file:<sha256>"}
   ]
 }
 ```
 
-`from` 必须相对 backup root；`to` 只能是 `config.json` 或 `.speculo/` 内非受保护路径。每个 action 都使用 `fingerprint` 输出锁定 `expected_target`；目标相互重叠时拆成不重叠动作。Plan 写入调用方声明的临时位置，报告保存等价 Markdown 表格；正式 state 不保存第二份 plan。
+`from` 必须与 `source_decision` 相同且相对 backup root；`copy ↔ restore`、`replace-json ↔ merge-json|replace-json`、`keep-current ↔ keep-current`、`remove-current ↔ remove-current`。只有 `keep-current` 决策可省略 action。`to` 只能是 `config.json` 或 `.speculo/` 内非受保护路径。每个 action 都使用 `fingerprint` 输出锁定 `expected_target`；目标相互重叠时拆成不重叠动作。Plan 写入调用方声明的临时位置，报告保存等价 Markdown 表格；正式 state 不保存第二份 plan。
 
 **完成标准**：计划可由脚本解析，路径均在授权边界内，受管理静态资产和 `back/` 不会成为目标。
 

package/template/skills/migrate-runtime-state/references/migration-contract.md

@@ -26,6 +26,11 @@
 - `active` 从仍位于 `changes/` 且 change 状态为 active/blocked/completed 的真实目录核对；不得创建虚假 change。
 - `archived` 从 `archive/YYYY-MM/<change>/` 核对，active/archived 不得重叠。
 - `config.json` 保留语言、Git、执行、验证与规划偏好，并补入当前 schema 的必需默认值。
+- SpecDev config v3 升级为 v4 时，`execution.max_parallel` 只作为旧并发偏好的输入，收敛到 `execution.max_implementation_agents: 1..3`；删除旧的自动提交和条件 worktree 开关，不把它们解释为授权。
+- change-status v3 只有在 `worktrees` 缺失或为空时才可确定性升级为 v4；存在旧 worktree 记录时，必须逐 Ticket 重建 implementation owner、source commit、candidate/result、E2E disposition 和父分支包含关系。v4 runtime 不得自动升级为 v5：旧状态无法可靠推断 execution authorization 或 Lead leadership，必须保持 pending 并显式对账。
+- active Goal Plan 不是 v5 时必须重新规划固定 Lead、Ticket worktree 和 candidate integration gate；不能只改 frontmatter 版本号。
+- 已声明为 v4 的 SpecDev config，以及已声明为 v5 的 global status、change-status 和 Goal Plan，必须完整满足当前 schema：必需字段、类型、枚举、嵌套对象和 `additionalProperties` 边界都通过后才能自动保留。不得为不完整状态静默补默认值，也不得只扫描少量标记字段。
+- worktree `removed` 只接受为 `integrated` 后的清理终态；source checkpoint、passed candidate/result、验证、E2E disposition 和 Evidence 必须完整保留。
 - `.config/`、`adr/`、`context/`、`research/`、`changes/`、`archive/` 和声明的 sidecar 都是持久项。
 - Command Markdown 报告和具有当前 owner 的 `state.json` 均迁移；未知 command state 保持 unresolved。
 
@@ -49,10 +54,11 @@
 
 ## 验证
 
-- backup manifest 的每个 file hash、size 和 symlink 条目与现场一致；存在 symlink 时阻塞。
-- plan 的 `backup_manifest_sha256` 与现场一致，`source_decisions` 恰好覆盖 manifest 全部条目，且每个 action 的 `expected_target` 与 active 现场一致。
+- backup manifest 的每个 file hash、size，以及每个 symlink 的类型和 link target 都必须与现场一致；link 本身保留为 pending 事实，不能被自动恢复到 active runtime。
+- plan 的 `backup_manifest_sha256` 与现场一致，`source_decisions` 恰好覆盖 manifest 全部条目；每个 action 必须显式 `source_decision`，且只可实现该 decision 的同目标、同 disposition 动作。除 `keep-current` 外，每个 decision 必须恰有一个 action；每个 action 的 `expected_target` 与 active 现场一致。
+- action 后、删除 staged marker 前、原子替换后都递归拒绝 active runtime 中的 symlink；任何失败均恢复原 active 安装。
 - 所有迁移后 JSON 可解析。
 - workspace、install manifest、项目配置和已安装 workflow 全局状态满足当前版本。
-- SpecDev active/archive 索引与目录一致；person 状态满足 schema v1。
+- SpecDev active/archive 索引与目录一致；SpecDev config 满足 v4 合同，global status、change-status 与 Goal Plan 满足 v5 合同；person 状态满足 schema v1。
 - pending marker 只在全部验证通过后从 staged 安装删除。
 - 执行后 backup manifest 与内容 hash 不变。