--- name: vocal2midi-rs-rewrite description: Coordinate the Vocal2Midi Python-to-Rust rewrite. Use when the user asks to continue, plan, route, re-cut, shard, implement, audit, promote, choose serial or coordinated-parallel execution, or select the next migration unit; when shared Burn gaps, dependency source expansion, capability coverage, or workflow may change the manifest inventory. --- # Vocal2Midi Rust Rewrite Drive the project-specific rewrite loop for Vocal2Midi. Treat `rewrite-in-rust/` as the durable control plane. ## Start Here 1. Confirm the current workspace is the Vocal2Midi repository. 2. Read these before making decisions: - `rewrite-in-rust/README.md` - `rewrite-in-rust/manifest.yaml` - `rewrite-in-rust/resources.md` - `rewrite-in-rust/notes.md` - `rewrite-in-rust/reference/glossary.md` - `rewrite-in-rust/records/` - `docs/architecture.md` - `docs/contributing.md` 3. Read source files and tests named by the selected unit. 4. Read the compiled DAG snapshot, graph revision, Git baseline, active locks, worktree assignments and integration waves when present. 5. If the task is dependency or seam setup, use `vocal2midi-rs-dep-bootstrap`. 6. If the task is implementation, use `vocal2midi-rs-unit-writer`. 7. If the task is review-only, use `vocal2midi-rs-review-gate`. Completion criterion: the selected path is grounded in manifest state and source truth, not memory. ## Discovery First Vocal2Midi is a cross-language dependency rewrite, not a mostly-Rust backend rewrite like mvsep-rs. Treat `manifest.yaml` units as a provisional inventory. Before choosing implementation work, check whether dependency expansion could change the unit boundary: - imports cross heavy Python package, native, FFI, model runtime, or vendored source boundaries - the unit depends on first-layer direct Python dependency behavior that should be read from `third_party/` before implementation - second-layer or deeper dependency behavior appears relevant, but no public-seam call path evidence has been recorded yet - the planned unit mixes several separately verifiable capabilities - a direct crate replacement looks broader than a narrow Rust implementation - a Rust crate covers useful lower-level behavior but differs from Python at the public API, resolver, constructor, formatting, or error-projection layer - a low-level native/compiler/runtime difference is being treated as behavior without proof that it reaches public outputs, memory/ABI contracts, persistence, security, or model/numeric correctness - fixtures or shared Rust data structures are missing - rollback is unclear after dependency expansion If any signal is present, route to `vocal2midi-rs-dep-bootstrap` before writer work. Re-cut planned units when that creates a smaller or more verifiable path. Do not treat dependency alignment as a binary choice between perfect crate parity and fully hand-written Rust. Dependency reuse and wheel rebuilding are complementary. The preferred decision paths are: 1. direct crate coverage when fixtures prove it; 2. partial crate reuse plus a fixture-bound semantic-delta adapter when Python source explains the semantic gaps; 3. narrow hand-written Rust for semantic gaps or capabilities the crate cannot safely own; 4. full hand-written replacement when it is the smaller or safer verified path, with a recorded tradeoff explaining why crate reuse plus adapter is worse. Completion criterion: continuing with the current unit boundary is justified, or the plan is routed to dependency/bootstrap discovery. ## Unit Selection - If the user names a unit, select only a dependency-ready node for that unit. - Otherwise compile the current manifest and select critical-path ready nodes whose dependencies, approvals, locks and capacity permit admission. - A selected unit may still be split, merged, renamed, deferred, or replaced after dependency discovery. - Manifest sharding does not determine scheduling. Artifact edges, owned paths, resource locks and capacity decide which unit phases can run concurrently. - Start with DAG dry-run. Enable parallel mutation only after explicit user opt-in, a clean/approved Git baseline, isolated worktrees, canonical shared prerequisites, an assigned coordinator and serialized Cargo build queue. - Do not skip the R0 behavior gate. - Do not promote a unit without its R0 behavior evidence, required reviews, and a rollback route. Completion criterion: the next unit and route are explicit. ## DAG And Git Coordination - Keep manifest declarations as source of truth and persist compiled graph snapshots. - Let workers propose graph patches; only the coordinator changes the canonical graph. - Allocate one worktree/branch per parallel mutating node and require an atomic candidate commit. - Admit disjoint nodes by critical path and capacity, not raw ready-node count. - Merge accepted candidates through coordinator-owned integration waves and run integration R0. - Invalidate downstream nodes and reviews when commit, graph revision or artifact digest changes. ## Behavior Verification Target Every unit uses Python/legacy behavior at a named public or application seam as its oracle. Record the observable inputs, outputs, errors, state changes and handoffs before writer work. Comparison is exact unless an existing public contract or explicit pre-implementation user decision records a model or numeric tolerance. For deep inference work, choose a seam that exposes model/config/weight loading, codec roundtrips, tensor shape/dtype/layout handoff, errors and application workflow without requiring framework internals to become migration targets. If the current unit cannot support independent Python/Rust comparison, move the seam outward, re-cut the unit, or keep the capability legacy-owned. Compilation or canonical Rust-to-Rust contracts cannot replace this behavior evidence. ## Source Boundary Borrow from py2rs: - behavior-first migration - reversible state - manifest-driven progress - writer/reviewer separation - one R0 behavior-parity gate before promotion Borrow from teach: - mission-grounded work - resources before memory - durable notes, references, and records - minimum scoped progression Do not borrow a fixed py2rs architecture. No PyO3, runtime router, CLI bridge, or subprocess bridge is introduced unless the unit's record explains why it fits Vocal2Midi. ## Rewrite Loop 1. Ground in state: read manifest, resources, records, selected sources, and existing tests. 2. Run the discovery check and re-cut provisional units when needed. 3. Define the unit's public boundary, current owner, target owner, `behavior_verification`, verification command, and rollback route. 4. Check the canonical shared dependency registry, then ensure dependency/bootstrap records exist before implementation when the unit needs new crates, fixtures, hand-written Burn gaps, or bridge/seam decisions. 5. Add Python/Rust behavior-parity fixtures at the declared seam before changing production paths. 6. Compile the DAG and admit a ready node with its exact Git/artifact inputs. 7. Run mutating nodes in isolated worktrees and collect atomic candidate commits. 8. Mark implemented-but-unreviewed work as `reimplemented`, not `verified`. 9. Run R0 first, then required review nodes serially per unit according to explicit role dependencies and risk priority. 10. Merge accepted candidates in an integration wave and run integration R0. 11. Promote only the exact reviewed/integrated snapshot when rollback remains clear. 12. Record reusable lessons and stale propagation in `rewrite-in-rust/records/`. Completion criterion: manifest state reflects reality and the next action is obvious. ## Non-Negotiables - Python/legacy public behavior is the oracle for every unit. A unit without an independently comparable seam remains legacy-owned or is re-cut before writer work. - GUI, Flask/Web handlers, and model inference remain legacy-owned unless a unit explicitly changes that boundary. - Runtime/control-plane code must not contain business logic. - A writer must not review its own work. - A reviewer must not patch production code. - A unit must never have concurrent review gates. Reviews of disjoint units may run concurrently only when their checks, report paths, and state writes cannot race. - Dependency alignment is by capability coverage, not package-name matching; partial crate coverage plus a Python-source-guided adapter is valid when it is smaller and more verifiable than fully hand-writing the lower layer. - Fewer Rust dependencies is not a success metric. Challenge unnecessary hand-written rewrites when a maintained crate can safely own a stable lower layer, and also allow full hand-written replacement when the dependency tradeoff is recorded and fixture-backed. - First-layer direct Python dependency sources are the normal local reference corpus. Second-layer or deeper source expansion requires public-seam call path evidence; lockfile transitivity alone is not enough. - Do not turn low-level native/compiler/runtime details into rewrite work unless they affect public behavior, memory/ABI contracts, persistence, security, or model/numeric correctness. - The initial module list is temporary; do not preserve it when dependency expansion proves a better boundary. - Shared Burn gaps, adapters, generated sources and fixture harnesses have one canonical project path and prerequisite owner. Never reimplement them under a second model shard. - `/tmp` and agent-private dependency copies are disposable research only and cannot be consumed by another unit. - Only a coordinator may modify shared Cargo manifests/lockfiles or schedule competing builds in coordinated parallel mode. - Only a coordinator may mutate the canonical graph/manifest, allocate worktrees, merge candidate commits, resolve conflicts or promote units. - Use uv Python 3.12.x for Python checks; do not use the system `python`. ## Completion Response Name the selected unit, route taken, manifest state changes, files changed, checks run, and remaining review roles.