Production Upgrade Roadmap

This roadmap tracks the production review upgrade for ChromoSort. Completed rows describe behavior now available in the current development branch; planned rows describe remaining follow-up work if new review needs appear.

Goal

The upgrade adds a paired review layer around the sequence-changing commands that most often need human judgment:

• fix
• scaffold
• gapfill

The existing fix, scaffold, and gapfill behavior should remain available as the default algorithmic path. Reviewed paths will add optional inputs that let users accept, reject, or add specific decisions when biological outliers need more control than a fully automatic run can provide.

Review Layer Design

chromo eval and chromo manual should become counterpart interfaces over the same underlying review-event model:

The intent is for both layers to expose the same evidence, candidate decisions, and row identifiers. eval should stay table-only. manual should remain exploratory, but each mode should also zoom directly to the candidate events that need review.

Eval Modes

chromo eval fix

Prepare an editable table for candidate contig-fix decisions. Rows should describe proposed split pieces or candidate breakpoint groups, with supporting evidence from:

• whole-genome reference-to-assembly alignments,
• optional GFA node context,
• optional long-read backmapping to the assembly.

The reviewed table should become an optional input to chromo fix, allowing the command to apply explicit accepted slices while preserving its current planner-driven behavior when no reviewed table is supplied.

chromo eval scaffold

Prepare an editable table for adjacent-contig scaffold decisions. Rows should describe candidate junctions, gaps, overlaps, order/orientation concerns, and graph or read support. Evidence should include:

• chromo sort assignment intervals,
• inferred reference-space gaps and overlaps,
• optional GFA direct edges or short paths,
• optional long-read bridges between contig ends.

The reviewed table should become an optional input to chromo scaffold, so users can pin down outlier junctions while leaving ordinary scaffold decisions algorithmic.

chromo eval gapfill

Prepare an editable table for graph-supported fill decisions. This should be a table-only counterpart to the existing gapfill planning behavior, expanded as needed to include long-read backmapping. Evidence should include:

• candidate GFA paths,
• GAF read-path support when available,
• Hi-C-like graph-node contacts when available,
• reference-placement PAF support,
• long-read evidence mapped back to the assembly.

The reviewed table should become an optional input to chromo gapfill, with the command revalidating accepted rows before applying sequence.

Manual Modes

chromo manual should evolve from one general review dashboard into task-specific review modes:

• chromo manual fix
• chromo manual scaffold
• chromo manual gapfill

Each mode should keep the useful “browse around and explore” feel, but it should open around a focused queue of candidate events. Selecting a row should zoom to the relevant contig, breakpoint, junction, or graph path while still allowing nearby alignments, graph neighborhoods, and contigs to be inspected.

Shared Review Events

A shared internal review-event model should keep eval and manual from drifting apart. A review event should carry:

• stable identifiers for the source FASTA records and candidate action,
• task type (fix, scaffold, or gapfill),
• proposed action and default acceptance state,
• evidence summaries from alignments, graph inputs, and long-read support,
• validation fields needed by the execution command,
• human-editable accept/reject and note fields.

The execution commands should validate reviewed tables against the current FASTA, assignments, graph paths, and settings before changing sequence. Rejected, deleted, stale, or invalid rows should fail safely or fall back to the current conservative behavior, depending on the command and mode.

Long-Read Backmapping Evidence

Long reads mapped back to the assembly should become a shared evidence source for the production upgrade. The first implementation should prefer a lightweight PAF-based reader to avoid adding heavy required dependencies. BAM or CRAM support can follow later as an optional capability.

The shared evidence layer should summarize:

• reads spanning candidate breakpoints,
• split or clipped read clusters near breakpoints,
• contig-end read bridges with orientation and estimated gap or overlap,
• coverage anomalies around candidate cuts or joins,
• concordance or conflict with GFA links and graph paths.

Implementation Phases

Guardrails

• Existing default behavior remains the default.
• Reviewed execution paths must be explicit.
• Table schemas should be stable and spreadsheet-friendly.
• Sequence-changing commands must revalidate reviewed rows before applying them.
• Ambiguous or stale evidence should remain reviewable rather than guessed.

Next Chapter: GAF Evidence And Modular Manual Panels

The next review upgrade should fully surface long-read GAF graph alignments across the same eval and manual task modes. GAF should be treated as a complementary evidence stream rather than a replacement for GFA or long-read PAF:

• GFA answers whether the graph topology permits a relationship.
• Long-read PAF answers whether reads support breakpoints or junctions in assembly-contig coordinate space.
• Long-read GAF answers whether reads traverse graph paths that support, disambiguate, or conflict with a proposed graph relationship.

The main product goal is communication. Users should be able to inspect four independent evidence panels when the corresponding inputs are provided, while the command-line eval tables expose compact summary columns for the same evidence.

Evidence Inputs

Each evidence stream should remain optional where possible. The dashboard should render only the panels backed by provided evidence, and eval should write . values for unavailable evidence rather than forcing unnecessary inputs.

Eval Mode Expansion

chromo eval fix, chromo eval scaffold, and chromo eval gapfill should all accept long-read GAF evidence.

For eval fix, GAF evidence should remain advisory. It should summarize graph traversal context near candidate split nodes or breakpoint-associated graph nodes, but PAF-to-assembly evidence should remain the primary coordinate-level support for breakpoint decisions.

For eval scaffold, GAF evidence should be first-class support. Scaffold junction rows should report whether reads traverse the direct GFA edge or the short graph path connecting adjacent contigs, whether support favors an alternate path, and whether graph traversal conflicts with the reference-space order.

For eval gapfill, GAF is already central to branch resolution. The next work should move GAF parsing and path-support helpers into a shared evidence module, then reuse the same summaries in the review-event table and manual dashboard.

Manual Dashboard Panels

Task-specific manual dashboards should expose a modular evidence layout for the selected event, contig, junction, or candidate path.

The current manual dashboard already has the alignment view, optional GFA context, and task-specific event queue. The next dashboard step is to split the selected-event evidence into these explicit panels instead of relying only on review-table columns and badges.

Executor Policy

The sequence-changing commands should remain conservative:

• chromo fix may consume GAF-derived review-table rows only when the reviewed table explicitly accepts the change; automatic fixing should still rely on existing coordinate-based logic.
• chromo scaffold may use GAF as report-only support or as reviewed-table context for accepted gap decisions, but it should not reorder, orient, or trim based on GAF alone.
• chromo gapfill can continue using GAF as a branch-support signal, with reviewed rows revalidated against the current GFA path before sequence is applied.

GAF Implementation Phases

Next Chapter: Architecture And Documentation Consistency

The architecture documentation now needs a publication-style refresh that describes not only what each algorithm does, but exactly where each algorithm, decision rule, data model, and evidence stream is used. The guiding question for reviewers should be:

Which subcommand, mode, or parameter activates this algorithm or data model?

The update should keep the existing methods-oriented architecture style: precise claims, traceable command boundaries, conservative descriptions of failure modes, and explicit links between code modules, CLI parameters, and user-facing artifacts. The README and user docs should then be checked against that architecture map so the project tells one coherent story.

Architecture Coverage Targets

Documentation Refresh Phases