@namewta/speculo 0.3.0 → 0.3.2

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

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:change-status:v3",
+  "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"
+  ],
+  "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
+    },
+    "completed_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "archived": {
+      "type": "boolean"
+    },
+    "archive_path": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "string",
+          "pattern": "^<Path>\\{roots\\.state\\}/specdev/archive/[^<]+</Path>$"
+        }
+      ]
+    },
+    "blockers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "deviations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "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": {
+          "change_status": {
+            "const": "archived"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "archived": {
+            "const": true
+          },
+          "archive_path": {
+            "type": "string",
+            "pattern": "^<Path>\\{roots\\.state\\}/specdev/archive/[^<]+</Path>$"
+          }
+        }
+      }
+    }
+  ],
+  "additionalProperties": true
+}

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

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:config:v3",
+  "title": "SpecDev Configuration",
+  "type": "object",
+  "required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
+  "properties": {
+    "schema_version": {"const": 3},
+    "interaction_language": {"type": "string", "minLength": 1},
+    "artifact_language": {"type": "string", "minLength": 1},
+    "git": {
+      "type": "object",
+      "required": ["auto_commit", "default_branch", "worktree_for_parallel"],
+      "properties": {
+        "auto_commit": {"type": "boolean"},
+        "default_branch": {"type": ["string", "null"]},
+        "worktree_for_parallel": {"type": "boolean"}
+      },
+      "additionalProperties": true
+    },
+    "execution": {
+      "type": "object",
+      "required": ["max_parallel", "deep_ticket_human_approval", "shared_path_owner"],
+      "properties": {
+        "max_parallel": {"type": "integer", "minimum": 1},
+        "deep_ticket_human_approval": {"type": "boolean"},
+        "shared_path_owner": {"type": "string", "minLength": 1}
+      },
+      "additionalProperties": true
+    },
+    "verification": {
+      "type": "object",
+      "required": ["test", "typecheck", "lint", "build"],
+      "properties": {
+        "test": {"type": ["string", "null"]},
+        "typecheck": {"type": ["string", "null"]},
+        "lint": {"type": ["string", "null"]},
+        "build": {"type": ["string", "null"]}
+      },
+      "additionalProperties": true
+    },
+    "planning": {
+      "type": "object",
+      "required": ["default_depth", "require_ready_gate", "require_evidence"],
+      "properties": {
+        "default_depth": {"enum": ["lite", "standard", "deep"]},
+        "require_ready_gate": {"type": "boolean"},
+        "require_evidence": {"type": "boolean"}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/template/workflows/specdev/common/schemas/goal-plan.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:goal-plan:v3",
+  "title": "SpecDev Goal Plan Frontmatter",
+  "type": "object",
+  "required": ["schema_version", "artifact", "change", "status", "modes", "ready_for_execution"],
+  "properties": {
+    "schema_version": {"const": 3},
+    "artifact": {"const": "goal-plan"},
+    "change": {"type": "string", "minLength": 1},
+    "status": {"enum": ["draft", "ready", "in_progress", "completed", "blocked"]},
+    "modes": {
+      "type": "array",
+      "items": {"enum": ["coordination", "migration", "high-assurance", "reference-conformance", "release-coordination"]},
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "ready_for_execution": {"type": "boolean"}
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:spec:v3",
+  "title": "SpecDev Spec Frontmatter",
+  "type": "object",
+  "required": ["schema_version", "artifact", "change", "status", "ready_for_tickets", "sources"],
+  "properties": {
+    "schema_version": {"const": 3},
+    "artifact": {"const": "spec"},
+    "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "status": {"enum": ["draft", "ready", "superseded"]},
+    "ready_for_tickets": {"type": "boolean"},
+    "sources": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "uniqueItems": true}
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:status:v3",
+  "title": "SpecDev Global Status",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "workflow",
+    "active",
+    "work_history",
+    "completed"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 3
+    },
+    "workflow": {
+      "const": "specdev"
+    },
+    "active": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "change",
+          "current_work",
+          "works_run",
+          "result"
+        ],
+        "properties": {
+          "change": {
+            "type": "string"
+          },
+          "current_work": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "works_run": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "result": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "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": true
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "work_history": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "change",
+          "work_id",
+          "started_at",
+          "completed_at",
+          "result"
+        ],
+        "properties": {
+          "change": {
+            "type": "string"
+          },
+          "work_id": {
+            "type": "string",
+            "pattern": "^specdev/"
+          },
+          "started_at": {
+            "type": "string"
+          },
+          "completed_at": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "result": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "completed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "change",
+          "archived_at",
+          "archive_path"
+        ],
+        "properties": {
+          "change": {
+            "type": "string"
+          },
+          "archived_at": {
+            "type": "string"
+          },
+          "archive_path": {
+            "type": "string",
+            "pattern": "^<Path>\\{roots\\.state\\}/specdev/archive/[^<]+</Path>$"
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:ticket:v3",
+  "title": "SpecDev Ticket Frontmatter",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "artifact",
+    "change",
+    "id",
+    "title",
+    "status",
+    "planning_depth",
+    "planning_depth_reason",
+    "ready",
+    "risk",
+    "blocked_by",
+    "contract_ids",
+    "owner",
+    "expected_changes",
+    "writable_paths",
+    "read_only_paths",
+    "shared_paths",
+    "shared_path_owners"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 3
+    },
+    "artifact": {
+      "const": "ticket"
+    },
+    "change": {
+      "type": "string",
+      "minLength": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^T-[0-9]{2,}$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "ready",
+        "in_progress",
+        "blocked",
+        "review",
+        "done",
+        "deviated",
+        "cancelled"
+      ]
+    },
+    "planning_depth": {
+      "enum": [
+        "lite",
+        "standard",
+        "deep"
+      ]
+    },
+    "planning_depth_reason": {
+      "type": "string",
+      "minLength": 1
+    },
+    "ready": {
+      "type": "boolean"
+    },
+    "risk": {
+      "enum": [
+        "low",
+        "medium",
+        "high",
+        "critical"
+      ]
+    },
+    "blocked_by": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^T-[0-9]{2,}$"
+      },
+      "uniqueItems": true
+    },
+    "contract_ids": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1
+    },
+    "expected_changes": {
+      "$ref": "#/$defs/pathArray"
+    },
+    "writable_paths": {
+      "$ref": "#/$defs/pathArray"
+    },
+    "read_only_paths": {
+      "$ref": "#/$defs/pathArray"
+    },
+    "shared_paths": {
+      "$ref": "#/$defs/pathArray"
+    },
+    "shared_path_owners": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^<Path>[^<]+</Path>\\s*=>\\s*[^=].+$"
+      },
+      "uniqueItems": true
+    }
+  },
+  "$defs": {
+    "pathArray": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^<Path>[^<]+</Path>$"
+      },
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": true
+}

