@namewta/speculo 0.7.1 → 0.7.3

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 (57) hide show
  1. package/README.md +2 -1
  2. package/dist/src/migrations.js +604 -23
  3. package/dist/src/migrations.js.map +1 -1
  4. package/package.json +1 -1
  5. package/template/canonical/canonical-specdev-engineering-cognitive-mentor.md +171 -277
  6. package/template/canonical/canonical-specdev-goal-plan.md +714 -833
  7. package/template/canonical/canonical-specdev-grill-with-docs.md +172 -278
  8. package/template/canonical/canonical-specdev-spec.md +199 -315
  9. package/template/canonical/canonical-specdev-tickets.md +405 -398
  10. package/template/canonical/canonical-specdev-wayfinder.md +170 -276
  11. package/template/skills/migrate-runtime-state/SKILL.md +6 -6
  12. package/template/skills/migrate-runtime-state/references/migration-contract.md +9 -3
  13. package/template/skills/migrate-runtime-state/scripts/migrate-runtime-state.mjs +322 -33
  14. package/template/skills/optimize-codex-config/SKILL.md +81 -0
  15. package/template/skills/optimize-codex-config/references/configuration-contract.md +103 -0
  16. package/template/skills/optimize-codex-config/references/troubleshooting.md +79 -0
  17. package/template/skills/optimize-codex-config/scripts/audit-codex-config.mjs +747 -0
  18. package/template/workflows/specdev/I-implement/I-implement.md +97 -142
  19. package/template/workflows/specdev/I-implement/evidence-template.md +60 -48
  20. package/template/workflows/specdev/I-implement/execution-preflight.md +29 -19
  21. package/template/workflows/specdev/I-implement/merge-conflict-protocol.md +12 -11
  22. package/template/workflows/specdev/I-init-setup/I-init-setup.md +4 -5
  23. package/template/workflows/specdev/I-init-setup/change-status-template.json +14 -1
  24. package/template/workflows/specdev/I-init-setup/config-template.json +3 -5
  25. package/template/workflows/specdev/I-init-setup/status-template.json +1 -1
  26. package/template/workflows/specdev/INDEX.md +12 -8
  27. package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +76 -93
  28. package/template/workflows/specdev/P-goal-plan/completion-control.md +26 -44
  29. package/template/workflows/specdev/P-goal-plan/goal-plan-template.md +43 -31
  30. package/template/workflows/specdev/P-goal-plan/lead-orchestration.md +34 -0
  31. package/template/workflows/specdev/P-goal-plan/orchestration-protocol.md +31 -42
  32. package/template/workflows/specdev/P-goal-plan/planning-modes.md +42 -61
  33. package/template/workflows/specdev/T-tickets/T-tickets.md +6 -3
  34. package/template/workflows/specdev/T-tickets/ticket-readiness.md +5 -3
  35. package/template/workflows/specdev/T-tickets/ticket-template.md +8 -1
  36. package/template/workflows/specdev/T-tickets/tickets-map-template.md +5 -4
  37. package/template/workflows/specdev/_state/status.json +1 -1
  38. package/template/workflows/specdev/common/README.md +2 -2
  39. package/template/workflows/specdev/common/rules/change-completion.md +17 -19
  40. package/template/workflows/specdev/common/rules/deviation-control.md +1 -1
  41. package/template/workflows/specdev/common/rules/evidence-and-verification.md +27 -37
  42. package/template/workflows/specdev/common/rules/path-ownership.md +21 -23
  43. package/template/workflows/specdev/common/rules/readiness-and-depth.md +1 -1
  44. package/template/workflows/specdev/common/schemas/change-status.schema.json +136 -195
  45. package/template/workflows/specdev/common/schemas/config.schema.json +9 -11
  46. package/template/workflows/specdev/common/schemas/goal-plan.schema.json +24 -6
  47. package/template/workflows/specdev/common/schemas/status.schema.json +7 -63
  48. package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md +42 -21
  49. package/template/workflows/specdev/common/skills/dev-worktree/references/create.md +48 -18
  50. package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md +47 -12
  51. package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +34 -30
  52. package/template/workflows/specdev/common/skills/subagent-delivery/references/external-web-subagent.md +10 -23
  53. package/template/workflows/specdev/common/skills/subagent-delivery/references/native-subagent.md +14 -25
  54. package/template/workflows/specdev/common/tools/validate-specdev.mjs +507 -117
  55. package/template/workflows/specdev/I-implement/delegated-evidence-template.md +0 -11
  56. package/template/workflows/specdev/P-goal-plan/delegated-execution-template.md +0 -33
  57. package/template/workflows/specdev/P-goal-plan/delegated-execution.md +0 -53
