@jeancodogno/specforce-kit 0.1.0

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 (153) hide show
  1. package/.geminiignore +15 -0
  2. package/.github/workflows/ci.yml +100 -0
  3. package/.github/workflows/release.yml +51 -0
  4. package/.golangci.yml +21 -0
  5. package/.goreleaser.yaml +43 -0
  6. package/.rgignore +13 -0
  7. package/.specforce/config.yaml +32 -0
  8. package/.specforce/docs/.gitkeep +0 -0
  9. package/.specforce/docs/architecture.md +98 -0
  10. package/.specforce/docs/engineering.md +80 -0
  11. package/.specforce/docs/governance.md +30 -0
  12. package/.specforce/docs/memorial.md +44 -0
  13. package/.specforce/docs/principles.md +31 -0
  14. package/.specforce/docs/security.md +31 -0
  15. package/.specforce/docs/ui-ux.md +129 -0
  16. package/.specforce/specs/.gitkeep +0 -0
  17. package/AGENTS.md +36 -0
  18. package/CONTRIBUTING.md +81 -0
  19. package/LICENSE +21 -0
  20. package/Makefile +49 -0
  21. package/README.md +144 -0
  22. package/assets/logo-header.png +0 -0
  23. package/assets/logo.png +0 -0
  24. package/docs/artifacts.md +41 -0
  25. package/docs/cli.md +73 -0
  26. package/docs/configuration.md +50 -0
  27. package/docs/getting-started.md +110 -0
  28. package/docs/supported-tools.md +14 -0
  29. package/go.mod +35 -0
  30. package/go.sum +61 -0
  31. package/index.js +0 -0
  32. package/package.json +26 -0
  33. package/src/cmd/specforce/main.go +23 -0
  34. package/src/cmd/specforce/main_test.go +7 -0
  35. package/src/internal/agent/artifacts/constitution/architecture.yaml +70 -0
  36. package/src/internal/agent/artifacts/constitution/engineering.yaml +52 -0
  37. package/src/internal/agent/artifacts/constitution/governance.yaml +41 -0
  38. package/src/internal/agent/artifacts/constitution/memorial.yaml +55 -0
  39. package/src/internal/agent/artifacts/constitution/principles.yaml +54 -0
  40. package/src/internal/agent/artifacts/constitution/security.yaml +47 -0
  41. package/src/internal/agent/artifacts/constitution/ui-ux.yaml +158 -0
  42. package/src/internal/agent/artifacts/spec/design.yaml +50 -0
  43. package/src/internal/agent/artifacts/spec/requirements.yaml +48 -0
  44. package/src/internal/agent/artifacts/spec/tasks.yaml +55 -0
  45. package/src/internal/agent/compatibility_test.go +120 -0
  46. package/src/internal/agent/cwd_test.go +9 -0
  47. package/src/internal/agent/embed.go +19 -0
  48. package/src/internal/agent/integration_test.go +138 -0
  49. package/src/internal/agent/kit/agents/product-analyst.yaml +31 -0
  50. package/src/internal/agent/kit/agents/technical-developer.yaml +28 -0
  51. package/src/internal/agent/kit/agents/technical-project-planner.yaml +30 -0
  52. package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +36 -0
  53. package/src/internal/agent/kit/agents/technical-solution-architect.yaml +32 -0
  54. package/src/internal/agent/kit/commands/archive.yaml +25 -0
  55. package/src/internal/agent/kit/commands/constitution.yaml +132 -0
  56. package/src/internal/agent/kit/commands/implement.yaml +96 -0
  57. package/src/internal/agent/kit/commands/spec.yaml +94 -0
  58. package/src/internal/agent/kit/instructions/archive.md +68 -0
  59. package/src/internal/agent/kit/kit.yaml +111 -0
  60. package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +56 -0
  61. package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +58 -0
  62. package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +38 -0
  63. package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +52 -0
  64. package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +137 -0
  65. package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +103 -0
  66. package/src/internal/agent/kit_manifests_test.go +58 -0
  67. package/src/internal/agent/manifest.go +15 -0
  68. package/src/internal/agent/registry.go +69 -0
  69. package/src/internal/agent/registry_test.go +51 -0
  70. package/src/internal/agent/translator.go +334 -0
  71. package/src/internal/agent/translator_test.go +734 -0
  72. package/src/internal/cli/archive.go +91 -0
  73. package/src/internal/cli/archive_test.go +67 -0
  74. package/src/internal/cli/cli.go +259 -0
  75. package/src/internal/cli/cli_test.go +130 -0
  76. package/src/internal/cli/cobra/archive.go +26 -0
  77. package/src/internal/cli/cobra/console.go +21 -0
  78. package/src/internal/cli/cobra/constitution.go +44 -0
  79. package/src/internal/cli/cobra/dummy_test.go +7 -0
  80. package/src/internal/cli/cobra/implementation.go +50 -0
  81. package/src/internal/cli/cobra/init.go +23 -0
  82. package/src/internal/cli/cobra/install.go +21 -0
  83. package/src/internal/cli/cobra/root.go +47 -0
  84. package/src/internal/cli/cobra/spec.go +91 -0
  85. package/src/internal/cli/console.go +48 -0
  86. package/src/internal/cli/constitution.go +190 -0
  87. package/src/internal/cli/constitution_test.go +50 -0
  88. package/src/internal/cli/implementation.go +153 -0
  89. package/src/internal/cli/implementation_test.go +165 -0
  90. package/src/internal/cli/spec.go +369 -0
  91. package/src/internal/cli/spec_test.go +85 -0
  92. package/src/internal/constitution/registry.go +139 -0
  93. package/src/internal/constitution/registry_test.go +97 -0
  94. package/src/internal/constitution/status.go +70 -0
  95. package/src/internal/constitution/status_test.go +160 -0
  96. package/src/internal/core/blueprint.go +49 -0
  97. package/src/internal/core/blueprint_test.go +58 -0
  98. package/src/internal/core/config.go +124 -0
  99. package/src/internal/core/config_test.go +145 -0
  100. package/src/internal/core/constants.go +13 -0
  101. package/src/internal/core/errors.go +31 -0
  102. package/src/internal/core/errors_test.go +48 -0
  103. package/src/internal/core/hooks.go +89 -0
  104. package/src/internal/core/hooks_test.go +51 -0
  105. package/src/internal/core/kit.go +15 -0
  106. package/src/internal/core/kit_test.go +65 -0
  107. package/src/internal/core/path.go +115 -0
  108. package/src/internal/core/path_test.go +101 -0
  109. package/src/internal/core/ui.go +19 -0
  110. package/src/internal/installer/dependencies.go +23 -0
  111. package/src/internal/installer/install.go +89 -0
  112. package/src/internal/installer/installer.go +45 -0
  113. package/src/internal/installer/installer_test.go +96 -0
  114. package/src/internal/project/agents_md.go +108 -0
  115. package/src/internal/project/agents_md_test.go +101 -0
  116. package/src/internal/project/bootstrapper.go +64 -0
  117. package/src/internal/project/bootstrapper_test.go +89 -0
  118. package/src/internal/project/detector.go +35 -0
  119. package/src/internal/project/detector_test.go +96 -0
  120. package/src/internal/project/refresh_integration_test.go +86 -0
  121. package/src/internal/project/service.go +93 -0
  122. package/src/internal/project/service_test.go +135 -0
  123. package/src/internal/spec/archive.go +49 -0
  124. package/src/internal/spec/archive_test.go +55 -0
  125. package/src/internal/spec/discovery.go +53 -0
  126. package/src/internal/spec/discovery_test.go +60 -0
  127. package/src/internal/spec/implementation.go +296 -0
  128. package/src/internal/spec/implementation_test.go +253 -0
  129. package/src/internal/spec/registry.go +142 -0
  130. package/src/internal/spec/registry_test.go +105 -0
  131. package/src/internal/spec/scanner.go +219 -0
  132. package/src/internal/spec/scanner_test.go +243 -0
  133. package/src/internal/spec/service.go +157 -0
  134. package/src/internal/spec/service_test.go +238 -0
  135. package/src/internal/spec/status.go +94 -0
  136. package/src/internal/spec/status_test.go +146 -0
  137. package/src/internal/spec/tasks.go +103 -0
  138. package/src/internal/spec/tasks_test.go +137 -0
  139. package/src/internal/tui/components.go +132 -0
  140. package/src/internal/tui/console.go +247 -0
  141. package/src/internal/tui/console_test.go +19 -0
  142. package/src/internal/tui/constitution.go +36 -0
  143. package/src/internal/tui/constitution_test.go +32 -0
  144. package/src/internal/tui/implementation.go +151 -0
  145. package/src/internal/tui/logo.go +89 -0
  146. package/src/internal/tui/multiselect.go +199 -0
  147. package/src/internal/tui/progressbar.go +37 -0
  148. package/src/internal/tui/progressbar_test.go +30 -0
  149. package/src/internal/tui/spec.go +35 -0
  150. package/src/internal/tui/spinner.go +66 -0
  151. package/src/internal/tui/terminal.go +18 -0
  152. package/src/internal/tui/theme.go +125 -0
  153. package/src/internal/tui/ui.go +52 -0