package/template/workflows/specdev/common/schemas/tickets-map.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:tickets-map:v3",
+  "title": "SpecDev Tickets Map Frontmatter",
+  "type": "object",
+  "required": ["schema_version", "artifact", "change", "status"],
+  "properties": {
+    "schema_version": {"const": 3},
+    "artifact": {"const": "tickets-map"},
+    "change": {"type": "string", "minLength": 1},
+    "status": {"enum": ["draft", "ready", "in_progress", "completed", "blocked"]}
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,28 @@
+---
+name: specdev-dev-worktree
+description: 为并行写代码的 Ready Ticket 建立隔离 worktree，并由 Lead 完成基线、集成验证和清理。Goal Plan Lead 在创建、恢复或收尾 Ticket worktree 时使用。
+---
+
+# SpecDev Dev Worktree
+
+## 适用范围
+
+- 仅用于并行写代码且路径所有权不冲突的 Ready Ticket。
+- 只读调查和顺序执行默认共用当前工作区。
+- Lead 管理创建、集成和清理；Worker 只实现、验证并返回 Evidence。
+- 平台原生 worktree 优先；不可用时使用 Git worktree。
+
+## 生命周期
+
+1. 创建或恢复时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/create.md</Path>`。
+2. Worker 完成后将记录从 `active` 更新为 `review`，返回 Ticket 状态、Evidence 路径、`workspace_ref`、commit 或 PR 引用，以及条件性 Lead E2E。
+3. Lead 集成或清理时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/finalize.md</Path>`。
+
+状态依次为 `planned → active → review → integrated → removed`；失败进入 `blocked`。记录写入 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees`。
+
+## 边界
+
+- 每个并行 Ticket 使用独立 worktree、分支和相同 `base_sha`。
+- 持久状态只保存 `workspace_ref`，不保存机器绝对路径。
+- E2E 仅由 Lead 在集成阶段执行，且仅适用于用户界面交互受影响的变更。
+- 合并、推送、PR、删除分支或 worktree 仍需用户授权。

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

@@ -0,0 +1,30 @@
+# 创建或恢复 Ticket Worktree
+
+## 前置
+
+- Ticket `ready: true`，依赖完成，写路径无冲突。
+- `<Path>{roots.state}/specdev/config.json</Path>` 中 `git.worktree_for_parallel: true`。
+- Lead 已固定所有并行 Ticket 共用的 `base_sha`。
+
+## 创建
+
+1. 若 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 已有该 Ticket 的 `active` 或 `review` 记录，解析 `workspace_ref` 并验证分支、`base_sha` 和工作区状态；一致则恢复。
+2. 否则优先调用平台原生 worktree 能力；不可用时从 `base_sha` 执行 `git worktree add -b <ticket-branch> <physical-path> <base-sha>`。物理路径必须位于主工作树之外。
+3. 分支使用 `speculo/<change>/<ticket-id>`；现有分支或目标路径未能匹配记录时停止。
+4. 安装项目所需依赖，运行最小基线检查。E2E 不属于 Worker 基线。
+5. 写入 `worktrees`：
+
+```json
+{
+  "ticket_id": "T-01",
+  "owner": "<worker>",
+  "provider": "native",
+  "base_sha": "<sha>",
+  "branch": "speculo/<change>/T-01",
+  "workspace_ref": "<provider-opaque-or-project-relative-ref>",
+  "status": "active",
+  "updated_at": "<ISO-8601>"
+}
+```
+
+完成条件：工作区可定位、基线可用、状态记录与实际分支一致。失败时设为 `blocked` 并保留现场。

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

@@ -0,0 +1,16 @@
+# 集成与清理 Ticket Worktree
+
+## Lead 集成
+
+1. 确认记录为 `review`，读取 Worker Evidence，实际修改未越过路径契约。
+2. 在目标集成基线上应用变更并运行受影响的定向与回归验证。
+3. 仅当变更影响用户界面交互时，由 Lead 运行验收所需的最小 E2E；Worker 只提供场景和预期结果。
+4. 验证通过后将记录更新为 `integrated`；冲突或失败时设为 `blocked` 并保留 worktree。
+
+## 清理
+
+1. 取得用户对删除 worktree 和分支的授权。
+2. 从主工作树或平台管理入口移除已集成 worktree。
+3. 确认 worktree 不再注册后删除对应分支，并将状态更新为 `removed`。
+
+PR 或暂缓集成时保留 worktree。清理失败时停止；仅在用户明确要求时使用强制删除。

package/template/workflows/specdev/common/skills/research/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: specdev-research
+description: 针对影响 SpecDev 决策的外部技术、依赖、标准或未知行为进行来源分级研究，并输出可追踪的结论与不确定性。
+---
+
+# SpecDev Research
+
+## 触发
+
+当外部 API、库版本、协议、法规、产品能力或最佳实践会改变设计/实现决策，且当前材料不足时使用。
+
+## 流程
+
+1. 写清楚要支持的具体决策和停止条件。
+2. 优先官方文档、规范、源代码、论文或维护者材料；技术问题优先一手来源。
+3. 核对版本、发布日期、适用环境和已知限制。
+4. 区分：来源明确事实、代码库事实、推断、建议。
+5. 对关键结论至少交叉验证；来源冲突时并列呈现，不强行调和。
+6. 记录摘要、证据、置信度、对 ADR/Spec/Ticket 的影响和仍未知项。
+7. 长期有效且经实现验证后才可由 Archive 提升到永久 research。
+
+## 输出模板
+
+```markdown
+# Research: <问题>
+- 决策用途：
+- 范围/版本：
+- 停止条件：
+
+## Findings
+### R-001
+- 结论：
+- 类型：官方事实 / 代码事实 / 推断 / 建议
+- 来源：
+- 置信度：high / medium / low
+- 适用限制：
+- 对工件影响：
+
+## Conflicts and Unknowns
+## Recommendation
+```
+
+不得长篇复制受版权保护的来源；使用短引文和自己的准确摘要。