codecartographer-pi 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 (75) hide show
  1. package/.codecarto/BACKLOG.md +192 -0
  2. package/.codecarto/CHANGELOG-2026-05-02-feedback-pass.md +118 -0
  3. package/.codecarto/CONTRIBUTING.md +56 -0
  4. package/.codecarto/GUIDE.md +298 -0
  5. package/.codecarto/LICENSE +21 -0
  6. package/.codecarto/NEW_THREAD_BLURB.md +47 -0
  7. package/.codecarto/README.md +39 -0
  8. package/.codecarto/THREAD_LOG.md +39 -0
  9. package/.codecarto/closeouts/2026-05-02-framework-feedback-pass.md +111 -0
  10. package/.codecarto/findings/architecture/README.md +3 -0
  11. package/.codecarto/findings/architecture/SKILL.md +102 -0
  12. package/.codecarto/findings/build-and-deploy/.gitkeep +0 -0
  13. package/.codecarto/findings/config-model/.gitkeep +0 -0
  14. package/.codecarto/findings/contracts/README.md +3 -0
  15. package/.codecarto/findings/contracts/SKILL.md +89 -0
  16. package/.codecarto/findings/defect-scan/README.md +18 -0
  17. package/.codecarto/findings/defect-scan/SKILL.md +87 -0
  18. package/.codecarto/findings/defect-scan/passes/01-logic-and-correctness.md +50 -0
  19. package/.codecarto/findings/defect-scan/passes/02-error-handling.md +55 -0
  20. package/.codecarto/findings/defect-scan/passes/03-concurrency-and-resources.md +54 -0
  21. package/.codecarto/findings/defect-scan/passes/04-security-and-trust.md +62 -0
  22. package/.codecarto/findings/defect-scan/passes/05-api-contract-violations.md +57 -0
  23. package/.codecarto/findings/defect-scan/passes/06-config-and-environment.md +58 -0
  24. package/.codecarto/findings/defect-scan-mechanical/README.md +17 -0
  25. package/.codecarto/findings/defect-scan-mechanical/SKILL.md +60 -0
  26. package/.codecarto/findings/defect-scan-semantic/README.md +17 -0
  27. package/.codecarto/findings/defect-scan-semantic/SKILL.md +54 -0
  28. package/.codecarto/findings/porting/README.md +3 -0
  29. package/.codecarto/findings/porting/SKILL.md +52 -0
  30. package/.codecarto/findings/protocols/README.md +3 -0
  31. package/.codecarto/findings/protocols/SKILL.md +87 -0
  32. package/.codecarto/findings/public-surfaces/README.md +3 -0
  33. package/.codecarto/findings/reimplementation-spec/README.md +3 -0
  34. package/.codecarto/findings/reimplementation-spec/SKILL.md +66 -0
  35. package/.codecarto/findings/runtime-lifecycle/README.md +3 -0
  36. package/.codecarto/findings/state-and-storage/README.md +3 -0
  37. package/.codecarto/scratch/.gitkeep +0 -0
  38. package/.codecarto/skills/spec-delta-application/SKILL.md +102 -0
  39. package/.codecarto/templates/architecture-map.md +143 -0
  40. package/.codecarto/templates/behavioral-contracts.md +134 -0
  41. package/.codecarto/templates/closeout-template.md +85 -0
  42. package/.codecarto/templates/conventions-template.md +65 -0
  43. package/.codecarto/templates/decisions-template.md +82 -0
  44. package/.codecarto/templates/defect-fix-tracker.md +77 -0
  45. package/.codecarto/templates/defect-report.md +116 -0
  46. package/.codecarto/templates/deltas-applied.md +71 -0
  47. package/.codecarto/templates/mechanical-defects.md +104 -0
  48. package/.codecarto/templates/protocols-and-state.md +126 -0
  49. package/.codecarto/templates/reimplementation-spec-opinionated.md +183 -0
  50. package/.codecarto/templates/reimplementation-spec.md +148 -0
  51. package/.codecarto/templates/reverse-engineering-bundle.md +141 -0
  52. package/.codecarto/templates/semantic-defects.md +109 -0
  53. package/.codecarto/templates/thread-log-entry-template.md +27 -0
  54. package/.codecarto/workflow/VALIDATE.md +81 -0
  55. package/.codecarto/workflow/pipeline-architecture-only.yaml +38 -0
  56. package/.codecarto/workflow/pipeline-defect-scan.yaml +61 -0
  57. package/.codecarto/workflow/pipeline-full-with-audit.yaml +188 -0
  58. package/.codecarto/workflow/pipeline-full-with-deep-audit.yaml +227 -0
  59. package/.codecarto/workflow/pipeline-lite.yaml +100 -0
  60. package/.codecarto/workflow/pipeline.yaml +163 -0
  61. package/.codecarto/workflow/status.yaml +64 -0
  62. package/LICENSE +21 -0
  63. package/README.md +356 -0
  64. package/core/index.ts +11 -0
  65. package/core/pipeline.ts +175 -0
  66. package/core/prompts.ts +183 -0
  67. package/core/status.ts +155 -0
  68. package/core/types.ts +96 -0
  69. package/core/utils.ts +52 -0
  70. package/core/workspace.ts +81 -0
  71. package/core/yaml.ts +256 -0
  72. package/extensions/codecarto/index.ts +446 -0
  73. package/mcp-server/bin.mjs +7 -0
  74. package/mcp-server/server.ts +497 -0
  75. package/package.json +52 -0
