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.
- package/.codecarto/BACKLOG.md +192 -0
- package/.codecarto/CHANGELOG-2026-05-02-feedback-pass.md +118 -0
- package/.codecarto/CONTRIBUTING.md +56 -0
- package/.codecarto/GUIDE.md +298 -0
- package/.codecarto/LICENSE +21 -0
- package/.codecarto/NEW_THREAD_BLURB.md +47 -0
- package/.codecarto/README.md +39 -0
- package/.codecarto/THREAD_LOG.md +39 -0
- package/.codecarto/closeouts/2026-05-02-framework-feedback-pass.md +111 -0
- package/.codecarto/findings/architecture/README.md +3 -0
- package/.codecarto/findings/architecture/SKILL.md +102 -0
- package/.codecarto/findings/build-and-deploy/.gitkeep +0 -0
- package/.codecarto/findings/config-model/.gitkeep +0 -0
- package/.codecarto/findings/contracts/README.md +3 -0
- package/.codecarto/findings/contracts/SKILL.md +89 -0
- package/.codecarto/findings/defect-scan/README.md +18 -0
- package/.codecarto/findings/defect-scan/SKILL.md +87 -0
- package/.codecarto/findings/defect-scan/passes/01-logic-and-correctness.md +50 -0
- package/.codecarto/findings/defect-scan/passes/02-error-handling.md +55 -0
- package/.codecarto/findings/defect-scan/passes/03-concurrency-and-resources.md +54 -0
- package/.codecarto/findings/defect-scan/passes/04-security-and-trust.md +62 -0
- package/.codecarto/findings/defect-scan/passes/05-api-contract-violations.md +57 -0
- package/.codecarto/findings/defect-scan/passes/06-config-and-environment.md +58 -0
- package/.codecarto/findings/defect-scan-mechanical/README.md +17 -0
- package/.codecarto/findings/defect-scan-mechanical/SKILL.md +60 -0
- package/.codecarto/findings/defect-scan-semantic/README.md +17 -0
- package/.codecarto/findings/defect-scan-semantic/SKILL.md +54 -0
- package/.codecarto/findings/porting/README.md +3 -0
- package/.codecarto/findings/porting/SKILL.md +52 -0
- package/.codecarto/findings/protocols/README.md +3 -0
- package/.codecarto/findings/protocols/SKILL.md +87 -0
- package/.codecarto/findings/public-surfaces/README.md +3 -0
- package/.codecarto/findings/reimplementation-spec/README.md +3 -0
- package/.codecarto/findings/reimplementation-spec/SKILL.md +66 -0
- package/.codecarto/findings/runtime-lifecycle/README.md +3 -0
- package/.codecarto/findings/state-and-storage/README.md +3 -0
- package/.codecarto/scratch/.gitkeep +0 -0
- package/.codecarto/skills/spec-delta-application/SKILL.md +102 -0
- package/.codecarto/templates/architecture-map.md +143 -0
- package/.codecarto/templates/behavioral-contracts.md +134 -0
- package/.codecarto/templates/closeout-template.md +85 -0
- package/.codecarto/templates/conventions-template.md +65 -0
- package/.codecarto/templates/decisions-template.md +82 -0
- package/.codecarto/templates/defect-fix-tracker.md +77 -0
- package/.codecarto/templates/defect-report.md +116 -0
- package/.codecarto/templates/deltas-applied.md +71 -0
- package/.codecarto/templates/mechanical-defects.md +104 -0
- package/.codecarto/templates/protocols-and-state.md +126 -0
- package/.codecarto/templates/reimplementation-spec-opinionated.md +183 -0
- package/.codecarto/templates/reimplementation-spec.md +148 -0
- package/.codecarto/templates/reverse-engineering-bundle.md +141 -0
- package/.codecarto/templates/semantic-defects.md +109 -0
- package/.codecarto/templates/thread-log-entry-template.md +27 -0
- package/.codecarto/workflow/VALIDATE.md +81 -0
- package/.codecarto/workflow/pipeline-architecture-only.yaml +38 -0
- package/.codecarto/workflow/pipeline-defect-scan.yaml +61 -0
- package/.codecarto/workflow/pipeline-full-with-audit.yaml +188 -0
- package/.codecarto/workflow/pipeline-full-with-deep-audit.yaml +227 -0
- package/.codecarto/workflow/pipeline-lite.yaml +100 -0
- package/.codecarto/workflow/pipeline.yaml +163 -0
- package/.codecarto/workflow/status.yaml +64 -0
- package/LICENSE +21 -0
- package/README.md +356 -0
- package/core/index.ts +11 -0
- package/core/pipeline.ts +175 -0
- package/core/prompts.ts +183 -0
- package/core/status.ts +155 -0
- package/core/types.ts +96 -0
- package/core/utils.ts +52 -0
- package/core/workspace.ts +81 -0
- package/core/yaml.ts +256 -0
- package/extensions/codecarto/index.ts +446 -0
- package/mcp-server/bin.mjs +7 -0
- package/mcp-server/server.ts +497 -0
- 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.
|