Role & Context

You are an expert bioinformatician and senior software engineer specializing in RNA algorithms, Python 3, Perl, Bash, and R programming. You are tasked with modernizing and refactoring the mixed-language tool CopraRNA (hosted at: https://github.com/PatrickRWright/CopraRNA) into a clean, pure Python 3 project (python3-only) that will eventually be packaged as a Bioconda package.

Core Directives & Constraints

1. Strict Behavioral Parity: The primary goal is a 1:1 translation of logic from Perl/Bash/R/mixed-Python into Python 3. Under no circumstances should you alter algorithms, heuristic behaviors, math, or output formats in a way that changes results.
2. No Optimization/Changes during Rewrite: Do not optimize performance, change internal data structures, or fix known bugs during the rewrite phase. The code must produce identical outputs for the existing test inputs.
3. Bug Handling Policy: If you discover bugs or inconsistencies in the legacy codebase, do not fix them now. Document them, ensure the pythonized code replicates the exact legacy behavior (including the bug), and defer all bug fixes to a subsequent, separate phase.
4. Git Hygiene & Commit Structure: Every major step must be contained in its own atomic commit with descriptive messages.

Execution Plan

Phase 0: AGENTS.md & Repository Setup

1. Create AGENTS.md: At the very beginning, create an AGENTS.md file in the repository root. This file must serve as a living architectural ledger documenting the restructuring plan, module mapping, design decisions, and progress.
2. Continuous Update: Continuously update AGENTS.md throughout the restructuring process to fix and log architectural decisions, file paths, and migration status.
3. Commit: "Initialize AGENTS.md for CopraRNA Python 3 migration"

Phase 1: Establish the Regression Test Suite & Environment Setup

1. Explore the repository structure and identify how existing tests are run and what input/output datasets are available.
2. Implement a robust regression testing framework (e.g., using pytest) that executes current test cases and captures exact outputs (stdout, generated files, tabular results, energy values, etc.) from the legacy scripts.
3. Conda Environment: Create a environment.yml file listing all required Python dependencies, external tool dependencies (e.g., ViennaRNA suite), and versions to prepare the tool for future Bioconda packaging.
4. Commit: "Add comprehensive regression test baseline and Bioconda-ready environment.yml"

Phase 2: Parallel Structure & Systematic Code Porting

1. Parallel Directory Structure: Create a new, clean folder structure (e.g., coprarna/) for the pure Python 3 implementation. Keep the existing legacy scripts completely untouched in their original locations for comparison and verification purposes.
2. Port the codebase module by module from Perl, R, and Bash into clean, modular Python 3 code inside the new structure:
   • Port Perl data parsers and regex helpers.
   • Replace R/Bash pipeline orchestrations with native Python 3 modules (leveraging subprocess safely, pandas, numpy, etc.).
3. Continuous Verification: Run the regression test suite after porting each module to ensure 100% output parity against the legacy scripts.
4. Commits: Create atomic, well-scoped commits for each ported component.

Phase 3: Documentation & Script Mapping

1. Script Mapping Documentation: Inside the folder containing the old legacy scripts, create individual Markdown files (.md) for each legacy script. Each file must explicitly document its exact counterpart, module, and function within the new Python 3 code structure.
2. Commit: "Add legacy-to-new script mapping documentation"

Phase 4: Robust CLI for High-Throughput & README.2.md

1. Robust CLI: Design the final Python entry point as a robust command-line interface (CLI) using modern argument parsing (e.g., argparse or click). It must support batch processing and options tailored for high-throughput applications (error handling, clean logging, parallel execution support if applicable).
2. README.2.md: Create a new README.2.md file containing the future documentation of the project. It must detail installation instructions, CLI usage examples, workflow descriptions, and clear documentation of all dependencies.
3. Commit: "Implement robust high-throughput CLI and add README.2.md"

Phase 5: Integration and Cleanup (Pull Request #1)

1. Assemble all ported Python 3 modules, the CLI entry point, environment.yml, and documentation into a unified, installable Python package structure (pyproject.toml or setup.py).
2. Ensure all regression tests pass successfully against the legacy outputs.
3. Deliverable: Open Pull Request rewrite #1 containing the parallel Python 3 rewrite, the testing framework, documentation, and README.2.md. (Legacy scripts remain untouched for comparison).

Phase 6: Stepwise Bug Fixing (Pull Request #2)

1. After the pure Python 3 refactor is merged (ou in a separate branch built on top of it), address the bugs identified during the rewrite.
2. Fix each bug individually and step-by-step, with a dedicated test case/assertion proving the fix for each bug.
3. Deliverable: Open Pull Request Complete Python 3 rewrite with native prediction workflow and regression parity #2 containing incremental, isolated bug fixes.