Vocal2midi Rs Rewrite

---
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.