@namewta/speculo 0.7.3 → 0.7.4

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:change-status:v5",
+  "$id": "urn:speculo:specdev:change-status:v6",
   "title": "SpecDev Change Status",
   "type": "object",
   "required": [
@@ -9,7 +9,7 @@
     "completed_at", "archived", "archive_path", "blockers", "deviations", "worktrees"
   ],
   "properties": {
-    "schema_version": {"const": 5},
+    "schema_version": {"const": 6},
     "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"]},
@@ -113,12 +113,39 @@
         "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,}$"},
+        "workspace_ref": {"type": "string", "pattern": "^(?:current|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}
       },
+      "allOf": [
+        {
+          "if": {"properties": {"workspace_ref": {"const": "current"}}, "required": ["workspace_ref"]},
+          "then": {
+            "properties": {
+              "integration": {
+                "allOf": [{
+                  "properties": {
+                    "candidate_sha": {"const": null},
+                    "candidate_tree_sha": {"const": null},
+                    "candidate_branch": {"const": null},
+                    "candidate_workspace_ref": {"const": null},
+                    "method": {"enum": [null, "direct-parent"]}
+                  }
+                }]
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "integration": {
+                "allOf": [{"properties": {"method": {"enum": [null, "fast-forward", "merge-commit"]}}}]
+              }
+            }
+          }
+        }
+      ],
       "additionalProperties": false
     },
     "integration": {
@@ -134,7 +161,7 @@
         "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"]},
+        "method": {"enum": [null, "direct-parent", "fast-forward", "merge-commit"]},
         "conflict_paths": {"type": "array", "items": {"type": "string"}},
         "verification": {"enum": ["pending", "passed", "failed"]},
         "full_suite": {"$ref": "#/$defs/full-suite"},

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

@@ -1,11 +1,11 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:config:v4",
+  "$id": "urn:speculo:specdev:config:v5",
   "title": "SpecDev Configuration",
   "type": "object",
   "required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
   "properties": {
-    "schema_version": {"const": 4},
+    "schema_version": {"const": 5},
     "interaction_language": {"type": "string", "minLength": 1},
     "artifact_language": {"type": "string", "minLength": 1},
     "git": {
@@ -18,9 +18,10 @@
     },
     "execution": {
       "type": "object",
-      "required": ["max_implementation_agents", "deep_ticket_human_approval", "shared_path_owner"],
+      "required": ["max_implementation_agents", "max_integration_attempts", "deep_ticket_human_approval", "shared_path_owner"],
       "properties": {
-        "max_implementation_agents": {"type": "integer", "minimum": 1, "maximum": 3},
+        "max_implementation_agents": {"type": "integer", "minimum": 1},
+        "max_integration_attempts": {"type": "integer", "minimum": 1},
         "deep_ticket_human_approval": {"type": "boolean"},
         "shared_path_owner": {"type": "string", "minLength": 1}
       },
@@ -39,14 +40,19 @@
     },
     "planning": {
       "type": "object",
-      "required": ["default_depth", "require_ready_gate", "require_evidence"],
+      "required": ["default_depth", "require_ready_gate", "require_evidence", "ui_prototype_default_variants", "ui_prototype_max_variants"],
       "properties": {
         "default_depth": {"enum": ["lite", "standard", "deep"]},
         "require_ready_gate": {"type": "boolean"},
-        "require_evidence": {"type": "boolean"}
+        "require_evidence": {"type": "boolean"},
+        "ui_prototype_default_variants": {"type": "integer", "minimum": 1},
+        "ui_prototype_max_variants": {"type": "integer", "minimum": 1}
       },
       "additionalProperties": true
     }
   },
+  "allOf": [{
+    "$comment": "ui_prototype_default_variants <= ui_prototype_max_variants is enforced by validate-specdev.mjs because JSON Schema cannot compare sibling numeric values."
+  }],
   "additionalProperties": false
 }

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

