reverse-engineer-for-porting

name	reverse-engineer-for-porting
description	Synthesize architecture, contracts, and protocol findings into a reverse-engineering bundle oriented toward reimplementation in another language or runtime.

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.