@@ -0,0 +1,296 @@
1
+ package spec
2
+
3
+ import (
4
+ "context"
5
+ "errors"
6
+ "fmt"
7
+ "os"
8
+ "path/filepath"
9
+ "regexp"
10
+ "strings"
11
+
12
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
13
+ )
14
+
15
+ type ImplementationTask struct {
16
+ ID string `json:"id"`
17
+ Title string `json:"title"`
18
+ State string `json:"state"`
19
+ Target string `json:"target"`
20
+ Context string `json:"context"`
21
+ ActionSteps []string `json:"action_steps"`
22
+ Verification string `json:"verification"`
23
+ }
24
+
25
+ type Phase struct {
26
+ ID string `json:"id"`
27
+ Title string `json:"title"`
28
+ Tasks []ImplementationTask `json:"tasks"`
29
+ }
30
+
31
+ type ImplementationReport struct {
32
+ Name string `json:"name"`
33
+ Status string `json:"status"` // ready | blocked
34
+ MissingArtifacts []string `json:"missing_artifacts,omitempty"`
35
+ ContextFiles []string `json:"context_files"`
36
+ Instructions []string `json:"instructions,omitempty"`
37
+ Phases []Phase `json:"phases"`
38
+ ExecutionStrategy string `json:"execution_strategy"`
39
+ PreemptiveMitigations string `json:"preemptive_mitigations"`
40
+ }
41
+
42
+ // Tasks returns a flat list of tasks across all phases for backward compatibility.
43
+ func (r *ImplementationReport) Tasks() []ImplementationTask {
44
+ var tasks []ImplementationTask
45
+ for _, p := range r.Phases {
46
+ tasks = append(tasks, p.Tasks...)
47
+ }
48
+ return tasks
49
+ }
50
+
51
+ // FindProjectRoot looks for the .specforce directory in the current or parent directories.
52
+ func FindProjectRoot() (string, error) {
53
+ cwd, err := os.Getwd()
54
+ if err != nil {
55
+ return "", err
56
+ }
57
+
58
+ current := cwd
59
+ for {
60
+ if _, err := os.Stat(filepath.Join(current, ".specforce")); err == nil {
61
+ return current, nil
62
+ }
63
+
64
+ parent := filepath.Dir(current)
65
+ if parent == current {
66
+ break
67
+ }
68
+ current = parent
69
+ }
70
+
71
+ return "", fmt.Errorf(".specforce directory not found")
72
+ }
73
+
74
+ // CheckTriadArtifacts verifies if requirements.md, design.md, and tasks.md exist.
75
+ func CheckTriadArtifacts(projectRoot, slug string) (bool, []string) {
76
+ required := []string{"requirements.md", "design.md", "tasks.md"}
77
+ missing := []string{}
78
+
79
+ specDir := filepath.Join(projectRoot, ".specforce", "specs", slug)
80
+
81
+ for _, art := range required {
82
+ if _, err := os.Stat(filepath.Join(specDir, art)); os.IsNotExist(err) {
83
+ missing = append(missing, art)
84
+ }
85
+ }
86
+
87
+ return len(missing) == 0, missing
88
+ }
89
+
90
+ // GetContextFiles returns absolute paths for all files in the spec directory and global docs.
91
+ func GetContextFiles(projectRoot, slug string) ([]string, error) {
92
+ files := []string{}
93
+
94
+ specDir := filepath.Join(projectRoot, ".specforce", "specs", slug)
95
+
96
+ // Helper to add files from a directory
97
+ addFiles := func(dir string) error {
98
+ if _, err := os.Stat(dir); os.IsNotExist(err) {
99
+ return nil
100
+ }
101
+
102
+ return filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
103
+ if err != nil {
104
+ return err
105
+ }
106
+ if !info.IsDir() {
107
+ abs, err := filepath.Abs(path)
108
+ if err != nil {
109
+ return err
110
+ }
111
+ files = append(files, abs)
112
+ }
113
+ return nil
114
+ })
115
+ }
116
+
117
+ if err := addFiles(specDir); err != nil {
118
+ return nil, err
119
+ }
120
+
121
+ return files, nil
122
+ }
123
+
124
+ // ParseTasks extracts implementation details from tasks.md.
125
+ func ParseTasks(ctx context.Context, projectRoot, slug string) (*ImplementationReport, error) {
126
+ if err := ctx.Err(); err != nil {
127
+ return nil, err
128
+ }
129
+
130
+ tasksPath, err := core.SecurePath(projectRoot, filepath.Join(".specforce", "specs", slug, "tasks.md"))
131
+ if err != nil {
132
+ return nil, fmt.Errorf("security: %w", err)
133
+ }
134
+ // #nosec G304 - Path is secured by SecurePath
135
+ content, err := os.ReadFile(tasksPath)
136
+ if err != nil {
137
+ return nil, fmt.Errorf("failed to read spec file %s: %w", tasksPath, errors.Join(core.ErrInvalidSpecFile, err))
138
+ }
139
+
140
+ report := &ImplementationReport{
141
+ Name: slug,
142
+ Phases: []Phase{},
143
+ }
144
+
145
+ extractStrategyAndMitigations(content, report)
146
+
147
+ if err := extractTasksFromContent(ctx, content, report); err != nil {
148
+ return nil, err
149
+ }
150
+
151
+ report.Status = calculateReportStatus(report.Tasks())
152
+
153
+ return report, nil
154
+ }
155
+
156
+ func extractStrategyAndMitigations(content []byte, report *ImplementationReport) {
157
+ strategyRegex := regexp.MustCompile(`(?s)## 1\. Execution Strategy\n(.*?)(?:\n##|$)`)
158
+ strategyMatch := strategyRegex.FindSubmatch(content)
159
+ if len(strategyMatch) > 1 {
160
+ report.ExecutionStrategy = strings.TrimSpace(string(strategyMatch[1]))
161
+ }
162
+
163
+ mitigationsRegex := regexp.MustCompile(`(?s)## 3\. Pre-emptive Mitigations\n(.*?)(?:\n##|$)`)
164
+ mitigationsMatch := mitigationsRegex.FindSubmatch(content)
165
+ if len(mitigationsMatch) > 1 {
166
+ report.PreemptiveMitigations = strings.TrimSpace(string(mitigationsMatch[1]))
167
+ }
168
+ }
169
+
170
+ func extractTasksFromContent(ctx context.Context, content []byte, report *ImplementationReport) error {
171
+ phaseHeaderRegex := regexp.MustCompile(`(?m)^### Phase (\d+): (.*)$`)
172
+ taskHeaderRegex := regexp.MustCompile(`(?m)^#{3,4} (T[\d.]+): (.*)$`)
173
+
174
+ phaseMatches := phaseHeaderRegex.FindAllSubmatchIndex(content, -1)
175
+ taskMatches := taskHeaderRegex.FindAllSubmatchIndex(content, -1)
176
+
177
+ for _, tm := range taskMatches {
178
+ if err := ctx.Err(); err != nil {
179
+ return err
180
+ }
181
+
182
+ task := parseTaskBlock(content, tm, taskMatches, phaseMatches)
183
+
184
+ // Find or create phase
185
+ currentPhaseIdx := findPhaseIdxForTask(content, tm[0], phaseMatches, report)
186
+ report.Phases[currentPhaseIdx].Tasks = append(report.Phases[currentPhaseIdx].Tasks, task)
187
+ }
188
+
189
+ return nil
190
+ }
191
+
192
+ func parseTaskBlock(content []byte, tm []int, taskMatches, phaseMatches [][]int) ImplementationTask {
193
+ task := ImplementationTask{
194
+ ID: string(content[tm[2]:tm[3]]),
195
+ Title: strings.TrimSpace(string(content[tm[4]:tm[5]])),
196
+ }
197
+
198
+ // Find the absolute next header (could be Phase or Task or ##)
199
+ nextHeaderPos := len(content)
200
+ for _, nextTm := range taskMatches {
201
+ if nextTm[0] > tm[0] && nextTm[0] < nextHeaderPos {
202
+ nextHeaderPos = nextTm[0]
203
+ break
204
+ }
205
+ }
206
+ for _, pm := range phaseMatches {
207
+ if pm[0] > tm[0] && pm[0] < nextHeaderPos {
208
+ nextHeaderPos = pm[0]
209
+ break
210
+ }
211
+ }
212
+ nextSectionRegex := regexp.MustCompile(`(?m)^## `)
213
+ sectionMatch := nextSectionRegex.FindIndex(content[tm[1]:])
214
+ if sectionMatch != nil {
215
+ absSectionPos := tm[1] + sectionMatch[0]
216
+ if absSectionPos < nextHeaderPos {
217
+ nextHeaderPos = absSectionPos
218
+ }
219
+ }
220
+
221
+ taskBlock := content[tm[0]:nextHeaderPos]
222
+ task.State = extractField(taskBlock, `\*\*State:\*\* \x60?\[([^\]\x60\n]*)\]\x60?`)
223
+ task.Target = extractField(taskBlock, `\*\*Target:\*\* \x60?([^\x60\n]*)\x60?`)
224
+ task.Context = extractField(taskBlock, `\*\*Context:\*\* \x60?([^\x60\n]*)\x60?`)
225
+ task.Verification = extractField(taskBlock, `(?s)\*\*Verification \(TDD\):\*\*\n(.*?)(?:\n\n|\n###|\n##|$)`)
226
+
227
+ actionStepsRegex := regexp.MustCompile(`(?m)^- (.*)$`)
228
+ actionMatches := actionStepsRegex.FindAllSubmatch(taskBlock, -1)
229
+ for _, am := range actionMatches {
230
+ task.ActionSteps = append(task.ActionSteps, string(am[1]))
231
+ }
232
+
233
+ return task
234
+ }
235
+
236
+ func findPhaseIdxForTask(content []byte, taskStart int, phaseMatches [][]int, report *ImplementationReport) int {
237
+ matchIdx := -1
238
+ for i := len(phaseMatches) - 1; i >= 0; i-- {
239
+ if phaseMatches[i][0] < taskStart {
240
+ matchIdx = i
241
+ break
242
+ }
243
+ }
244
+
245
+ if matchIdx == -1 {
246
+ if len(report.Phases) == 0 || report.Phases[0].ID != "0" {
247
+ report.Phases = append([]Phase{{ID: "0", Title: "Initial Tasks", Tasks: []ImplementationTask{}}}, report.Phases...)
248
+ }
249
+ return 0
250
+ }
251
+
252
+ phaseID := string(content[phaseMatches[matchIdx][2]:phaseMatches[matchIdx][3]])
253
+ phaseTitle := strings.TrimSpace(string(content[phaseMatches[matchIdx][4]:phaseMatches[matchIdx][5]]))
254
+
255
+ for idx, p := range report.Phases {
256
+ if p.ID == phaseID && p.Title == phaseTitle {
257
+ return idx
258
+ }
259
+ }
260
+
261
+ report.Phases = append(report.Phases, Phase{ID: phaseID, Title: phaseTitle, Tasks: []ImplementationTask{}})
262
+ return len(report.Phases) - 1
263
+ }
264
+
265
+ func calculateReportStatus(tasks []ImplementationTask) string {
266
+ if len(tasks) == 0 {
267
+ return "ready"
268
+ }
269
+ allFinished := true
270
+ allPending := true
271
+ for _, t := range tasks {
272
+ st := strings.ToUpper(t.State)
273
+ if st != "FINISHED" {
274
+ allFinished = false
275
+ }
276
+ if st != "PENDING" && st != "" {
277
+ allPending = false
278
+ }
279
+ }
280
+
281
+ if allFinished {
282
+ return "finished"
283
+ } else if !allPending {
284
+ return "in-progress"
285
+ }
286
+ return "ready"
287
+ }
288
+
289
+ func extractField(block []byte, pattern string) string {
290
+ re := regexp.MustCompile(pattern)
291
+ match := re.FindSubmatch(block)
292
+ if len(match) > 1 {
293
+ return strings.TrimSpace(string(match[1]))
294
+ }
295
+ return ""
296
+ }
@@ -0,0 +1,253 @@
1
+ package spec
2
+
3
+ import (
4
+ "context"
5
+ "os"
6
+ "path/filepath"
7
+ "testing"
8
+ )
9
+
10
+ func TestCheckTriadArtifacts(t *testing.T) {
11
+ tmpDir, err := os.MkdirTemp("", "specforce-test-*")
12
+ if err != nil {
13
+ t.Fatal(err)
14
+ }
15
+ defer func() { _ = os.RemoveAll(tmpDir) }()
16
+
17
+ slug := "test-feature"
18
+ specDir := filepath.Join(tmpDir, ".specforce", "specs", slug)
19
+ err = os.MkdirAll(specDir, 0755)
20
+ if err != nil {
21
+ t.Fatal(err)
22
+ }
23
+
24
+ // Case 1: All missing
25
+ ok, missing := CheckTriadArtifacts(tmpDir, slug)
26
+ if ok {
27
+ t.Error("Expected false, got true")
28
+ }
29
+ if len(missing) != 3 {
30
+ t.Errorf("Expected 3 missing, got %d", len(missing))
31
+ }
32
+
33
+ // Case 2: Some missing
34
+ if err := os.WriteFile(filepath.Join(specDir, "requirements.md"), []byte("test"), 0644); err != nil {
35
+ t.Fatal(err)
36
+ }
37
+ ok, missing = CheckTriadArtifacts(tmpDir, slug)
38
+ if ok {
39
+ t.Error("Expected false, got true")
40
+ }
41
+ if len(missing) != 2 {
42
+ t.Errorf("Expected 2 missing, got %d", len(missing))
43
+ }
44
+
45
+ // Case 3: None missing
46
+ if err := os.WriteFile(filepath.Join(specDir, "design.md"), []byte("test"), 0644); err != nil {
47
+ t.Fatal(err)
48
+ }
49
+ if err := os.WriteFile(filepath.Join(specDir, "tasks.md"), []byte("test"), 0644); err != nil {
50
+ t.Fatal(err)
51
+ }
52
+ ok, missing = CheckTriadArtifacts(tmpDir, slug)
53
+ if !ok {
54
+ t.Error("Expected true, got false")
55
+ }
56
+ if len(missing) != 0 {
57
+ t.Errorf("Expected 0 missing, got %d", len(missing))
58
+ }
59
+ }
60
+
61
+ func TestGetContextFiles(t *testing.T) {
62
+ tmpDir, err := os.MkdirTemp("", "specforce-test-*")
63
+ if err != nil {
64
+ t.Fatal(err)
65
+ }
66
+ defer func() { _ = os.RemoveAll(tmpDir) }()
67
+
68
+ slug := "test-feature"
69
+ specDir := filepath.Join(tmpDir, ".specforce", "specs", slug)
70
+ docsDir := filepath.Join(tmpDir, ".specforce", "docs")
71
+ err = os.MkdirAll(specDir, 0755)
72
+ if err != nil {
73
+ t.Fatal(err)
74
+ }
75
+ err = os.MkdirAll(docsDir, 0755)
76
+ if err != nil {
77
+ t.Fatal(err)
78
+ }
79
+
80
+ if err := os.WriteFile(filepath.Join(specDir, "tasks.md"), []byte("test"), 0644); err != nil {
81
+ t.Fatal(err)
82
+ }
83
+ if err := os.WriteFile(filepath.Join(docsDir, "architecture.md"), []byte("test"), 0644); err != nil {
84
+ t.Fatal(err)
85
+ }
86
+
87
+ files, err := GetContextFiles(tmpDir, slug)
88
+ if err != nil {
89
+ t.Fatalf("Unexpected error: %v", err)
90
+ }
91
+
92
+ if len(files) != 1 {
93
+ t.Errorf("Expected 1 file (from spec dir), got %d. Global docs from .specforce/docs should be excluded.", len(files))
94
+ }
95
+
96
+ for _, f := range files {
97
+ if !filepath.IsAbs(f) {
98
+ t.Errorf("Expected absolute path, got %s", f)
99
+ }
100
+ }
101
+ }
102
+
103
+ func setupTasksFile(t *testing.T, tmpDir, slug, content string) {
104
+ specDir := filepath.Join(tmpDir, ".specforce", "specs", slug)
105
+ err := os.MkdirAll(specDir, 0755)
106
+ if err != nil {
107
+ t.Fatal(err)
108
+ }
109
+
110
+ if err := os.WriteFile(filepath.Join(specDir, "tasks.md"), []byte(content), 0644); err != nil {
111
+ t.Fatal(err)
112
+ }
113
+ }
114
+
115
+ func getSampleTasksMD() string {
116
+ return `
117
+ # Implementation Roadmap
118
+
119
+ ## 1. Execution Strategy
120
+ Strategy details here.
121
+
122
+ ## 2. Tasks
123
+
124
+ ### Phase 1: Setup
125
+ #### T1.1: Task One
126
+ **State:** [FINISHED]
127
+ **Target:** target/one
128
+ **Context:** context/one
129
+
130
+ **Action Steps:**
131
+ - step 1
132
+ - step 2
133
+
134
+ **Verification (TDD):**
135
+ run verify 1
136
+
137
+ ### Phase 2: Implementation
138
+ #### T1.2: Task Two
139
+ **State:** [IN-PROGRESS]
140
+ **Target:** target/two
141
+ **Context:** context/two
142
+
143
+ **Action Steps:**
144
+ - step A
145
+
146
+ **Verification (TDD):**
147
+ run verify 2
148
+
149
+ ## 3. Pre-emptive Mitigations
150
+ Mitigation details here.
151
+ `
152
+ }
153
+
154
+ func TestParseTasks(t *testing.T) {
155
+ tmpDir, err := os.MkdirTemp("", "specforce-test-*")
156
+ if err != nil {
157
+ t.Fatal(err)
158
+ }
159
+ defer func() { _ = os.RemoveAll(tmpDir) }()
160
+
161
+ slug := "test-feature"
162
+ setupTasksFile(t, tmpDir, slug, getSampleTasksMD())
163
+
164
+ report, err := ParseTasks(context.Background(), tmpDir, slug)
165
+ if err != nil {
166
+ t.Fatalf("Unexpected error: %v", err)
167
+ }
168
+
169
+ if len(report.Phases) != 2 {
170
+ t.Errorf("Expected 2 phases, got %d", len(report.Phases))
171
+ }
172
+
173
+ if report.Phases[0].Title != "Setup" || report.Phases[1].Title != "Implementation" {
174
+ t.Errorf("Unexpected phase titles: %s, %s", report.Phases[0].Title, report.Phases[1].Title)
175
+ }
176
+
177
+ if len(report.Tasks()) != 2 {
178
+ t.Errorf("Expected 2 tasks total, got %d", len(report.Tasks()))
179
+ }
180
+
181
+ t1 := report.Phases[0].Tasks[0]
182
+ if t1.ID != "T1.1" || t1.Title != "Task One" {
183
+ t.Errorf("Task 1.1 mismatch: %+v", t1)
184
+ }
185
+
186
+ if report.ExecutionStrategy != "Strategy details here." {
187
+ t.Errorf("Expected strategy, got %v", report.ExecutionStrategy)
188
+ }
189
+
190
+ if report.PreemptiveMitigations != "Mitigation details here." {
191
+ t.Errorf("Expected mitigations, got %v", report.PreemptiveMitigations)
192
+ }
193
+ }
194
+
195
+ func TestParseTasks_EdgeCases(t *testing.T) {
196
+ tmpDir, err := os.MkdirTemp("", "specforce-test-*")
197
+ if err != nil {
198
+ t.Fatal(err)
199
+ }
200
+ defer func() { _ = os.RemoveAll(tmpDir) }()
201
+
202
+ slug := "edge-feature"
203
+ content := `
204
+ # No sections
205
+ #### T1.1: Standalone Task
206
+ **State:** [PENDING]
207
+ `
208
+ setupTasksFile(t, tmpDir, slug, content)
209
+
210
+ report, err := ParseTasks(context.Background(), tmpDir, slug)
211
+ if err != nil {
212
+ t.Fatal(err)
213
+ }
214
+
215
+ if report.ExecutionStrategy != "" {
216
+ t.Errorf("Expected empty strategy, got %v", report.ExecutionStrategy)
217
+ }
218
+
219
+ if len(report.Phases) != 1 || report.Phases[0].Title != "Initial Tasks" {
220
+ t.Errorf("Expected 1 default phase, got %v", len(report.Phases))
221
+ }
222
+ }
223
+
224
+ func TestImplementationReport_Tasks(t *testing.T) {
225
+ report := &ImplementationReport{
226
+ Phases: []Phase{
227
+ {
228
+ ID: "1",
229
+ Title: "Phase 1",
230
+ Tasks: []ImplementationTask{
231
+ {ID: "T1.1", Title: "Task 1.1"},
232
+ {ID: "T1.2", Title: "Task 1.2"},
233
+ },
234
+ },
235
+ {
236
+ ID: "2",
237
+ Title: "Phase 2",
238
+ Tasks: []ImplementationTask{
239
+ {ID: "T2.1", Title: "Task 2.1"},
240
+ },
241
+ },
242
+ },
243
+ }
244
+
245
+ tasks := report.Tasks()
246
+ if len(tasks) != 3 {
247
+ t.Fatalf("Expected 3 tasks, got %d", len(tasks))
248
+ }
249
+
250
+ if tasks[0].ID != "T1.1" || tasks[1].ID != "T1.2" || tasks[2].ID != "T2.1" {
251
+ t.Errorf("Unexpected task order or IDs: %v", tasks)
252
+ }
253
+ }
@@ -0,0 +1,142 @@
1
+ package spec
2
+
3
+ import (
4
+ "fmt"
5
+ "io/fs"
6
+ "strings"
7
+
8
+ "gopkg.in/yaml.v3"
9
+ )
10
+
11
+ // Artifact represents a specification document type.
12
+ type Artifact struct {
13
+ Name string `json:"name" yaml:"-"`
14
+ Description string `json:"description" yaml:"description"`
15
+ Instruction string `json:"instruction" yaml:"instruction"`
16
+ Template string `json:"template" yaml:"template"`
17
+ Dependency string `json:"dependency" yaml:"dependency"`
18
+ }
19
+
20
+ // Registry manages the collection of spec artifacts.
21
+ type Registry struct {
22
+ artifacts map[string]Artifact
23
+ }
24
+
25
+ // NewRegistry initializes a new registry by loading YAML files from the provided filesystem.
26
+ func NewRegistry(artifactsFS fs.FS) (*Registry, error) {
27
+ r := &Registry{
28
+ artifacts: make(map[string]Artifact),
29
+ }
30
+
31
+ artifactRoot := "."
32
+
33
+ err := fs.WalkDir(artifactsFS, artifactRoot, func(path string, d fs.DirEntry, err error) error {
34
+ if err != nil {
35
+ return err
36
+ }
37
+ if d.IsDir() || !strings.HasSuffix(d.Name(), ".yaml") {
38
+ return nil
39
+ }
40
+
41
+ art, err := loadArtifact(artifactsFS, path, d.Name())
42
+ if err != nil {
43
+ return err
44
+ }
45
+
46
+ r.artifacts[art.Name] = art
47
+ return nil
48
+ })
49
+
50
+ if err != nil {
51
+ return nil, fmt.Errorf("failed to load spec artifacts: %w", err)
52
+ }
53
+
54
+ // Circular dependency check
55
+ if err := r.checkCircularDependencies(); err != nil {
56
+ return nil, err
57
+ }
58
+
59
+ return r, nil
60
+ }
61
+
62
+ func loadArtifact(artifactsFS fs.FS, path, fileName string) (Artifact, error) {
63
+ data, err := fs.ReadFile(artifactsFS, path)
64
+ if err != nil {
65
+ return Artifact{}, fmt.Errorf("failed to read artifact %s: %w", path, err)
66
+ }
67
+
68
+ var art Artifact
69
+ if err := yaml.Unmarshal(data, &art); err != nil {
70
+ return Artifact{}, fmt.Errorf("failed to parse artifact %s: %w", path, err)
71
+ }
72
+
73
+ // Validation: Check required fields
74
+ if art.Description == "" {
75
+ return Artifact{}, fmt.Errorf("artifact %s is missing 'description'", path)
76
+ }
77
+ if art.Instruction == "" {
78
+ return Artifact{}, fmt.Errorf("artifact %s is missing 'instruction'", path)
79
+ }
80
+ if art.Template == "" {
81
+ return Artifact{}, fmt.Errorf("artifact %s is missing 'template'", path)
82
+ }
83
+
84
+ // Name is derived from the filename without extension
85
+ art.Name = strings.TrimSuffix(fileName, ".yaml")
86
+
87
+ return art, nil
88
+ }
89
+
90
+ // Get returns an artifact by its name.
91
+ func (r *Registry) Get(name string) (Artifact, bool) {
92
+ art, ok := r.artifacts[name]
93
+ return art, ok
94
+ }
95
+
96
+ // List returns all loaded artifacts.
97
+ func (r *Registry) List() []Artifact {
98
+ list := make([]Artifact, 0, len(r.artifacts))
99
+ // Standard order: requirements, design, tasks
100
+ order := []string{"requirements", "design", "tasks"}
101
+
102
+ for _, name := range order {
103
+ if art, ok := r.artifacts[name]; ok {
104
+ list = append(list, art)
105
+ }
106
+ }
107
+
108
+ // Catch any artifacts not in the explicit order
109
+ for name, art := range r.artifacts {
110
+ found := false
111
+ for _, orderedName := range order {
112
+ if name == orderedName {
113
+ found = true
114
+ break
115
+ }
116
+ }
117
+ if !found {
118
+ list = append(list, art)
119
+ }
120
+ }
121
+
122
+ return list
123
+ }
124
+
125
+ func (r *Registry) checkCircularDependencies() error {
126
+ for name := range r.artifacts {
127
+ visited := make(map[string]bool)
128
+ curr := name
129
+ for curr != "" {
130
+ if visited[curr] {
131
+ return fmt.Errorf("circular dependency detected involving artifact: %s", curr)
132
+ }
133
+ visited[curr] = true
134
+ art, ok := r.artifacts[curr]
135
+ if !ok {
136
+ break
137
+ }
138
+ curr = art.Dependency
139
+ }
140
+ }
141
+ return nil
142
+ }