reverse-engineer-for-porting

Reverse Engineer For Porting

This phase synthesizes the outputs of architecture, contracts, and protocols. If defect reports exist, also read and integrate them: findings/defect-scan/defect-report.md (full-with-audit pipeline) or both findings/defect-scan-mechanical/mechanical-defects.md and findings/defect-scan-semantic/semantic-defects.md (full-with-deep-audit pipeline). The pipeline ensures all required phases are complete before this one runs. Read the prior phase artifacts before starting.

Treat the reverse-engineering bundle as the pipeline's intentional compression boundary. It must be self-sufficient enough for reimplementation-spec to start from this one artifact rather than loading every upstream report. Preserve compact source pointers instead of copying upstream prose:

• Add a Source Index covering architecture, contracts, protocols/state, and defects when present.
• Carry forward every load-bearing invariant, acceptance obligation, compatibility hazard, and defect disposition.
• For omitted detail, name the canonical upstream section and the exact condition that should trigger a targeted deep read.
• Surface conflicts and incomplete coverage explicitly; never hide them behind synthesis.

The source code to analyze is in the parent directory (../ relative to .codecarto/). This is the repository root.

Keep four classes of findings separate throughout:

• observed fact: direct statements from docs, tests, schemas, types, and code.
• strong inference: architectural conclusions drawn from multiple facts.
• portability hazard: assumptions tied to the source language, runtime, terminal, OS, or third-party SDKs.
• open question: missing or conflicting behavior that still needs evidence.

Prefer concept names over source names:

• Translate file- or class-level details into concepts such as provider adapter, message normalizer, agent loop, tool executor, session store, render loop, UI surface, or product shell.
• Do not assume the target implementation should mirror the source folder layout.

Treat layered repositories as a composition problem:

• Identify the lowest reusable core first.
• Separate shared middle layers from delivery surfaces.
• Treat UI, CLI, bot, web, or deployment wrappers as adapters around shared behavior unless evidence says otherwise.
• Look for reusable layers such as provider normalization, agent runtime, UI surfaces, and product wrappers.

Sort features by porting importance:

• core: required for the system to function.
• important: required for parity on major workflows.
• optional: valuable, but not required for a first viable port.
• incidental: source-specific ergonomics or implementation accidents.

If the defect report is available, integrate defect findings into the porting bundle:

• Reference relevant defects in the feature contract table.
• Tag each referenced defect with a porting recommendation: fix before porting (the defect would carry into a new implementation), port differently (the new implementation should handle this case differently by design), or leave behind (the defect is specific to the source implementation and won't survive porting).
• Consolidate defect-related portability hazards alongside hazards from other phases.

Use the output template at templates/reverse-engineering-bundle.md. Produce:

• A system summary in plain language.
• A layer map with package or module ownership.
• A feature contract table with porting priority (include defect references if the defect report exists).
• A protocol and state note set.
• Portability hazards consolidated from all prior phases.
• Observed facts separated from inferred structure.
• A compact Source Index and explicit coverage gaps that let downstream synthesis deep-read selectively.

Bias toward evidence over cleverness:

• Prefer tests over assumptions.
• Prefer behavior over implementation detail.
• Mark uncertainty explicitly instead of flattening it away.

When fixing defects before or during porting, use the tracker template at templates/defect-fix-tracker.md to log each fix, deferral, or acceptance decision. The tracker uses defect IDs from the report (D{pass}.{number}) so progress maps directly back to findings.