@@ -0,0 +1,227 @@
1
+ workflow_name: codebase-reverse-engineering-with-deep-audit
2
+ workflow_version: 1
3
+ workflow_goal: Produce a reverse-engineering bundle and reimplementation spec, with the defect scan split into an early mechanical pass (after architecture) and a deep semantic pass (after protocols), so the reimplementation can design around defects with full context.
4
+ source_location: ../
5
+ validation_protocol: workflow/VALIDATE.md
6
+ phase_order:
7
+ - architecture
8
+ - defect-scan-mechanical
9
+ - contracts
10
+ - protocols
11
+ - defect-scan-semantic
12
+ - porting
13
+ - reimplementation-spec
14
+ phases:
15
+ - id: architecture
16
+ purpose: Build the layer map, dependency direction, public surfaces, and high-level system structure.
17
+ skill_path: findings/architecture/SKILL.md
18
+ output_template: templates/architecture-map.md
19
+ depends_on: []
20
+ primary_output: findings/architecture/architecture-map.md
21
+ secondary_outputs:
22
+ - path: findings/public-surfaces/public-surfaces.md
23
+ mode: append
24
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
25
+ mode: append
26
+ - path: findings/state-and-storage/state-and-storage.md
27
+ mode: append
28
+ - path: findings/build-and-deploy/build-and-deploy.md
29
+ mode: append
30
+ - path: findings/config-model/config-model.md
31
+ mode: append
32
+ required_reads:
33
+ - GUIDE.md
34
+ - workflow/status.yaml
35
+ completion_criteria:
36
+ - The system intent is documented.
37
+ - The layer map and dependency direction are documented.
38
+ - Public surfaces are identified.
39
+ - Runtime lifecycle, concurrency model, and porting priorities are summarized.
40
+ - Findings are marked with evidence levels.
41
+ handoff_requirements:
42
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
43
+ - Update workflow/status.yaml.
44
+ - Append a summary entry to THREAD_LOG.md.
45
+ - id: defect-scan-mechanical
46
+ purpose: Early, context-light defect pass covering logic, error handling, and configuration hazards. Runs before contracts so mechanical bugs are surfaced for the contracts and porting phases to reference.
47
+ skill_path: findings/defect-scan-mechanical/SKILL.md
48
+ output_template: templates/mechanical-defects.md
49
+ depends_on:
50
+ - architecture
51
+ primary_output: findings/defect-scan-mechanical/mechanical-defects.md
52
+ secondary_outputs: []
53
+ required_reads:
54
+ - GUIDE.md
55
+ - workflow/status.yaml
56
+ - findings/architecture/architecture-map.md
57
+ completion_criteria:
58
+ - At least two of the three mechanical passes (1, 2, 6) produced findings or documented "no defects found."
59
+ - Each finding has location, severity, evidence level, and recommended action.
60
+ - Findings are organized by pass and sorted by severity.
61
+ - Summary tables are complete and counts match the detailed findings.
62
+ - Items spotted that are actually semantic in nature are routed to defect-scan-semantic via carry_forward in workflow/status.yaml.
63
+ - Findings are marked with evidence levels.
64
+ handoff_requirements:
65
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
66
+ - Update workflow/status.yaml.
67
+ - Append a summary entry to THREAD_LOG.md.
68
+ - id: contracts
69
+ purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
70
+ skill_path: findings/contracts/SKILL.md
71
+ output_template: templates/behavioral-contracts.md
72
+ depends_on:
73
+ - architecture
74
+ primary_output: findings/contracts/behavioral-contracts.md
75
+ secondary_outputs:
76
+ - path: findings/public-surfaces/public-surfaces.md
77
+ mode: append
78
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
79
+ mode: append
80
+ - path: findings/state-and-storage/state-and-storage.md
81
+ mode: append
82
+ - path: findings/config-model/config-model.md
83
+ mode: append
84
+ required_reads:
85
+ - GUIDE.md
86
+ - workflow/status.yaml
87
+ - findings/architecture/architecture-map.md
88
+ - findings/defect-scan-mechanical/mechanical-defects.md
89
+ completion_criteria:
90
+ - User-facing surfaces are split by surface type.
91
+ - Feature contracts record trigger, defaults, outputs, side effects, persisted state, error behavior, and recovery behavior.
92
+ - Security and authorization model is documented (if applicable).
93
+ - Contract ownership is mapped back to a layer or package.
94
+ - A black-box acceptance list is included.
95
+ - Findings are marked with evidence levels.
96
+ handoff_requirements:
97
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
98
+ - Update workflow/status.yaml.
99
+ - Append a summary entry to THREAD_LOG.md.
100
+ - id: protocols
101
+ purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
102
+ skill_path: findings/protocols/SKILL.md
103
+ output_template: templates/protocols-and-state.md
104
+ depends_on:
105
+ - architecture
106
+ primary_output: findings/protocols/protocols-and-state.md
107
+ secondary_outputs:
108
+ - path: findings/public-surfaces/public-surfaces.md
109
+ mode: append
110
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
111
+ mode: append
112
+ - path: findings/state-and-storage/state-and-storage.md
113
+ mode: append
114
+ - path: findings/config-model/config-model.md
115
+ mode: append
116
+ required_reads:
117
+ - GUIDE.md
118
+ - workflow/status.yaml
119
+ - findings/architecture/architecture-map.md
120
+ - findings/defect-scan-mechanical/mechanical-defects.md
121
+ completion_criteria:
122
+ - An event catalog is documented.
123
+ - A state machine is documented.
124
+ - Persistent schema notes are documented.
125
+ - Compatibility hazards are documented.
126
+ - Findings are marked with evidence levels.
127
+ handoff_requirements:
128
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
129
+ - Update workflow/status.yaml.
130
+ - Append a summary entry to THREAD_LOG.md.
131
+ - id: defect-scan-semantic
132
+ purpose: Deep, context-rich defect pass covering concurrency, security, and API contract violations. Runs after protocols so contracts/protocols context is available, and before porting so the porting phase can synthesize all defects with full understanding of the system.
133
+ skill_path: findings/defect-scan-semantic/SKILL.md
134
+ output_template: templates/semantic-defects.md
135
+ depends_on:
136
+ - architecture
137
+ - contracts
138
+ - protocols
139
+ - defect-scan-mechanical
140
+ primary_output: findings/defect-scan-semantic/semantic-defects.md
141
+ secondary_outputs: []
142
+ required_reads:
143
+ - GUIDE.md
144
+ - workflow/status.yaml
145
+ - findings/architecture/architecture-map.md
146
+ - findings/contracts/behavioral-contracts.md
147
+ - findings/protocols/protocols-and-state.md
148
+ - findings/defect-scan-mechanical/mechanical-defects.md
149
+ completion_criteria:
150
+ - All three semantic passes (3, 4, 5) produced findings or documented "no defects found."
151
+ - Each finding has location, severity, evidence level, and recommended action.
152
+ - Pass 5 findings cite the contract or protocol reference they violate.
153
+ - Findings are organized by pass and sorted by severity; summary tables match the detailed findings.
154
+ - Any carry_forward entries that targeted defect-scan-semantic have been resolved or explicitly re-routed.
155
+ - Findings are marked with evidence levels.
156
+ handoff_requirements:
157
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
158
+ - Update workflow/status.yaml.
159
+ - Append a summary entry to THREAD_LOG.md.
160
+ - id: porting
161
+ purpose: Synthesize architecture, contracts, protocols, and both defect passes into a reverse-engineering bundle oriented toward porting. Fill the Defect Synthesis section by consolidating mechanical-defects.md and semantic-defects.md into a single porting-oriented view.
162
+ skill_path: findings/porting/SKILL.md
163
+ output_template: templates/reverse-engineering-bundle.md
164
+ depends_on:
165
+ - architecture
166
+ - contracts
167
+ - protocols
168
+ - defect-scan-mechanical
169
+ - defect-scan-semantic
170
+ primary_output: findings/porting/reverse-engineering-bundle.md
171
+ secondary_outputs:
172
+ - path: findings/public-surfaces/public-surfaces.md
173
+ mode: append
174
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
175
+ mode: append
176
+ - path: findings/state-and-storage/state-and-storage.md
177
+ mode: append
178
+ - path: findings/build-and-deploy/build-and-deploy.md
179
+ mode: append
180
+ - path: findings/config-model/config-model.md
181
+ mode: append
182
+ required_reads:
183
+ - GUIDE.md
184
+ - workflow/status.yaml
185
+ - findings/architecture/architecture-map.md
186
+ - findings/contracts/behavioral-contracts.md
187
+ - findings/protocols/protocols-and-state.md
188
+ - findings/defect-scan-mechanical/mechanical-defects.md
189
+ - findings/defect-scan-semantic/semantic-defects.md
190
+ completion_criteria:
191
+ - The system summary, layer map, contract table, protocol notes, and porting findings are synthesized.
192
+ - Portability hazards and open questions are separated from facts.
193
+ - Feature importance is sorted for porting.
194
+ - Defect Synthesis consolidates mechanical-defects.md and semantic-defects.md with porting recommendations (fix before porting / port differently / leave behind).
195
+ - Findings are marked with evidence levels.
196
+ handoff_requirements:
197
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
198
+ - Update workflow/status.yaml.
199
+ - Append a summary entry to THREAD_LOG.md.
200
+ - id: reimplementation-spec
201
+ purpose: Produce the final language-agnostic reimplementation plan and acceptance spec. The Strategic Alignment Hook in GUIDE.md decides between the default and opinionated template variants.
202
+ skill_path: findings/reimplementation-spec/SKILL.md
203
+ output_template: templates/reimplementation-spec.md
204
+ depends_on:
205
+ - porting
206
+ primary_output: findings/reimplementation-spec/reimplementation-spec.md
207
+ secondary_outputs: []
208
+ required_reads:
209
+ - GUIDE.md
210
+ - workflow/status.yaml
211
+ - findings/architecture/architecture-map.md
212
+ - findings/contracts/behavioral-contracts.md
213
+ - findings/protocols/protocols-and-state.md
214
+ - findings/porting/reverse-engineering-bundle.md
215
+ - findings/defect-scan-mechanical/mechanical-defects.md
216
+ - findings/defect-scan-semantic/semantic-defects.md
217
+ completion_criteria:
218
+ - Concept-level modules are defined.
219
+ - Required behaviors are stated.
220
+ - Protocol and persisted state expectations are stated.
221
+ - Acceptance scenarios and known unknowns are included.
222
+ - Defects identified in either scan are explicitly designed-around or noted as "left behind", with the choice cited.
223
+ - Findings are marked with evidence levels.
224
+ handoff_requirements:
225
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
226
+ - Update workflow/status.yaml.
227
+ - Append a summary entry to THREAD_LOG.md.
@@ -0,0 +1,100 @@
1
+ workflow_name: codebase-analysis-lite
2
+ workflow_version: 3
3
+ workflow_goal: Produce an architecture map, behavioral contracts, and protocol notes for an unfamiliar source repository.
4
+ source_location: ../
5
+ validation_protocol: workflow/VALIDATE.md
6
+ phase_order:
7
+ - architecture
8
+ - contracts
9
+ - protocols
10
+ phases:
11
+ - id: architecture
12
+ purpose: Build the layer map, dependency direction, public surfaces, and high-level system structure.
13
+ skill_path: findings/architecture/SKILL.md
14
+ output_template: templates/architecture-map.md
15
+ depends_on: []
16
+ primary_output: findings/architecture/architecture-map.md
17
+ secondary_outputs:
18
+ - path: findings/public-surfaces/public-surfaces.md
19
+ mode: append
20
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
21
+ mode: append
22
+ - path: findings/state-and-storage/state-and-storage.md
23
+ mode: append
24
+ - path: findings/build-and-deploy/build-and-deploy.md
25
+ mode: append
26
+ - path: findings/config-model/config-model.md
27
+ mode: append
28
+ required_reads:
29
+ - GUIDE.md
30
+ - workflow/status.yaml
31
+ completion_criteria:
32
+ - The system intent is documented.
33
+ - The layer map and dependency direction are documented.
34
+ - Public surfaces are identified.
35
+ - Runtime lifecycle, concurrency model, and porting priorities are summarized.
36
+ - Findings are marked with evidence levels.
37
+ handoff_requirements:
38
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
39
+ - Update workflow/status.yaml.
40
+ - Append a summary entry to THREAD_LOG.md.
41
+ - id: contracts
42
+ purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
43
+ skill_path: findings/contracts/SKILL.md
44
+ output_template: templates/behavioral-contracts.md
45
+ depends_on:
46
+ - architecture
47
+ primary_output: findings/contracts/behavioral-contracts.md
48
+ secondary_outputs:
49
+ - path: findings/public-surfaces/public-surfaces.md
50
+ mode: append
51
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
52
+ mode: append
53
+ - path: findings/state-and-storage/state-and-storage.md
54
+ mode: append
55
+ - path: findings/config-model/config-model.md
56
+ mode: append
57
+ required_reads:
58
+ - GUIDE.md
59
+ - workflow/status.yaml
60
+ - findings/architecture/architecture-map.md
61
+ completion_criteria:
62
+ - User-facing surfaces are split by surface type.
63
+ - Feature contracts record trigger, defaults, outputs, side effects, persisted state, error behavior, and recovery behavior.
64
+ - Contract ownership is mapped back to a layer or package.
65
+ - A black-box acceptance list is included.
66
+ - Findings are marked with evidence levels.
67
+ handoff_requirements:
68
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
69
+ - Update workflow/status.yaml.
70
+ - Append a summary entry to THREAD_LOG.md.
71
+ - id: protocols
72
+ purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
73
+ skill_path: findings/protocols/SKILL.md
74
+ output_template: templates/protocols-and-state.md
75
+ depends_on:
76
+ - architecture
77
+ primary_output: findings/protocols/protocols-and-state.md
78
+ secondary_outputs:
79
+ - path: findings/public-surfaces/public-surfaces.md
80
+ mode: append
81
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
82
+ mode: append
83
+ - path: findings/state-and-storage/state-and-storage.md
84
+ mode: append
85
+ - path: findings/config-model/config-model.md
86
+ mode: append
87
+ required_reads:
88
+ - GUIDE.md
89
+ - workflow/status.yaml
90
+ - findings/architecture/architecture-map.md
91
+ completion_criteria:
92
+ - An event catalog is documented.
93
+ - A state machine is documented.
94
+ - Persistent schema notes are documented.
95
+ - Compatibility hazards are documented.
96
+ - Findings are marked with evidence levels.
97
+ handoff_requirements:
98
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
99
+ - Update workflow/status.yaml.
100
+ - Append a summary entry to THREAD_LOG.md.
@@ -0,0 +1,163 @@
1
+ workflow_name: codebase-reverse-engineering
2
+ workflow_version: 3
3
+ workflow_goal: Produce a reusable reverse-engineering bundle for an unfamiliar source repository in ordered phases.
4
+ source_location: ../
5
+ validation_protocol: workflow/VALIDATE.md
6
+ phase_order:
7
+ - architecture
8
+ - contracts
9
+ - protocols
10
+ - porting
11
+ - reimplementation-spec
12
+ phases:
13
+ - id: architecture
14
+ purpose: Build the layer map, dependency direction, public surfaces, and high-level system structure.
15
+ skill_path: findings/architecture/SKILL.md
16
+ output_template: templates/architecture-map.md
17
+ depends_on: []
18
+ primary_output: findings/architecture/architecture-map.md
19
+ secondary_outputs:
20
+ - path: findings/public-surfaces/public-surfaces.md
21
+ mode: append
22
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
23
+ mode: append
24
+ - path: findings/state-and-storage/state-and-storage.md
25
+ mode: append
26
+ - path: findings/build-and-deploy/build-and-deploy.md
27
+ mode: append
28
+ - path: findings/config-model/config-model.md
29
+ mode: append
30
+ required_reads:
31
+ - GUIDE.md
32
+ - workflow/status.yaml
33
+ completion_criteria:
34
+ - The system intent is documented.
35
+ - The layer map and dependency direction are documented.
36
+ - Public surfaces are identified.
37
+ - Runtime lifecycle, concurrency model, and porting priorities are summarized.
38
+ - Findings are marked with evidence levels.
39
+ handoff_requirements:
40
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
41
+ - Update workflow/status.yaml.
42
+ - Append a summary entry to THREAD_LOG.md.
43
+ - id: contracts
44
+ purpose: Recover user-visible behavior, defaults, side effects, error behavior, and black-box acceptance checks.
45
+ skill_path: findings/contracts/SKILL.md
46
+ output_template: templates/behavioral-contracts.md
47
+ depends_on:
48
+ - architecture
49
+ primary_output: findings/contracts/behavioral-contracts.md
50
+ secondary_outputs:
51
+ - path: findings/public-surfaces/public-surfaces.md
52
+ mode: append
53
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
54
+ mode: append
55
+ - path: findings/state-and-storage/state-and-storage.md
56
+ mode: append
57
+ - path: findings/config-model/config-model.md
58
+ mode: append
59
+ required_reads:
60
+ - GUIDE.md
61
+ - workflow/status.yaml
62
+ - findings/architecture/architecture-map.md
63
+ completion_criteria:
64
+ - User-facing surfaces are split by surface type.
65
+ - Feature contracts record trigger, defaults, outputs, side effects, persisted state, error behavior, and recovery behavior.
66
+ - Security and authorization model is documented (if applicable).
67
+ - Contract ownership is mapped back to a layer or package.
68
+ - A black-box acceptance list is included.
69
+ - Findings are marked with evidence levels.
70
+ handoff_requirements:
71
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
72
+ - Update workflow/status.yaml.
73
+ - Append a summary entry to THREAD_LOG.md.
74
+ - id: protocols
75
+ purpose: Capture event catalogs, state machines, persistence formats, and compatibility hazards.
76
+ skill_path: findings/protocols/SKILL.md
77
+ output_template: templates/protocols-and-state.md
78
+ depends_on:
79
+ - architecture
80
+ primary_output: findings/protocols/protocols-and-state.md
81
+ secondary_outputs:
82
+ - path: findings/public-surfaces/public-surfaces.md
83
+ mode: append
84
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
85
+ mode: append
86
+ - path: findings/state-and-storage/state-and-storage.md
87
+ mode: append
88
+ - path: findings/config-model/config-model.md
89
+ mode: append
90
+ required_reads:
91
+ - GUIDE.md
92
+ - workflow/status.yaml
93
+ - findings/architecture/architecture-map.md
94
+ completion_criteria:
95
+ - An event catalog is documented.
96
+ - A state machine is documented.
97
+ - Persistent schema notes are documented.
98
+ - Compatibility hazards are documented.
99
+ - Findings are marked with evidence levels.
100
+ handoff_requirements:
101
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
102
+ - Update workflow/status.yaml.
103
+ - Append a summary entry to THREAD_LOG.md.
104
+ - id: porting
105
+ purpose: Synthesize architecture, contracts, and protocols into a reverse-engineering bundle oriented toward porting.
106
+ skill_path: findings/porting/SKILL.md
107
+ output_template: templates/reverse-engineering-bundle.md
108
+ depends_on:
109
+ - architecture
110
+ - contracts
111
+ - protocols
112
+ primary_output: findings/porting/reverse-engineering-bundle.md
113
+ secondary_outputs:
114
+ - path: findings/public-surfaces/public-surfaces.md
115
+ mode: append
116
+ - path: findings/runtime-lifecycle/runtime-lifecycle.md
117
+ mode: append
118
+ - path: findings/state-and-storage/state-and-storage.md
119
+ mode: append
120
+ - path: findings/build-and-deploy/build-and-deploy.md
121
+ mode: append
122
+ - path: findings/config-model/config-model.md
123
+ mode: append
124
+ required_reads:
125
+ - GUIDE.md
126
+ - workflow/status.yaml
127
+ - findings/architecture/architecture-map.md
128
+ - findings/contracts/behavioral-contracts.md
129
+ - findings/protocols/protocols-and-state.md
130
+ completion_criteria:
131
+ - The system summary, layer map, contract table, protocol notes, and porting findings are synthesized.
132
+ - Portability hazards and open questions are separated from facts.
133
+ - Feature importance is sorted for porting.
134
+ - Findings are marked with evidence levels.
135
+ handoff_requirements:
136
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
137
+ - Update workflow/status.yaml.
138
+ - Append a summary entry to THREAD_LOG.md.
139
+ - id: reimplementation-spec
140
+ purpose: Produce the final language-agnostic reimplementation plan and acceptance spec.
141
+ skill_path: findings/reimplementation-spec/SKILL.md
142
+ output_template: templates/reimplementation-spec.md
143
+ depends_on:
144
+ - porting
145
+ primary_output: findings/reimplementation-spec/reimplementation-spec.md
146
+ secondary_outputs: []
147
+ required_reads:
148
+ - GUIDE.md
149
+ - workflow/status.yaml
150
+ - findings/architecture/architecture-map.md
151
+ - findings/contracts/behavioral-contracts.md
152
+ - findings/protocols/protocols-and-state.md
153
+ - findings/porting/reverse-engineering-bundle.md
154
+ completion_criteria:
155
+ - Concept-level modules are defined.
156
+ - Required behaviors are stated.
157
+ - Protocol and persisted state expectations are stated.
158
+ - Acceptance scenarios and known unknowns are included.
159
+ - Findings are marked with evidence levels.
160
+ handoff_requirements:
161
+ - Run validation per workflow/VALIDATE.md. Append validation block to primary output.
162
+ - Update workflow/status.yaml.
163
+ - Append a summary entry to THREAD_LOG.md.
@@ -0,0 +1,64 @@
1
+ project_name: ""
2
+ # source_location is defined in the active pipeline YAML. Do not duplicate it here.
3
+ pipeline: workflow/pipeline-full-with-deep-audit.yaml
4
+ # ^^^ To switch pipelines, change the line above AND adjust the phases below to match:
5
+ # pipeline-full-with-deep-audit.yaml (default) → keep phases as-is (split defect scan)
6
+ # pipeline-full-with-audit.yaml → replace defect-scan-mechanical and defect-scan-semantic with a single defect-scan
7
+ # pipeline.yaml → remove all defect-scan phases
8
+ # pipeline-defect-scan.yaml → remove contracts through reimplementation-spec; collapse defect phases into a single defect-scan
9
+ # pipeline-lite.yaml → remove all defect-scan phases, porting, and reimplementation-spec
10
+ # pipeline-architecture-only.yaml → keep only architecture
11
+ current_phase: architecture # Set to "complete" when all phases are done.
12
+ last_updated: ""
13
+ # Schema for open_questions and carry_forward entries (see GUIDE.md "Open Questions vs Carry-Forward"):
14
+ # open_questions: items that are still genuinely unknown (need a runtime test, maintainer decision, spec ruling).
15
+ # carry_forward: items deferred to a specific later phase whose rubric is the right place to close them.
16
+ # Each entry is a mapping with keys: id, kind, description, deferred_reason
17
+ # carry_forward entries additionally carry: target_phase
18
+ # Allowed kinds: needs-runtime-test, needs-maintainer-decision, needs-spec-ruling,
19
+ # defer-to-phase, needs-fixture-capture
20
+ phases:
21
+ architecture:
22
+ status: pending
23
+ owner_notes: []
24
+ outputs_present: []
25
+ open_questions: [] # genuinely unknown items
26
+ carry_forward: [] # items routed to a later phase {id, kind, target_phase, description, deferred_reason}
27
+ defect-scan-mechanical:
28
+ status: pending
29
+ owner_notes: []
30
+ outputs_present: []
31
+ open_questions: []
32
+ carry_forward: []
33
+ contracts:
34
+ status: pending
35
+ owner_notes: []
36
+ outputs_present: []
37
+ open_questions: []
38
+ carry_forward: []
39
+ protocols:
40
+ status: pending
41
+ owner_notes: []
42
+ outputs_present: []
43
+ open_questions: []
44
+ carry_forward: []
45
+ defect-scan-semantic:
46
+ status: pending
47
+ owner_notes: []
48
+ outputs_present: []
49
+ open_questions: []
50
+ carry_forward: []
51
+ porting:
52
+ status: pending
53
+ owner_notes: []
54
+ outputs_present: []
55
+ open_questions: []
56
+ carry_forward: []
57
+ reimplementation-spec:
58
+ status: pending
59
+ owner_notes: []
60
+ outputs_present: []
61
+ open_questions: []
62
+ carry_forward: []
63
+ next_actions:
64
+ - Begin architecture phase by reading the repository and producing findings/architecture/architecture-map.md
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 James Sesler
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.