@@ -1,213 +1,154 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "urn:speculo:specdev:change-status:v3",
3
+ "$id": "urn:speculo:specdev:change-status:v5",
4
4
  "title": "SpecDev Change Status",
5
5
  "type": "object",
6
6
  "required": [
7
- "schema_version",
8
- "artifact",
9
- "change",
10
- "change_status",
11
- "current_work",
12
- "created_at",
13
- "updated_at",
14
- "completed_at",
15
- "archived",
16
- "archive_path",
17
- "blockers",
18
- "deviations"
7
+ "schema_version", "artifact", "change", "change_status", "current_work", "works_run",
8
+ "claimed_investigations", "execution_authorization", "leadership", "created_at", "updated_at",
9
+ "completed_at", "archived", "archive_path", "blockers", "deviations", "worktrees"
19
10
  ],
20
11
  "properties": {
21
- "schema_version": {
22
- "const": 3
23
- },
24
- "artifact": {
25
- "const": "change-status"
26
- },
27
- "change": {
28
- "type": "string",
29
- "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
30
- },
31
- "change_status": {
32
- "enum": [
33
- "active",
34
- "blocked",
35
- "completed",
36
- "archived"
37
- ]
38
- },
39
- "current_work": {
40
- "type": [
41
- "string",
42
- "null"
43
- ]
44
- },
45
- "created_at": {
46
- "type": "string",
47
- "minLength": 1
48
- },
49
- "updated_at": {
50
- "type": "string",
51
- "minLength": 1
12
+ "schema_version": {"const": 5},
13
+ "artifact": {"const": "change-status"},
14
+ "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
15
+ "change_status": {"enum": ["active", "blocked", "completed", "archived"]},
16
+ "current_work": {"type": ["string", "null"], "pattern": "^specdev/"},
17
+ "works_run": {"type": "array", "items": {"type": "string", "pattern": "^specdev/"}, "uniqueItems": true},
18
+ "claimed_investigations": {"type": "array", "items": {"$ref": "#/$defs/claim"}},
19
+ "execution_authorization": {"$ref": "#/$defs/authorization"},
20
+ "leadership": {"$ref": "#/$defs/leadership"},
21
+ "created_at": {"type": "string", "minLength": 1},
22
+ "updated_at": {"type": "string", "minLength": 1},
23
+ "completed_at": {"type": ["string", "null"]},
24
+ "archived": {"type": "boolean"},
25
+ "archive_path": {"anyOf": [{"type": "null"}, {"type": "string", "pattern": "^<Path>\\{roots\\.state\\}/specdev/archive/[^<]+</Path>$"}]},
26
+ "blockers": {"type": "array", "items": {"type": "string"}},
27
+ "deviations": {"type": "array", "items": {"type": "string"}},
28
+ "worktrees": {"type": "array", "items": {"$ref": "#/$defs/worktree"}}
29
+ },
30
+ "$defs": {
31
+ "claim": {
32
+ "type": "object",
33
+ "required": ["id", "owner", "session", "claimed_at"],
34
+ "properties": {
35
+ "id": {"type": "string", "minLength": 1},
36
+ "owner": {"type": "string", "minLength": 1},
37
+ "session": {"type": ["string", "null"]},
38
+ "claimed_at": {"type": "string", "minLength": 1}
39
+ },
40
+ "additionalProperties": false
52
41
  },
53
- "completed_at": {
54
- "type": [
55
- "string",
56
- "null"
57
- ]
42
+ "authorization-entry": {
43
+ "type": "object",
44
+ "required": ["status", "source", "granted_at", "scope"],
45
+ "properties": {
46
+ "status": {"enum": ["authorized", "not-authorized", "revoked"]},
47
+ "source": {"type": ["string", "null"]},
48
+ "granted_at": {"type": ["string", "null"]},
49
+ "scope": {"type": "string", "minLength": 1}
50
+ },
51
+ "allOf": [{
52
+ "if": {"properties": {"status": {"const": "authorized"}}, "required": ["status"]},
53
+ "then": {"properties": {"source": {"type": "string", "minLength": 1}, "granted_at": {"type": "string", "minLength": 1}}}
54
+ }],
55
+ "additionalProperties": false
58
56
  },
59
- "archived": {
60
- "type": "boolean"
57
+ "authorization": {
58
+ "type": "object",
59
+ "required": ["implementation_commit", "local_candidate_integration", "source_cleanup"],
60
+ "properties": {
61
+ "implementation_commit": {"$ref": "#/$defs/authorization-entry"},
62
+ "local_candidate_integration": {"$ref": "#/$defs/authorization-entry"},
63
+ "source_cleanup": {"$ref": "#/$defs/authorization-entry"}
64
+ },
65
+ "additionalProperties": false
61
66
  },
62
- "archive_path": {
63
- "anyOf": [
64
- {
65
- "type": "null"
66
- },
67
- {
68
- "type": "string",
69
- "pattern": "^<Path>\\{roots\\.state\\}/specdev/archive/[^<]+</Path>$"
70
- }
71
- ]
67
+ "leadership-history": {
68
+ "type": "object",
69
+ "required": ["owner", "epoch", "assigned_at", "ended_at"],
70
+ "properties": {
71
+ "owner": {"type": "string", "minLength": 1},
72
+ "epoch": {"type": "integer", "minimum": 1},
73
+ "assigned_at": {"type": "string", "minLength": 1},
74
+ "ended_at": {"type": "string", "minLength": 1}
75
+ },
76
+ "additionalProperties": false
72
77
  },
73
- "blockers": {
74
- "type": "array",
75
- "items": {
76
- "type": "string"
77
- }
78
+ "leadership": {
79
+ "type": "object",
80
+ "required": ["current", "epoch", "assigned_at", "history"],
81
+ "properties": {
82
+ "current": {"type": "string", "minLength": 1},
83
+ "epoch": {"type": "integer", "minimum": 1},
84
+ "assigned_at": {"type": "string", "minLength": 1},
85
+ "history": {"type": "array", "items": {"$ref": "#/$defs/leadership-history"}}
86
+ },
87
+ "additionalProperties": false
78
88
  },
79
- "deviations": {
80
- "type": "array",
81
- "items": {
82
- "type": "string"
83
- }
89
+ "full-suite": {
90
+ "type": "object",
91
+ "required": ["required", "status", "reason", "evidence"],
92
+ "properties": {
93
+ "required": {"type": "boolean"},
94
+ "status": {"enum": ["not-required", "pending", "passed", "failed"]},
95
+ "reason": {"type": ["string", "null"]},
96
+ "evidence": {"type": ["string", "null"]}
97
+ },
98
+ "allOf": [{
99
+ "if": {"properties": {"required": {"const": false}}, "required": ["required"]},
100
+ "then": {"properties": {"status": {"const": "not-required"}, "reason": {"type": "string", "minLength": 1}}}
101
+ }],
102
+ "additionalProperties": false
84
103
  },
85
- "worktrees": {
86
- "type": "array",
87
- "items": {
88
- "type": "object",
89
- "required": [
90
- "ticket_id",
91
- "owner",
92
- "provider",
93
- "base_sha",
94
- "branch",
95
- "workspace_ref",
96
- "status",
97
- "updated_at"
98
- ],
99
- "properties": {
100
- "ticket_id": {
101
- "type": "string",
102
- "pattern": "^T-[0-9]{2,}$"
103
- },
104
- "owner": {
105
- "type": "string",
106
- "minLength": 1
107
- },
108
- "provider": {
109
- "enum": [
110
- "native",
111
- "git",
112
- "external"
113
- ]
114
- },
115
- "base_sha": {
116
- "type": "string",
117
- "minLength": 1
118
- },
119
- "branch": {
120
- "type": "string",
121
- "minLength": 1
122
- },
123
- "workspace_ref": {
124
- "type": "string",
125
- "minLength": 1,
126
- "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
127
- },
128
- "status": {
129
- "enum": [
130
- "planned",
131
- "active",
132
- "review",
133
- "integrated",
134
- "removed",
135
- "blocked"
136
- ]
137
- },
138
- "updated_at": {
139
- "type": "string",
140
- "minLength": 1
141
- }
142
- },
143
- "additionalProperties": true
144
- }
145
- }
146
- },
147
- "allOf": [
148
- {
149
- "if": {
150
- "properties": {
151
- "worktrees": {
152
- "contains": {
153
- "properties": {
154
- "provider": {
155
- "const": "git"
156
- }
157
- },
158
- "required": [
159
- "provider"
160
- ]
161
- }
162
- }
163
- }
104
+ "worktree": {
105
+ "type": "object",
106
+ "required": ["ticket_id", "owner", "implementation_owner", "integration_owner", "provider", "base_sha", "parent_branch", "branch", "workspace_ref", "source_checkpoint", "integration", "status", "updated_at"],
107
+ "properties": {
108
+ "ticket_id": {"type": "string", "pattern": "^T-[0-9]{2,}$"},
109
+ "owner": {"type": "string", "minLength": 1},
110
+ "implementation_owner": {"type": "string", "minLength": 1},
111
+ "integration_owner": {"type": "string", "minLength": 1},
112
+ "provider": {"const": "git"},
113
+ "base_sha": {"type": "string", "minLength": 1},
114
+ "parent_branch": {"type": "string", "minLength": 1},
115
+ "branch": {"type": "string", "minLength": 1},
116
+ "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,}$"},
117
+ "source_checkpoint": {"type": ["string", "null"]},
118
+ "integration": {"$ref": "#/$defs/integration"},
119
+ "status": {"enum": ["planned", "active", "review", "integrating", "integrated", "removed", "blocked"]},
120
+ "updated_at": {"type": "string", "minLength": 1}
164
121
  },
165
- "then": {
166
- "properties": {
167
- "worktrees": {
168
- "items": {
169
- "if": {
170
- "properties": {
171
- "provider": {
172
- "const": "git"
173
- }
174
- },
175
- "required": [
176
- "provider"
177
- ]
178
- },
179
- "then": {
180
- "properties": {
181
- "workspace_ref": {
182
- "pattern": "^specdev-worktree/T-[0-9]{2,}$"
183
- }
184
- }
185
- }
186
- }
187
- }
188
- }
189
- }
122
+ "additionalProperties": false
190
123
  },
191
- {
192
- "if": {
193
- "properties": {
194
- "change_status": {
195
- "const": "archived"
196
- }
197
- }
124
+ "integration": {
125
+ "type": "object",
126
+ "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"],
127
+ "properties": {
128
+ "status": {"enum": ["pending", "candidate", "passed", "failed", "stale"]},
129
+ "parent_ref": {"type": ["string", "null"]},
130
+ "parent_before_sha": {"type": ["string", "null"]},
131
+ "source_sha": {"type": ["string", "null"]},
132
+ "candidate_sha": {"type": ["string", "null"]},
133
+ "candidate_tree_sha": {"type": ["string", "null"]},
134
+ "candidate_branch": {"type": ["string", "null"]},
135
+ "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,}$"}]},
136
+ "result_sha": {"type": ["string", "null"]},
137
+ "method": {"enum": [null, "fast-forward", "merge-commit"]},
138
+ "conflict_paths": {"type": "array", "items": {"type": "string"}},
139
+ "verification": {"enum": ["pending", "passed", "failed"]},
140
+ "full_suite": {"$ref": "#/$defs/full-suite"},
141
+ "e2e": {"$ref": "#/$defs/full-suite"},
142
+ "evidence": {"type": "string", "pattern": "^<Path>\\{roots\\.state\\}/specdev/changes/[^<]+/evidence/T-[0-9]{2,}\\.md</Path>$"},
143
+ "attempts": {"type": "integer", "minimum": 0},
144
+ "promotion_status": {"enum": ["pending", "applying", "applied", "failed", "stale"]}
198
145
  },
199
- "then": {
200
- "properties": {
201
- "archived": {
202
- "const": true
203
- },
204
- "archive_path": {
205
- "type": "string",
206
- "pattern": "^<Path>\\{roots\\.state\\}/specdev/archive/[^<]+</Path>$"
207
- }
208
- }
209
- }
146
+ "additionalProperties": false
210
147
  }
211
- ],
212
- "additionalProperties": true
148
+ },
149
+ "allOf": [{
150
+ "if": {"properties": {"change_status": {"const": "archived"}}, "required": ["change_status"]},
151
+ "then": {"properties": {"archived": {"const": true}, "archive_path": {"type": "string", "pattern": "^<Path>\\{roots\\.state\\}/specdev/archive/[^<]+</Path>$"}}}
152
+ }],
153
+ "additionalProperties": false
213
154
  }
@@ -1,32 +1,30 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "urn:speculo:specdev:config:v3",
3
+ "$id": "urn:speculo:specdev:config:v4",
4
4
  "title": "SpecDev Configuration",
5
5
  "type": "object",
6
6
  "required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
7
7
  "properties": {
8
- "schema_version": {"const": 3},
8
+ "schema_version": {"const": 4},
9
9
  "interaction_language": {"type": "string", "minLength": 1},
10
10
  "artifact_language": {"type": "string", "minLength": 1},
11
11
  "git": {
12
12
  "type": "object",
13
- "required": ["auto_commit", "default_branch", "worktree_for_parallel"],
13
+ "required": ["default_branch"],
14
14
  "properties": {
15
- "auto_commit": {"type": "boolean"},
16
- "default_branch": {"type": ["string", "null"]},
17
- "worktree_for_parallel": {"type": "boolean"}
15
+ "default_branch": {"type": ["string", "null"]}
18
16
  },
19
- "additionalProperties": true
17
+ "additionalProperties": false
20
18
  },
21
19
  "execution": {
22
20
  "type": "object",
23
- "required": ["max_parallel", "deep_ticket_human_approval", "shared_path_owner"],
21
+ "required": ["max_implementation_agents", "deep_ticket_human_approval", "shared_path_owner"],
24
22
  "properties": {
25
- "max_parallel": {"type": "integer", "minimum": 1},
23
+ "max_implementation_agents": {"type": "integer", "minimum": 1, "maximum": 3},
26
24
  "deep_ticket_human_approval": {"type": "boolean"},
27
25
  "shared_path_owner": {"type": "string", "minLength": 1}
28
26
  },
29
- "additionalProperties": true
27
+ "additionalProperties": false
30
28
  },
31
29
  "verification": {
32
30
  "type": "object",
@@ -50,5 +48,5 @@
50
48
  "additionalProperties": true
51
49
  }
52
50
  },
53
- "additionalProperties": true
51
+ "additionalProperties": false
54
52
  }
@@ -1,21 +1,39 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "urn:speculo:specdev:goal-plan:v3",
3
+ "$id": "urn:speculo:specdev:goal-plan:v5",
4
4
  "title": "SpecDev Goal Plan Frontmatter",
5
5
  "type": "object",
6
- "required": ["schema_version", "artifact", "change", "status", "modes", "ready_for_execution"],
6
+ "required": [
7
+ "schema_version", "artifact", "change", "status", "modes", "orchestration",
8
+ "lead", "implementation_agent_limit", "ticket_workspace_policy", "integration_gate",
9
+ "ready_for_execution"
10
+ ],
7
11
  "properties": {
8
- "schema_version": {"const": 3},
12
+ "schema_version": {"const": 5},
9
13
  "artifact": {"const": "goal-plan"},
10
14
  "change": {"type": "string", "minLength": 1},
11
15
  "status": {"enum": ["draft", "ready", "in_progress", "completed", "blocked"]},
12
16
  "modes": {
13
17
  "type": "array",
14
- "items": {"enum": ["coordination", "migration", "high-assurance", "reference-conformance", "release-coordination"]},
15
- "minItems": 1,
18
+ "items": {"enum": ["migration", "high-assurance", "reference-conformance", "release-coordination"]},
16
19
  "uniqueItems": true
17
20
  },
21
+ "orchestration": {"const": "lead-directed"},
22
+ "lead": {"type": "string", "minLength": 1},
23
+ "implementation_agent_limit": {"type": "integer", "minimum": 1, "maximum": 3},
24
+ "ticket_workspace_policy": {"const": "required"},
25
+ "integration_gate": {"const": "candidate-merge"},
18
26
  "ready_for_execution": {"type": "boolean"}
19
27
  },
20
- "additionalProperties": true
28
+ "allOf": [
29
+ {
30
+ "if": {"properties": {"status": {"enum": ["draft", "blocked", "completed"]}}, "required": ["status"]},
31
+ "then": {"properties": {"ready_for_execution": {"const": false}}}
32
+ },
33
+ {
34
+ "if": {"properties": {"status": {"enum": ["ready", "in_progress"]}}, "required": ["status"]},
35
+ "then": {"properties": {"ready_for_execution": {"const": true}}}
36
+ }
37
+ ],
38
+ "additionalProperties": false
21
39
  }
@@ -1,82 +1,26 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "urn:speculo:specdev:status:v4",
3
+ "$id": "urn:speculo:specdev:status:v5",
4
4
  "title": "SpecDev Global Status",
5
5
  "type": "object",
6
- "required": [
7
- "schema_version",
8
- "workflow",
9
- "active",
10
- "archived"
11
- ],
6
+ "required": ["schema_version", "workflow", "active", "archived"],
12
7
  "properties": {
13
- "schema_version": {
14
- "const": 4
15
- },
16
- "workflow": {
17
- "const": "specdev"
18
- },
8
+ "schema_version": {"const": 5},
9
+ "workflow": {"const": "specdev"},
19
10
  "active": {
20
11
  "type": "array",
21
12
  "items": {
22
13
  "type": "object",
23
- "required": [
24
- "change",
25
- "current_work",
26
- "works_run"
27
- ],
14
+ "required": ["change"],
28
15
  "properties": {
29
16
  "change": {
30
17
  "type": "string",
31
18
  "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
32
- },
33
- "current_work": {
34
- "type": [
35
- "string",
36
- "null"
37
- ],
38
- "pattern": "^specdev/"
39
- },
40
- "works_run": {
41
- "type": "array",
42
- "items": {
43
- "type": "string",
44
- "pattern": "^specdev/"
45
- },
46
- "uniqueItems": true
47
- },
48
- "claimed_investigations": {
49
- "type": "array",
50
- "items": {
51
- "type": "object",
52
- "required": [
53
- "id",
54
- "owner",
55
- "claimed_at"
56
- ],
57
- "properties": {
58
- "id": {
59
- "type": "string"
60
- },
61
- "owner": {
62
- "type": "string"
63
- },
64
- "session": {
65
- "type": [
66
- "string",
67
- "null"
68
- ]
69
- },
70
- "claimed_at": {
71
- "type": "string"
72
- }
73
- },
74
- "additionalProperties": false
75
- }
76
19
  }
77
20
  },
78
21
  "additionalProperties": false
79
- }
22
+ },
23
+ "uniqueItems": true
80
24
  },
81
25
  "archived": {
82
26
  "type": "array",
@@ -1,31 +1,52 @@
1
1
  ---
2
- name: specdev-dev-worktree
3
- description: 为需要隔离项目写入的 Ready Ticket 或一次性原型建立可恢复 worktree,并由调用方明确的 workspace owner 管理基线、集成或清理。
2
+ name: dev-worktree
3
+ description: 管理 SpecDev Ticket 或原型的 Git worktree;为 Ticket 创建隔离来源 workspace、固定实现 commit,并由 Lead 在 parent-candidate checkout 验证后推进父分支。
4
4
  ---
5
5
 
6
- # SpecDev Dev Worktree
6
+ # Dev Worktree
7
7
 
8
- ## 适用范围
8
+ Skill 由 T-tickets/P-goal-plan/I-implement 和 P-prototype 复用。`purpose=ticket` 使用完整 source → candidate → parent 状态机;`purpose=prototype` 只使用调用方批准的临时生命周期。
9
9
 
10
- - 用于并行写代码且路径所有权不冲突的 Ready Ticket,或明确要求临时隔离的一次性原型。
11
- - 只读调查和顺序执行默认共用当前工作区。
12
- - 调用方必须明确 workspace owner、implementation owner、固定基线、工作项 ID、持久化 owner 和允许的结束动作。
13
- - 普通执行不建立额外角色;委派 Goal Plan 才把 workspace owner/implementation owner 分别映射为 Lead/Worker。
14
- - 平台原生 worktree 优先;不可用时使用 Git worktree。
10
+ ## 输入
15
11
 
16
- ## 生命周期
12
+ - `operation=create | restore | finalize | remove`;
13
+ - `purpose=ticket | prototype`;
14
+ - repository、父分支、`base_sha`、branch、portable workspace locator;
15
+ - workspace、implementation 和 integration owner;
16
+ - 允许动作、路径合同、验证合同、调用方状态记录位置。
17
17
 
18
- 1. 创建或恢复时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/create.md</Path>`。
19
- 2. implementation owner 完成后返回工作项状态、Evidence/record 路径、`workspace_ref`、checkpoint、commit 或 PR 引用和未验证项;Ticket worktree 从 `active` 更新为 `review`。
20
- 3. workspace owner 集成或清理时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/finalize.md</Path>`;一次性原型只评估和清理,不合入生产分支。
18
+ Ticket 还必须提供 Ready Ticket、Goal Plan(若存在)、Evidence 路径、implementation commit 与本地 candidate integration/父分支更新授权。缺失时返回 blocked,不使用 current workspace 代替。
21
19
 
22
- Ticket worktree 状态依次为 `planned → active → review → integrated → removed`;失败进入 `blocked`,记录写入 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees`。原型的 branch、`workspace_ref` 和清理结果只写入 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>`,不伪造 Ticket worktree 记录。
20
+ ## 1. 创建或恢复
23
21
 
24
- ## 边界
22
+ `operation=create` 时加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/create.md</Path>`。Ticket 使用 `specdev-worktree/<ticket-id>`;同一 Ticket 只存在一个来源 worktree。`operation=restore` 时重读实际 Git worktree/branch/tip/dirty 状态并与调用方记录核对,漂移时停止。
25
23
 
26
- - 每个并行 Ticket 使用独立 worktree、分支和相同 `base_sha`;每个原型使用独立 worktree 和分支。
27
- - Git provider 固定使用 `<project-root>/specdev-worktree/<work-item-id>/`,持久化 `workspace_ref: specdev-worktree/<work-item-id>`;`<project-root>` 由 `workspace.json#path_base: project-root` 解析。
28
- - native/external provider 保留其可迁移 opaque locator;所有 provider 都不保存机器绝对路径、认证秘密或真实用户数据。
29
- - 项目根 `.gitignore` 的 `specdev-worktree/` 条目由 `speculo init` 单一维护;缺失时创建流程阻塞并提示重新运行 init。
30
- - E2E 仅适用于用户界面交互受影响的变更。普通执行由当前集成 owner 运行;委派执行由 Lead 在集成阶段运行。
31
- - 合并、推送、PR、删除分支或 worktree 仍需用户授权。
24
+ **完成标准**:来源基线、branch、locator、owners 和实际 Git 状态一致;现有用户改动未被覆盖。
25
+
26
+ ## 2. 来源实现门
27
+
28
+ implementation owner 只在来源 worktree 修改授权项目路径,运行 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查。进入 `review` 前,worktree 必须 clean,branch tip 必须是已授权的 `source_checkpoint` commit,实际 diff 必须符合路径合同。
29
+
30
+ **完成标准**:source checkpoint 不可变且可达;来源 worktree 没有 E2E pass 声明。
31
+
32
+ ## 3. 候选合并与父分支推进
33
+
34
+ `operation=finalize` 仅由 Lead/integration owner 调用,并加载 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/finalize.md</Path>`。Lead 在独立 parent-candidate checkout 组合最新父分支与 source checkpoint,运行集成检查和适用 E2E,通过后才推进父分支。
35
+
36
+ 本地 candidate checkout/branch 的创建、重建和回收属于已授权 local candidate integration;来源 branch/worktree 的删除仍需要独立 cleanup 授权。push、PR、remote merge、deploy、migration 和生产动作不从本 Skill 继承。
37
+
38
+ **完成标准**:Ticket `integrated` 时父 HEAD 精确等于记录的 result SHA,并包含 source checkpoint;失败或 stale 时父分支未变化。后续 `removed` 只表示来源 branch/worktree 已清理,不撤销该集成事实。
39
+
40
+ ## 4. 移除
41
+
42
+ `operation=remove` 先验证 Ticket 已 `integrated` 或 prototype 已结束、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree;强制删除需要单独确认。删除后重读 `git worktree list` 与 refs,并只把调用方生命周期状态更新为 `removed`;`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
43
+
44
+ **完成标准**:只删除精确授权目标;失败保留现场与恢复命令。
45
+
46
+ ## 固定规则
47
+
48
+ - Agent Team 不决定 worktree;Ticket 切片本身决定来源 worktree;
49
+ - Ticket E2E 只在 Lead-owned parent-candidate checkout 运行;
50
+ - 每个 Done Ticket 必须有 source commit 与父分支 result,worktree 状态为 `integrated` 或其清理后终态 `removed`;
51
+ - candidate 失败保留来源 worktree 修正,父分支不动;
52
+ - 成功集成不自动清理来源 branch/worktree。