@@ -1,15 +1,15 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:specdev:goal-plan:v5",
+  "$id": "urn:speculo:specdev:goal-plan:v6",
   "title": "SpecDev Goal Plan Frontmatter",
   "type": "object",
   "required": [
     "schema_version", "artifact", "change", "status", "modes", "orchestration",
-    "lead", "implementation_agent_limit", "ticket_workspace_policy", "integration_gate",
+    "lead", "implementation_agent_limit", "integration_attempt_limit", "ticket_workspace_policy", "integration_gate",
     "ready_for_execution"
   ],
   "properties": {
-    "schema_version": {"const": 5},
+    "schema_version": {"const": 6},
     "artifact": {"const": "goal-plan"},
     "change": {"type": "string", "minLength": 1},
     "status": {"enum": ["draft", "ready", "in_progress", "completed", "blocked"]},
@@ -20,12 +20,21 @@
     },
     "orchestration": {"const": "lead-directed"},
     "lead": {"type": "string", "minLength": 1},
-    "implementation_agent_limit": {"type": "integer", "minimum": 1, "maximum": 3},
-    "ticket_workspace_policy": {"const": "required"},
-    "integration_gate": {"const": "candidate-merge"},
+    "implementation_agent_limit": {"type": "integer", "minimum": 1},
+    "integration_attempt_limit": {"type": "integer", "minimum": 1},
+    "ticket_workspace_policy": {"enum": ["current", "required"]},
+    "integration_gate": {"enum": ["direct-parent", "candidate-merge"]},
     "ready_for_execution": {"type": "boolean"}
   },
   "allOf": [
+    {
+      "if": {"properties": {"ticket_workspace_policy": {"const": "current"}}, "required": ["ticket_workspace_policy"]},
+      "then": {"properties": {"integration_gate": {"const": "direct-parent"}}}
+    },
+    {
+      "if": {"properties": {"ticket_workspace_policy": {"const": "required"}}, "required": ["ticket_workspace_policy"]},
+      "then": {"properties": {"integration_gate": {"const": "candidate-merge"}}}
+    },
     {
       "if": {"properties": {"status": {"enum": ["draft", "blocked", "completed"]}}, "required": ["status"]},
       "then": {"properties": {"ready_for_execution": {"const": false}}}

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

@@ -1,11 +1,11 @@
 ---
 name: dev-worktree
-description: 管理 SpecDev Ticket 或原型的 Git worktree；为 Ticket 创建隔离来源 workspace、固定实现 commit，并由 Lead 在 parent-candidate checkout 验证后推进父分支。
+description: 管理 SpecDev required Ticket 或原型的 Git worktree；为 required Ticket 创建隔离来源 workspace、固定实现 commit，并由 Lead 在 parent-candidate checkout 验证后推进父分支。
 ---
 
 # Dev Worktree
 
-本 Skill 由 T-tickets/P-goal-plan/I-implement 和 P-prototype 复用。`purpose=ticket` 使用完整 source → candidate → parent 状态机；`purpose=prototype` 只使用调用方批准的临时生命周期。
+本 Skill 由 T-tickets/P-goal-plan/I-implement 和 P-prototype 复用。`purpose=ticket` 仅在 Goal Plan 选择 `required` 时使用完整 source → candidate → parent 状态机；`current` Ticket 不调用本 Skill。`purpose=prototype` 只使用调用方批准的临时生命周期。
 
 ## 输入
 
@@ -15,7 +15,7 @@ description: 管理 SpecDev Ticket 或原型的 Git worktree；为 Ticket 创建
 - workspace、implementation 和 integration owner；
 - 允许动作、路径合同、验证合同、调用方状态记录位置。
 
-Ticket 还必须提供 Ready Ticket、Goal Plan（若存在）、Evidence 路径、implementation commit 与本地 candidate integration/父分支更新授权。缺失时返回 blocked，不使用 current workspace 代替。
+required Ticket 还必须提供 Ready Ticket、Goal Plan（若存在）、Evidence 路径、implementation commit 与本地 candidate integration/父分支更新授权。缺失时返回 blocked；current Ticket 应按 I-implement 的 direct-parent 规则执行。
 
 ## 1. 创建或恢复
 

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

@@ -31,7 +31,7 @@
 - 项目要求的 typecheck/lint/build 或其他父状态检查；
 - 仅当 Ticket/Goal Plan `e2e.required=true` 时运行对应 E2E。
 
-每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。可由既有合同机械修正的失败最多处理三轮；不得放宽断言、删除检查或发明行为。
+每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`；父分支保持 `parent_before_sha`。机械修正次数不得超过 Goal Plan 快照的 `integration_attempt_limit`；不得放宽断言、删除检查或发明行为。
 
 ## 4. 推进父分支
 

package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md

@@ -15,15 +15,15 @@ description: 动态派单合同：为 Lead 生成受限的 implementation/review
 - `operation=dispatch`：提供 `task_kind=implementation | review | research | test-observation`、已存在 Goal Plan（若有）、Ticket/固定审查目标、依赖 Evidence、适用合同、repository、不可变 checkpoint、项目 Agent 指令、workspace/session locator、provider、允许动作、路径边界、检查、停止条件与返回格式；
 - `operation=accept`：提供原 Dispatch Packet、subagent 返回、当前 repository/workspace、预期与实际 checkpoint，以及 Lead 可用于独立核对的 Git/命令事实。
 
-`operation=dispatch` 且 `task_kind=implementation` 时，还必须提供独立 Ticket worktree、branch、`base_sha`、writable/shared owner、implementation commit 授权与 source-worktree 非 E2E 检查。缺失时返回 blocked，不推断权限或创建 current-workspace 写入者。
+`operation=dispatch` 且 `task_kind=implementation` 时，必须提供 Goal Plan 的 workspace strategy、branch、`base_sha`、writable/shared owner、implementation commit 授权与对应检查。`required` 必须提供独立 Ticket worktree 和 source-worktree 非 E2E 检查；`current` 必须提供 `workspace_ref=current`、parent branch 和 current-workspace 串行锁。缺失时返回 blocked，不推断策略或并发权限。
 
 ## 1. 固定 Lead 与任务类型
 
 Lead 保留需求解释、DAG/Wave/Gate、shared owner、权限、SpecDev 工件、Evidence、candidate-merge、父分支和最终回复。subagent 不写 Ticket、Map、Goal Plan、Evidence、change status 或父分支。
 
-- implementation 可以写唯一 Ticket worktree，并在授权时创建实现 commit；
+- implementation 可以在 required 模式写唯一 Ticket worktree，或在 current 模式按串行锁写当前 workspace，并在授权时创建实现 commit；
 - review/research/test-observation 只读，返回 findings、来源或命令观察；
-- E2E Gate 永远由 Lead 拥有，不能派给 implementation 或只读 agent；Ticket E2E 在 parent-candidate 状态执行，Direct Spec E2E 在 Lead-owned current workspace 执行。
+- E2E Gate 永远由 Lead 拥有，不能派给 implementation 或只读 agent；required Ticket E2E 在 parent-candidate 状态执行，current Ticket 和 Direct Spec E2E 在 Lead-owned current workspace 执行。
 
 **完成标准**：Lead、task kind、写入边界和 E2E owner 唯一。
 
@@ -44,7 +44,7 @@ Lead 保留需求解释、DAG/Wave/Gate、shared owner、权限、SpecDev 工件
 - 原生 Agent：加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/native-subagent.md</Path>`；
 - 外部网页 Agent：加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/external-web-subagent.md</Path>`。
 
-implementation Packet 必须适合一个上下文独立完成；多个 implementation subagent 由 Lead 控制在 Goal Plan/config 上限内且最多三个。只读 agent 不设置 SpecDev 数字上限，但不得争用可变环境。
+implementation Packet 必须适合一个上下文独立完成；required 模式多个 implementation subagent 由 Lead 控制在 Goal Plan、config 与平台能力共同上限内，current 模式保持单 writer 串行。只读 agent 不设置 SpecDev 数字上限，但不得争用可变环境。
 
 **完成标准**：Packet 可独立投递；目标、checkpoint、路径、权限、检查和返回均可判定。
 

package/template/workflows/specdev/common/skills/subagent-delivery/references/external-web-subagent.md

@@ -10,7 +10,7 @@
 
 Packet 固定目标、范围、合同、checkpoint、路径边界、非 E2E 验证要求和停止条件。外部 provider 返回 patch/文件、修改清单、推理摘要、模拟或自报测试、未验证项和会话 locator。
 
-Lead 在 Ticket worktree 中核对附件 hash、应用候选、检查 diff、依赖与锁文件、运行本地非 E2E 检查并创建 implementation commit。外部自报结果、截图或模拟保持 `unverified`；适用 E2E 仍只在 parent-candidate 状态运行。
+Lead 在 Goal Plan 指定的 current workspace 或 Ticket worktree 中核对附件 hash、应用候选、检查 diff、依赖与锁文件、运行本地非 E2E 检查并创建 implementation commit。外部自报结果、截图或模拟保持 `unverified`；适用 E2E 由 Lead 在 current workspace 或 parent-candidate 状态运行。
 
 ## 修正与恢复
 

package/template/workflows/specdev/common/skills/subagent-delivery/references/native-subagent.md

@@ -4,21 +4,21 @@ Lead 可以直接创建和管理隔离 Agent 时加载。
 
 ## 派单
 
-Lead 为每个 Agent 发送一个完整 Dispatch Packet。implementation Agent 只进入指定 Ticket worktree；review/research/test-observation Agent 只读取固定输入。并行前核对 Ticket 依赖与 writable/shared path，不以“不同 Agent”代替路径隔离。
+Lead 为每个 Agent 发送一个完整 Dispatch Packet。implementation Agent 只进入 Goal Plan 指定的 current workspace 或 Ticket worktree；review/research/test-observation Agent 只读取固定输入。并行前核对 Ticket 依赖与 writable/shared path，不以“不同 Agent”代替路径隔离。
 
 Packet 对 implementation 明确：
 
 - Ticket、Goal Plan、依赖 Evidence 与 `base_sha`；
 - branch、portable `workspace_ref`、writable/read-only/shared paths；
-- 允许 worktree local changes 与 implementation commit；
+- 允许当前策略下的 workspace changes 与 implementation commit；
 - 单元、组件、静态、类型、lint/build 等适用非 E2E 检查；
-- E2E 由 Lead 在 parent-candidate 状态执行；
+- E2E 由 Lead 在 current workspace 或 parent-candidate 状态执行；
 - 越界、合同冲突、基线漂移和无法提交时立即停止。
 
 ## 返回
 
 implementation Agent 返回 Ticket ID、workspace locator、最终 commit、`git status`、修改路径、命令/结果、未运行项、冲突和恢复条件，不写 SpecDev Evidence。只读 Agent 返回固定 checkpoint、findings、来源、命令观察和未验证项。
 
-Lead 重读 worktree、验证 commit 可达且 tip 一致、检查实际 diff 与路径合同，再决定接受、修正或 blocked。接受的 implementation 候选进入 dev-worktree candidate-merge；只读结论由 Lead 写入对应权威工件。
+Lead 重读 workspace、验证 commit 可达且 tip 一致、检查实际 diff 与路径合同，再决定接受、修正或 blocked。接受的 implementation 结果按 Goal Plan 进入 direct-parent 或 candidate-merge；只读结论由 Lead 写入对应权威工件。
 
 **完成标准**：原生 Agent 的写入与返回均绑定一个 Packet；Lead 可以独立复现其事实声明。

package/template/workflows/specdev/common/tools/README.md

@@ -5,10 +5,11 @@
 ```bash
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
   --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|review|prototype|wayfinder|complete> \
+  --repo <project-root> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```
 
-`--stage` 只要求该阶段已经拥有的工件；所有已经存在的工件仍会验证。省略 stage 时验证当前存在的工件，不会因未来 Work 尚未运行而报错。
+`--stage` 只要求该阶段已经拥有的工件；所有已经存在的工件仍会验证。省略 stage 时验证当前存在的工件，不会因未来 Work 尚未运行而报错。`--repo` 可选；提供后会把状态中的 SHA、祖先关系、当前分支和完成时 clean 状态与真实 Git 仓库交叉验证。
 
 ## 校验 SpecDev 工作流包