TODO_IMPLEMENTATION_TRACKER.md

Legend

pending
[~] in progress
done
[!] blocked

Meta Tracking Discipline

Create a single authoritative tracker file in-repo.
Update this file after every material sub-task completion.
Keep explicit status for blockers, assumptions, and deferred items.
Ensure final pass marks all completed and explicitly lists remaining gaps.

A. FW-P2C-003 Native Accelerated Adapter Layer

A1. Discovery and API reconnaissance

Inspect frankentorch public APIs for runtime-safe tensor operations usable in ASR postprocessing path.
Inspect frankenjax public APIs for optional fallback/secondary acceleration path.
Identify a deterministic acceleration target that can be used without introducing unsafe code.
Define capability probe semantics: available, unavailable, degraded.
Define environment and feature flags controlling accelerator behavior.

A2. Interface design

Add accelerator abstraction module and trait(s).
Define AccelerationBackend enum (none, frankentorch, frankenjax).
Define typed input/output for acceleration pass.
Define error model for acceleration failures and fallback reasons.
Define observability fields to record chosen accelerator and fallback reason.

A3. Frankentorch implementation

Implement frankentorch-backed accelerator.
Add runtime availability probe for frankentorch path.
Ensure deterministic behavior for identical inputs.
Wire graceful fallback on runtime errors.

A4. Frankenjax implementation

Implement frankenjax-backed optional accelerator.
Add runtime availability probe for frankenjax path.
Ensure fallback ordering to frankentorch-first policy.
Wire graceful fallback on runtime errors.

A5. Pipeline integration

Insert acceleration stage into orchestrator after backend output normalization.
Ensure stage emits events for start/success/fallback/error.
Record accelerator metadata in final report.
Ensure acceleration stage preserves transcript semantics.

A6. Tests

Unit test backend selection policy and fallback cascade.
Unit test deterministic output for fixed synthetic segments.
Unit test report metadata when acceleration applied.
Unit test report metadata when acceleration skipped/fallback.

B. Real-Time Robot Mode Stage Streaming

B1. Event architecture

Refactor event log to support immediate event publication + final accumulation.
Introduce event sink abstraction for real-time emitters.
Preserve existing final report structure.

B2. CLI robot mode integration

Update robot run to stream stage events as they happen.
Keep schema stable and line-oriented NDJSON.
Ensure errors are emitted both as stage events and terminal run_error envelope.

B3. Non-robot flow compatibility

Keep normal transcribe output behavior unchanged.
Ensure persistence includes full event sequence identical to streamed order.

B4. Tests

Unit test sequence monotonicity for real-time events.
Unit test streamed events are present in persisted report.
Unit test error path emits terminal run_error.

C. FrankenTUI Run Status + Transcript Timeline

C1. Mandatory `$frankentui` skill first pass

Read /data/projects/frankentui/AGENTS.md fully.
Read /data/projects/frankentui/README.md fully.
Run mandatory cass archaeology commands from skill.
Review runtime architecture contract files listed by skill.
Capture key reusable patterns from skill references.

C2. TUI UX scope definition (for this repo)

Define shell layout: header, status bar, run list pane, transcript timeline pane, event log pane.
Define keyboard model (quit/help/focus switch/scroll/theme cycle where applicable).
Define tiny-terminal fallback layout behavior.
Define color/contrast strategy aligned with frankentui patterns.

C3. Implementation

Implement --features tui screen in src/tui.rs.
Integrate frankentui crate usage (not placeholder).
Render current run status summary.
Render transcript timeline with per-segment timing + speaker labels.
Render event stream pane with recent stage events.
Provide clear keyboard controls and on-screen hints.

C4. Data plumbing

Add TUI data source path (latest run from db or sample state when empty).
Handle no-runs state gracefully with actionable guidance.
Handle long transcripts via scrolling/clipping.

C5. Tests/build checks for TUI feature

Compile checks with --features tui.
Add at least one unit test covering TUI model/state transform.
Ensure default build remains unaffected when tui feature disabled.

D. Documentation and Contract Updates

Update README.md with new accelerator stage and real-time robot behavior.
Add robot NDJSON event examples including real-time stage lines.
Document TUI controls and feature flag usage.
Update architecture docs with acceleration stage and event sink model.
Update parity doc to reflect newly completed items.

E. Validation and Quality Gates

Run cargo fmt --check.
Run cargo check --all-targets.
Run cargo clippy --all-targets -- -D warnings.
Run cargo test.
Run feature build: cargo check --all-targets --features tui.
Run feature build: cargo check --all-targets --features gpu-frankentorch.
Run feature build: cargo check --all-targets --features gpu-frankenjax.

F. Finalization

Reconcile tracker status against actual code changes.
Summarize deliverables and residual risks.
Provide concrete next packets only if any required work remains.

S. Fresh-Eyes Audit Pass (2026-02-22)

S1. Audit scope and findings

Re-read all newly written/modified speculation pipeline code (src/streaming.rs, src/speculation.rs, src/robot.rs) with contract focus.
Cross-audit event contract against robot schema and required-field constants.
Identify concrete issues:
- transcript.partial payload schema mismatch in speculative pipeline events.
- Missing robot schema docs for emitted speculation events (confirm/retract/correct/speculation_stats).
- Zero-duration duration-loop path skipped cancellation checkpoint hook.
- Evidence-ledger correction-rate string matching brittle to decision-string variants.
- Speculation stats docs described means as “across corrections” despite all-window aggregation.

S2. Fixes applied

S3. Regression coverage

Added/updated tests to validate speculative event payload required fields.
Added zero-duration checkpoint behavior test.
Updated robot contract tests for expanded schema event set and required-field lists.
Added ledger capacity-zero behavior test.

S4. Quality gates

cargo fmt --check
cargo check --all-targets
cargo clippy --all-targets -- -D warnings
cargo test

T. Randomized Deep Audit Pass (2026-02-23)

T0. Execution Control

Create granular audit checklist for this pass before code changes.
Keep checklist updated after each material sub-task.
Reconcile checklist completion against concrete code/test evidence before handoff.

T1. Random Sampling + Flow Mapping

Generate randomized source-file sample from src/**/*.rs.
Select representative audit targets across backend/orchestrator/storage/robot/TTY layers.
Map outbound dependencies (use/called modules) for each selected target.
Map inbound callsites (rg references) for each selected target.
Build per-target execution-flow notes (entrypoints, side effects, invariants).

T2. Fresh-Eyes Critical Review

Audit sampled target #1 (build_native_segmentation in whisper_cpp_native.rs) — silent segment skip on inverted timestamps.
Audit sampled target #2 (run_stage_with_budget + PipelineCx::deadline in orchestrator.rs) — u64→i64 deadline overflow.
Audit sampled target #3 (decompress_chunk in tty_audio.rs) — zlib bomb DOS (no decompression size limit).
Audit sampled target #4 (persist_report_inner in storage.rs) — clean (parameterized SQL, transactional).
Audit sampled target #5 (run_complete_value in robot.rs) — clean (low-risk schema gap).
Trace adjacent imported/importing files for each discovered risk.

T3. Bug Confirmation + Fixes

Confirm each issue with direct code-path reasoning (and repro where applicable).
Implement deterministic, minimal fixes for confirmed defects only.
Avoid broad refactors not required for bug correction.
Preserve API contracts unless a bug requires contract correction.

T4. Test Reinforcement

Add/update unit tests covering each fixed bug path.
Add/update integration tests if bug spans module boundaries.
Ensure new assertions check invariant and failure behavior.

T5. Mandatory Quality Gates

cargo fmt --check
cargo check --all-targets
cargo clippy --all-targets -- -D warnings
cargo test (all tests pass via rch; e2e pipeline tests skip gracefully when ffmpeg is unavailable on worker PATH)

Blockers / Assumptions / Deferred

Blockers: none currently blocking implementation or validation.
Assumption: backend binaries/tools (whisper-cli, insanely-fast-whisper, diarization python stack, ffmpeg) are available in runtime environments where those backends are selected.
Deferred: frankentui path dependency warnings (ftui-layout, ftui-widgets) are upstream to /data/projects/frankentui; they do not block franken_whisper quality gates.

Live Notes

2026-02-22: Tracker initialized.
2026-02-22: Completed acceleration stage integration (frankentorch/frankenjax/CPU fallback) with metadata propagation.
2026-02-22: Completed real-time robot stage streaming and terminal envelopes (run_start, stage, run_complete, run_error).
2026-02-22: Replaced placeholder TUI with frankentui-powered runs/timeline/events screen.
2026-02-22: Added tests for stream sequence/order, robot envelopes, and acceleration metadata/priority.
2026-02-22: Quality gates all green (fmt, check, clippy -D warnings, test, feature checks, test --all-features).
2026-02-22: Hardened sync lock/atomicity/conflict semantics and added reject+overwrite sync conflict tests.
2026-02-22: Added adaptive backend shadow-routing evidence ledger with explicit loss/posterior/calibration/fallback terms.
2026-02-22: Added explicit stage *.error emission for ingest/normalize/backend/persist failures.
2026-02-22: Completed full docs-first archaeology pass (AGENTS.md, README.md, all spec/runbook docs) with explorer-assisted codebase synthesis.
2026-02-22: Added Section I (completed archaeology packet) and Section J (granular prioritized backlog from investigation findings).
2026-02-22: Ran cargo test --tests --no-run sanity check; confirmed integration-test drift in tests/cli_integration.rs (missing trace_id, evidence, timeout_ms, timeout fields).
2026-02-22: Reconciled integration tests with current model/CLI fields and updated stale orchestrator event-order expectation (orchestration.budgets pre-ingest event).
2026-02-22: Quality gates green after reconciliation (cargo fmt --check, cargo check --all-targets, cargo clippy --all-targets -- -D warnings, cargo test).
2026-02-22: Added robot error-code regression matrix test covering stable mappings across key FwError variants.
2026-02-22: Added explicit sync import referential integrity checks for segments.run_id/events.run_id with orphan-row rejection tests.
2026-02-22: Confirmed panic-safe sync lock lifecycle is implemented (SyncLock drop guard + failure-path lock-release tests).
2026-02-22: Aligned sync strategy docs to actual CLI conflict flag usage (--conflict-policy overwrite).
2026-02-22: Completed J0 packet (J0.0–J0.5 all checked) and re-ran quality gates + feature checks (tui, gpu-frankentorch, gpu-frankenjax).
2026-02-22: Feature checks pass for this repo; remaining warnings observed are upstream in /data/projects/frankentui crates.
2026-02-22: Completed J1/K4 remaining deltas: deterministic cancellation stage emission, cancellation evidence trail payload/count, robot envelope ordering integration test, and stage budget typed config-source parsing test.
2026-02-22: Added runtime segment conformance enforcement (segment-monotonic-v1) plus conformance unit tests for timestamp ordering/overlap policy.
2026-02-22: Incorporated cross-agent architecture feedback into core docs (engine-contract direction, explicit compatibility/conformance envelope, robust TTY protocol direction, GPU lifecycle risk surfacing).
2026-02-22: Quality gates rerun green after this packet (cargo fmt --check, cargo check --all-targets, cargo clippy --all-targets -- -D warnings, cargo test, feature checks for tui, gpu-frankentorch, gpu-frankenjax) using isolated target dir to avoid external Cargo lock contention.
2026-02-22: Added docs/conformance-contract.md and linked it in README Key Docs as the compatibility-oracle artifact for native-engine convergence packets.
2026-02-22: Final verification pass green on current revision: cargo test -q now reports 106 unit + 26 integration tests passing; feature checks remain green (only upstream warning noise from /data/projects/frankentui).
2026-02-22: Added executable compatibility comparator (SegmentCompatibilityTolerance + SegmentComparisonReport) with tests covering timestamp tolerance, text drift, and speaker mismatch requirements.
2026-02-22: Added fixture-driven conformance harness (tests/conformance_harness.rs) with baseline and drift-failure JSON fixtures under tests/fixtures/conformance/.
2026-02-22: Integrated concurrent RunReport.replay model evolution end-to-end (orchestrator replay hash capture + runtime metadata wiring) and reconciled initializer/test expectations.
2026-02-22: Latest full gate pass on current tree: cargo fmt --check, cargo check --all-targets, cargo clippy --all-targets -- -D warnings, cargo test -q (1052 unit, 43 integration, 2 replay-envelope, 5 recovery-smoke, 2 conformance-harness tests all green), plus feature checks (tui, gpu-frankentorch, gpu-frankenjax) green; only upstream warnings remain in /data/projects/frankentui.
2026-02-22: Added acceleration.context stage telemetry payload for replay/debug (requested GPU device, flash-attention intent, selected acceleration backend/mode, feature gates) as partial K14.6 delivery.
2026-02-22: Resolved enum-value drift in CLI integration tests (--backend whisper-cpp), then revalidated full gate suite green on current revision.
2026-02-22: Current gate snapshot: cargo test -q now reports 1059 unit + 48 integration + 2 replay-envelope + 5 recovery-smoke + 2 conformance-harness tests passing; feature checks remain green (warnings in /data/projects/frankentui and test-only unused import warning in src/robot.rs under non-default feature combos).
2026-02-22: Cleaned robot test-only import warning under feature checks (src/robot.rs), reran full gates + feature checks; latest snapshot: 1064 unit + 48 integration + 2 replay-envelope + 5 recovery-smoke + 2 conformance-harness tests passing, with only upstream /data/projects/frankentui warnings remaining.
2026-02-22: Closed closure packet M by landing ingest↔backend parity integration tests (file/stdin/mic envelopes) and deterministic TTY retransmit planning (tty-audio retransmit-plan) with protocol + README documentation updates.
2026-02-22: Explorer-assisted parity archaeology identified two remaining CLI parity deltas to track explicitly: insanely-fast diarization token CLI override (currently env-only) and insanely-fast transcript-path override.
2026-02-22: Re-read AGENTS.md and README.md fully, then reconciled explorer backlog against current code/tests/docs before reopening implementation work.
2026-02-22: Fixed gpu-frankentorch feature compile drift by replacing removed ft-api tensor_layer_norm call with deterministic CPU-fallback error path (src/accelerate.rs), and resolved sync test accessor drift in src/sync.rs.
2026-02-22: Closed P2.2, P2.5, and P4.4 with integration/unit coverage; reconciled P4/P5 status against concrete routing-contract + sync/recovery evidence.
2026-02-22: Re-ran full quality matrix on current tree (cargo fmt --check, cargo check --all-targets, cargo clippy --all-targets -- -D warnings, cargo test, cargo check --all-targets --features tui, cargo check --all-targets --features gpu-frankentorch, cargo check --all-targets --features gpu-frankenjax) with all checks passing (non-fatal warning noise remains in /data/projects/frankentui and src/tui.rs under --features tui).
2026-02-22: Added NativeEngineRolloutStage parsing helpers (as_str/parse) in src/conformance.rs with new unit coverage for named/numeric stage parsing.
2026-02-22: Wired rollout-stage gating into backend selection (src/backend/mod.rs) via FRANKEN_WHISPER_NATIVE_ROLLOUT_STAGE, including deterministic static-order forcing for shadow|validated|fallback and explicit routing evidence fields (native_rollout_stage, native_rollout_forced_static_order).
2026-02-22: Expanded lifecycle/rollout contract docs (docs/engine_compatibility_spec.md, docs/native_engine_contract.md) and README env overrides to document runtime rollout controls and stage-event contract invariants.
2026-02-22: Re-ran full mandatory quality matrix after P3.1 rollout-lifecycle edits; all checks passed on current tree.
2026-02-22: Closed P3.1.4 by extending replay packs with tolerance_manifest.json (src/replay_pack.rs) and adding tests for rollout-stage extraction, serialization, and deterministic pack contents.
2026-02-22: Re-ran full mandatory quality matrix after replay-pack/tolerance-manifest edits; all checks passed (current cargo test snapshot: 1901 tests passed, with only expected ignored fixture-generation tests).
2026-02-22: Completed native pilot execution packet for all three backends (src/backend/whisper_cpp_native.rs, src/backend/insanely_fast_native.rs, src/backend/whisper_diarization_native.rs) and wired runtime native/bridge dispatch with deterministic fallback + replay identity capture (src/backend/mod.rs, src/orchestrator.rs).
2026-02-22: Expanded bridge-vs-native conformance corpus (tests/fixtures/conformance/corpus/hello_world_bridge_native_pairs.json) and added native golden artifacts (tests/fixtures/golden/*_native_output.*).
2026-02-22: Upgraded conformance harness gate to enforce tolerance + invariant + replay-field presence and emit machine-readable artifact bundle at target/conformance/bridge_native_conformance_bundle.json (tests/conformance_harness.rs).

G. Active Execution Packet (2026-02-22) — S1 + S2 + A1

G0. Granular Control Plane

Re-audit current src/ state before edits (detected partial S1 + acceleration work already landed).
Keep this tracker updated after every material sub-task in this packet.
Ensure each completed item links to concrete code/tests/docs updates.
Final pass: close all completed boxes and list unresolved blockers explicitly.

G1. S1 Real-Time Robot Stage Streaming Hardening

G1.1 Event-flow correctness

Confirm stage events are streamed during execution (not only post-completion).
Add explicit stage error emission (*.error) in orchestrator failure paths (ingest/normalize/backend/persist).
Ensure terminal run_error envelope remains emitted in robot mode on failures.
Ensure streamed stage ordering is monotonic and stable by single-sequencer contract.

G1.2 Persistence + stream consistency

Verify persisted events sequence matches streamed sequence contractually.
Add regression test for monotonic sequence behavior.
Add regression test asserting persisted events preserve streamed order semantics.

G1.3 Robot contract tests

Add unit test for run_error envelope schema.
Add/adjust tests for stage + completion envelope compatibility.

G2. S2 SQLite ↔ JSONL One-Way Sync Commands

G2.1 CLI/command surface

Add sync export-jsonl command.
Add sync import-jsonl command.
Add explicit conflict policy flag (reject|overwrite) for import.
Keep command output machine-readable and deterministic.

G2.2 Locking and atomicity

Implement exclusive sync lock guard at .franken_whisper/locks/sync.lock.
Implement stale-lock handling (PID/timestamp checks + archival).
Enforce one sync operation at a time.
Ensure lock release on all exit paths.

G2.3 Export pipeline (`db -> jsonl`)

Export runs.jsonl deterministically.
Export segments.jsonl deterministically.
Export events.jsonl deterministically.
Write channels atomically via temp + fsync + rename.
Emit manifest.json with schema/export versions, row counts, checksums.

G2.4 Import pipeline (`jsonl -> db`)

Validate manifest presence + version compatibility.
Parse channels deterministically and replay in order (runs, segments, events).
Implement upsert semantics with explicit conflict policy behavior.
Log conflicts to sync_conflicts.jsonl.
Wrap import in transactional commit/rollback boundary.

G2.5 Storage integration support

Add storage/data-layer support needed for full sync export/import replacement semantics.
Ensure overwrite policy can safely replace an existing run atomically.
Ensure import preserves event sequence and segment indexing invariants.

G2.6 Sync tests

Add export test (artifacts + manifest correctness).
Add roundtrip import test into fresh DB.
Add conflict reject test with sync_conflicts.jsonl artifact.
Add overwrite policy test.

G3. A1 Adaptive Backend Routing (Shadow Mode + Evidence Ledger)

G3.1 Shadow decision model

Add explicit state extraction (duration bucket, diarize/translate hints, availability).
Add explicit action set (candidate backend start choices/order).
Add explicit loss matrix terms (latency, quality proxy, failure risk).
Add posterior/confidence computation terms per backend.
Add calibration score computation and deterministic fallback trigger.

G3.2 Evidence artifact

Emit machine-readable shadow-routing evidence event before backend execution.
Include static order vs recommended order and fallback trigger in evidence payload.
Persist evidence via run events so it lands in SQLite.
Add warnings when fallback trigger or significant policy divergence occurs.

G3.3 Shadow-mode safety

Keep execution policy deterministic/static while in shadow mode.
Ensure no behavior regressions for explicit backend selection.
Add unit tests for evidence payload shape + fallback trigger logic.

G4. Documentation + parity updates for this packet

Update README.md with real-time robot streaming and sync command usage.
Update README.md backend notes to describe shadow adaptive routing ledger.
Update FEATURE_PARITY.md phase checklist to reflect completed S1/S2/A1 work.
Update architecture docs (PROPOSED_ARCHITECTURE.md) for event sink + sync mechanics + shadow routing.

G5. Mandatory quality gates and handoff

Run cargo fmt --check.
Run cargo check --all-targets.
Run cargo clippy --all-targets -- -D warnings.
Run cargo test.
Run feature check cargo check --all-targets --features tui.
Run feature check cargo check --all-targets --features gpu-frankentorch.
Run feature check cargo check --all-targets --features gpu-frankenjax.
Final reconciliation: tracker vs actual code/docs/tests completed.

H. Active Execution Packet (2026-02-22) — Full User Request (All 4 Streams)

H0. Control and Tracking

Create this packet section with full granular scope and keep it authoritative.
Update this tracker after every material code/doc/test change.
Keep explicit mapping from each request item to code/docs/tests touched.
Final tracker reconciliation: every unchecked item is either done or explicitly blocked.

H1. Sync CLI + SQLite/JSONL Ops Hardening

H1.1 Surface and contract audit

Re-verify sync export-jsonl and sync import-jsonl CLI behavior against SYNC_STRATEGY.md.
Ensure output payloads are deterministic and machine-readable (JSON only, stable fields).
Ensure import conflict policy remains explicit (reject|overwrite) with safe default.

H1.2 Locking and atomicity hardening

Ensure sync lock release is guaranteed on all code paths (success + error).
Ensure stale/corrupt lock archival behavior is deterministic and tested.
Ensure atomic writes use temp + fsync + rename semantics for all sync artifacts.

H1.3 Import/export correctness hardening

Validate manifest/schema/checksum failure paths provide clear actionable errors.
Ensure conflict artifact (sync_conflicts.jsonl) is always produced on reject conflicts.
Ensure overwrite semantics preserve run/segment/event invariants end-to-end.

H1.4 Sync tests

Add/adjust tests for lock lifecycle correctness and release on failure.
Add/adjust tests for conflict artifact behavior and deterministic import ordering.
Add/adjust tests for manifest/checksum/schema validation edge paths.

H2. Asupersync Cancel-Correct Orchestration Upgrade

H2.1 Stage budget model

Define explicit stage budget config (state space + defaults + env overrides).
Emit a machine-readable orchestration budget event at run start.
Ensure each stage has deterministic timeout handling policy.

H2.2 Budgeted stage execution

Execute blocking stage work through asupersync budgeted wrappers.
Enforce per-stage timeout envelopes and map timeout to deterministic error codes.
Ensure timeout/cancel events are emitted with explicit stage, budget, and reason.

H2.3 Fallback safety + orphan prevention

Ensure timeout behavior yields conservative deterministic fallback/error path.
Ensure no orphan background tasks are left after timeout/error paths.
Ensure final run report persists the complete stage evidence trail.

H2.4 Tests for orchestration guarantees

Add unit tests for stage timeout mapping and emitted error codes.
Add unit tests for budget parsing/env override behavior.
Add unit tests for deterministic fallback trigger behavior under timeout pressure.

H3. Backend Parity + Streaming Ergonomics Hardening

H3.1 Backend parity deltas

Add missing option forwarding where safely available for backend adapters.
Improve diarization segment normalization resilience (speaker/timestamp/text edge cases).
Ensure backend diagnostics output includes clear availability + prerequisite signals.

H3.2 Streaming ergonomics

Ensure robot stage stream includes explicit timeout/cancel error stages.
Ensure stage codes/messages are consistent and machine-contract stable.
Ensure warnings capture policy divergence/fallback reasons deterministically.

H3.3 Tests for backend/streaming hardening

Add/adjust backend parser tests for diarization edge payloads.
Add/adjust robot stream tests for timeout/cancel stage emission.
Add/adjust tests for stable stage code/message contracts.

H4. Frankentui-Style Planning Methodology Artifacts (for this repo)

H4.1 Create architecture-operations docs

Add docs/operational-playbook.md adapted for franken_whisper phase gates.
Add docs/master-todo-bead-map.md mapping tracker packets to bead-style units.
Add docs/definition_of_done.md with explicit quality and contract gates.
Add docs/risk-register.md with risks, mitigations, test evidence, and fallback triggers.

H4.2 Wire docs into existing project narrative

Update README.md key docs section to include the new methodology docs.
Cross-reference new docs from relevant spec docs where appropriate.
Ensure terminology aligns with AGENTS contract and current implementation reality.

H5. Final Validation + Handoff

Run cargo fmt --check.
Run cargo check --all-targets.
Run cargo clippy --all-targets -- -D warnings.
Run cargo test.
Run cargo check --all-targets --features tui.
Run cargo check --all-targets --features gpu-frankentorch.
Run cargo check --all-targets --features gpu-frankenjax.
Update this tracker with final results and explicit residual risks/gaps.

H6. Explicit Request-to-Artifact Mapping

Sync CLI + sync hardening mapped to: src/sync.rs, src/cli.rs, src/main.rs, src/process.rs, tests/cli_integration.rs.
Asupersync orchestration upgrade mapped to: src/orchestrator.rs, src/error.rs, src/process.rs.
Backend parity/streaming hardening mapped to: src/backend/mod.rs, src/backend/insanely_fast.rs, src/backend/whisper_cpp.rs, src/backend/whisper_diarization.rs, src/orchestrator.rs.
Frankentui-style methodology docs mapped to: docs/operational-playbook.md, docs/master-todo-bead-map.md, docs/definition_of_done.md, docs/risk-register.md, README.md, PLAN_TO_PORT_WHISPER_STACK_TO_RUST.md, PROPOSED_ARCHITECTURE.md.
Residual risk note recorded: upstream frankentui dependency warnings persist during --features tui checks (non-blocking for this repo).

I. Active Execution Packet (2026-02-22) — Full Archaeology + Methodology Assimilation

I0. Control Plane and Explicit Scope

Confirm user objective: full comprehension of AGENTS+README, architecture, methodology, and actionable next work map.
Keep this tracker as the single authoritative ledger for investigation tasks and discovered follow-up work.
Preserve non-destructive discipline during investigation (read-only exploration, no file deletion, no repo rewrites).
Record concrete evidence for each completion item (file paths, key modules, and command-driven inspection).

I1. Mandatory Documentation-First Pass (Per AGENTS + Skill Contract)

I2. Skill-Governed Investigation Workflow

Load codebase-archaeology skill and follow documentation-first + entry-point-first flow.
Load comprehensive-codebase-report skill and use report-oriented synthesis structure.
Use explorer agents for codebase excavation (core pipeline, storage/sync, CLI/TUI/TTY, docs parity alignment).
Collect explorer findings and close agent sessions cleanly.
Cross-validate explorer output with direct source inspection in local files.

I3. Repository Orientation and Entry Surfaces

Enumerate top-level repository layout and module inventory.
Identify Rust crate entry points (src/main.rs, src/lib.rs) and command routing model.
Enumerate all CLI command surfaces and subcommands in src/cli.rs.
Enumerate compile-time feature gates (tui, gpu-frankentorch, gpu-frankenjax).
Enumerate integration test and unit test locations relevant to architecture guarantees.

I4. Core Architecture and Data-Flow Comprehension

Trace run lifecycle end-to-end: input materialization -> normalization -> backend -> acceleration -> persist -> emit.
Confirm real-time stage event streaming path and persisted event ordering contract.
Map orchestrator responsibilities (FrankenWhisperEngine, PipelineCx, EventLog) and cancellation checkpoints.
Map backend selection policy: static auto order + adaptive shadow-routing evidence model.
Map typed domain surface (TranscribeRequest, TranscriptionResult, RunReport, RunEvent, StoredRunDetails).
Map storage schema and persistence semantics (runs, segments, events).
Map sync export/import execution including lock handling, manifest validation, checksums, and conflicts.

I5. Interface and Ergonomics Comprehension

Confirm robot-mode envelope contract (run_start, stage, run_complete, run_error) and line orientation.
Confirm robot backends diagnostics payload shape and environment override discoverability.
Confirm TUI behavior, focus model, refresh cadence, and tui feature-gate fallback behavior.
Confirm low-bandwidth TTY audio prototype protocol (μ-law + zlib + base64 NDJSON frame stream).
Confirm current machine-vs-human output split and where strict robot ergonomics are/are not satisfied.

I6. Methodology and Intent Comprehension (How This Project Is Meant To Be Built)

Confirm spec-first workflow ordering and non-ad-hoc implementation rule from AGENTS contract.
Confirm SQLite canonical-state + one-way JSONL adjunct contract and operational runbook coupling.
Confirm “alien-artifact” adaptive-controller requirements and deterministic fallback requirement.
Confirm project mission as synthesis (not line translation) across three legacy codebases plus FrankenSuite integrations.
Confirm the dual product shape: embeddable library + standalone CLI/robot + optional human TUI.

I7. Gap Discovery and Prioritized Follow-Up Backlog Synthesis

Identify architecture gaps still open vs declared contracts.
Identify sync-spec mismatches and integrity hardening opportunities.
Identify backend parity gaps by adapter and option forwarding coverage.
Identify orchestration/cancellation hardening gaps around stage-budget semantics.
Identify robot-contract ergonomics and schema durability gaps.
Materialize findings into the granular prioritized backlog in Section J below.

I8. Session Completion for This Packet

Produce concise architecture/intent mental model for user handoff.
Produce explicit TODOs with completion states and clear pending ownership.
Record residual risk set discovered during investigation.
Keep all investigation tasks in this packet closed ([x]) before handoff.

J. Post-Investigation Granular Backlog (Priority-Ordered)

J0. Critical Contract and Correctness Deltas

J0.0 Validate top-priority drift by compiling integration tests and capture concrete compiler diagnostics.
J0.1 Reconcile integration tests with current public model fields (trace_id, evidence, timeout_ms) in tests/cli_integration.rs.
J0.2 Add regression test ensuring robot_error_code() mappings stay stable across error variants.
J0.3 Ensure sync lock lifecycle is panic-safe (RAII/drop guard or equivalent) so lock release is guaranteed.
J0.4 Add explicit referential integrity validation during import (segments.run_id and events.run_id must exist in runs).
J0.5 Align sync strategy docs/CLI flags (--conflict-policy vs documented overwrite control wording) to remove operator ambiguity.

J1. Asupersync Cancel-Correct Packet (Phase 4 open item)

J1.1 Define explicit stage budget schema (defaults + env overrides + typed config source).
J1.2 Emit a budget declaration stage event at run start for deterministic replay/audit.
J1.3 Wrap blocking stage operations under budget-aware orchestration wrappers.
J1.4 Convert deadline exceedance paths to deterministic stage-level timeout codes/events.
J1.5 Ensure no orphaned background subprocesses remain on timeout/cancel paths.
J1.6 Persist cancellation evidence trail into final run report and stage stream.
J1.7 Add unit tests for stage timeout/error-code mapping and cancellation event emission.
J1.8 Add unit tests for budget env parsing/override behavior and invalid input handling.

J2. Backend Parity Packet Completion (Phase 3 open items)

J2.1 Whisper.cpp adapter parity audit vs legacy CLI surface (language/task/output/timestamp controls). (Completed: 12 new flags added + bug fix.)
J2.2 Insanely-fast adapter parity audit (batch/chunk/timestamp/task controls and defaults). (Covered: K5.2 + 13 build_args tests.)
J2.3 Diarization adapter parity hardening for segment extraction and speaker normalization edge cases. (Covered: 43 whisper_diarization tests including SRT parsing, speaker extraction, malformed blocks.)
J2.4 Add explicit line-in/stream behavior envelope parity tests for ingest + backend interactions. (Covered: transcribe_file_input_crosses_ingest_normalize_backend_with_stub_whisper_cpp, transcribe_stdin_input_crosses_ingest_normalize_backend_with_stub_whisper_cpp, transcribe_mic_line_in_input_crosses_ingest_normalize_backend_with_stub_whisper_cpp.)
J2.5 Add adapter-level diagnostics for unsupported flags/options to keep failures explicit and deterministic. (Covered: K5.5 diagnostics() with unsupported_options arrays.)
J2.6 Expand adapter tests for malformed/missing artifacts and mixed-format output payloads. (Covered: 30+ malformed-artifact tests in backend/mod.rs + whisper_diarization.rs.)

J3. Robot-Mode Ergonomics and Schema Stability

J3.1 Replace/augment hard-coded robot schema sample with generated/validated schema source of truth. (addressed: schema_examples_satisfy_their_own_required_fields validates examples against declared required fields; schema_declares_required_fields_for_each_event_type verifies structure)
J3.2 Add contract test asserting every streamed stage line carries required stable fields. (Covered: 8 robot.rs contract tests for required fields, field types, schema self-validation.)
J3.3 Add stable machine-readable runs listing mode (e.g., NDJSON/JSON output option) for automation. (Covered: runs --format json|ndjson + integration tests runs_command_parses_json_format / runs_command_parses_ndjson_format.)
J3.4 Ensure timeout/cancel stage events are always emitted before terminal run_error. (verified: run_pipeline_emits_checkpoint_cancelled_stage_with_evidence confirms cancellation stage events emitted before error return; streamed_event_order_matches_persisted_event_order verifies event ordering)
J3.5 Add golden tests for stage code/message compatibility across known pipeline failure classes. (Covered: stage_failure_code_for_all_error_variants and stage_failure_message_for_all_error_classes in orchestrator tests — exhaustive coverage of all FwError variants.)

J4. Sync and Recovery Operational Hardening

J4.1 Add tests for stale/corrupt lock archival naming and deterministic behavior. (Covered: stale_lock_archive_name_follows_deterministic_pattern, corrupt_lock_is_archived_and_replaced, stale_lock_is_archived_before_new_lock_is_granted.)
J4.2 Add tests for import behavior when conflict file write itself fails. (Covered: import_surfaces_error_when_conflicts_file_cannot_be_written — unix-only permission test.)
J4.3 Add tests for manifest schema major mismatch and minor compatibility expectations. (Covered: import_rejects_major_schema_version_mismatch, import_accepts_backward_compatible_minor_schema_version, validate_schema_version_* unit tests.)
J4.4 Add tests for row-count mismatch behavior when conflicts are present vs absent. (Covered: import_row_count_mismatch_errors_when_no_conflicts_present, import_row_count_mismatch_is_deferred_when_conflicts_exist.)
J4.5 Add recovery smoke scripts/checklists that validate runbook paths using synthetic fault fixtures. (covered: 5 tests in tests/recovery_smoke.rs: round_trip_snapshot_restore, failed_import_preserves_existing_db_state, export_recovers_from_stale_lock, import_conflict_emits_conflicts_artifact, rebuild_fresh_db_matches_snapshot_expectations)

J5. Deterministic Replay Envelope Uplift (Alien Recommendation Alignment)

J5.1 Persist normalized input hash into run-level metadata. (implemented: ReplayEnvelope.input_content_hash populated via sha256_file in orchestrator pipeline)
J5.2 Persist backend command identity/version metadata for each backend execution. (implemented: ReplayEnvelope.backend_identity + backend_version populated from runtime_metadata)
J5.3 Persist output payload hash for replay/regression comparisons. (implemented: ReplayEnvelope.output_payload_hash populated via sha256_json_value in orchestrator pipeline)
J5.4 Add replay-comparison helper that flags semantic drift for same input/config. (implemented: conformance::ReplayComparisonReport with within_tolerance(), tested in replay_comparison_within_tolerance_checks_all_fields + integration test replay_comparator_flags_semantic_drift)
J5.5 Add tests for replay envelope completeness and hash determinism. (Covered: 14 replay_pack tests including write_and_reread_pack_integrity, env_snapshot_without_backend_info, manifest/repro_lock serde round-trips, plus storage replay_envelope_defaults_round_trip.)

J6. Low-Bandwidth TTY Relay Hardening (Prototype -> Robust Mode)

J6.1 Add frame integrity checks beyond JSON parse/base64 decode (checksum and/or per-frame hash). (Covered: CRC32 + SHA-256 integrity checks implemented with 47 tty_audio tests including decode_passes_integrity_when_crc_correct, decode_detects_sha256_integrity_failure, crc32_is_deterministic.)
J6.2 Add sequence-gap detection and explicit gap error reporting. (Covered: decode_detects_sequence_gaps_as_error, retransmit_candidates tests.)
J6.3 Define retransmit/recovery policy for missing/corrupt frames in constrained PTY flows. (Covered: retransmit-plan artifact model + CLI + tests over mixed gap/corrupt windows.)
J6.4 Add tests for out-of-order frames, duplicate frames, and missing frame windows. (Covered: decode_out_of_order_frames_fails, decode_detects_duplicate_frames_as_error, decode_skip_missing_policy_recovers_gap, decode_skip_missing_policy_drops_corrupt_frame_and_continues.)
J6.5 Document robust-mode protocol versioning and compatibility rules. (Covered: docs/tty-audio-protocol.md robust-mode + retransmit handshake section.)

J7. TUI and Human-Mode Reliability Follow-Ups

J7.1 Add tests for run selection and scroll behavior against larger synthetic run/event sets. (covered by tui tests: app_handles_large_run_sets, large_dataset_120_runs_caps_at_runs_limit, single_run_with_2000_events, page_movement_clamps_at_boundaries)
J7.2 Add smoke coverage for empty-db and transient DB-open failure UX paths. (covered by tui tests: app_empty_db_and_event_volume_paths_are_stable, app_reports_transient_db_open_failures_and_warning_legend)
J7.3 Validate TUI refresh behavior under high event volume to prevent UI lag/regressions. (covered by tui test: app_handles_large_run_sets_selection_and_refresh_cycles)
J7.4 Add operator-facing legend for warning semantics (fallback/divergence) where practical. (covered by tui test: warning_legend_content verifies fallback/divergence/deterministic)

J8. Docs and Planning Artifact Completion

J8.1 Add docs/operational-playbook.md linked to current phase gates and rollback strategy. (completed in H4.1)
J8.2 Add docs/master-todo-bead-map.md mapping packets/tasks to issue units. (completed in H4.1)
J8.3 Add docs/definition_of_done.md with hard acceptance criteria per packet class. (completed in H4.1)
J8.4 Add docs/risk-register.md with severity, mitigation, and evidence status. (completed in H4.1)
J8.5 Update README Key Docs and spec cross-links to include new planning/operations artifacts. (completed in H4.2)

J9. Validation Gates for Each Future Execution Packet

J9.1 Run cargo fmt --check after substantive edits.
J9.2 Run cargo check --all-targets after substantive edits.
J9.3 Run cargo clippy --all-targets -- -D warnings after substantive edits.
J9.4 Run cargo test (including integration tests) after substantive edits.
J9.5 Run feature checks: --features tui, --features gpu-frankentorch, --features gpu-frankenjax.
J9.6 Record quality-gate outcomes and residual risk deltas back into this tracker.

K. Canonical Backlog (Reconciled 2026-02-22; supersedes stale J snapshot)

K0. Session Execution Control (Current Turn)

K0.1 Read AGENTS.md end-to-end and extract all hard constraints.
K0.2 Read README.md end-to-end and validate current product-shape claims.
K0.3 Run explorer-based architecture investigation across src/, tests/, and docs.
K0.4 Run legacy-parity investigation across all three legacy_* folders.
K0.5 Reconcile discovered implementation state against tracker items.
K0.6 Record this canonical reconciliation section so future packets start from accurate status.

K1. Understanding and Architecture Assimilation (Completed)

K1.1 Confirm entrypoints and command routing (src/main.rs, src/cli.rs).
K1.2 Confirm stage pipeline shape (ingest -> normalize -> backend -> acceleration -> persist -> emit).
K1.3 Confirm robot-mode stream contract (run_start, stage, run_complete, run_error).
K1.4 Confirm storage contract (runs, segments, events) and query/readback paths.
K1.5 Confirm sync contract implementation (export-jsonl, import-jsonl, lock + manifest + checksum paths).
K1.6 Confirm stage-budget orchestration and timeout typing via asupersync.
K1.7 Confirm backend diagnostics/readiness and shadow-routing evidence emission.
K1.8 Confirm optional TUI and TTY-audio prototype surfaces and feature gates.

K2. Legacy Fusion Assimilation (Completed)

K2.1 Map legacy_whispercpp capability set to Rust adapter coverage and gaps.
K2.2 Map legacy_insanely_fast_whisper capability set to Rust adapter coverage and gaps.
K2.3 Map legacy_whisper_diarization capability set to Rust adapter coverage and gaps.
K2.4 Capture adapter-surface parity deltas that remain unsurfaced in Rust CLI/API.
K2.5 Capture dependency/compatibility drift risk from external binary/script reliance.

K3. Highest-Priority Correctness Deltas (Open)

K3.1 Add full regression test matrix for FwError::robot_error_code() across all error variants.
K3.2 Add explicit import referential-integrity validation (segments.run_id, events.run_id -> runs.id) before commit.
K3.3 Align sync strategy docs and CLI terminology (--conflict-policy reject|overwrite) to remove stale wording (upsert / --force-conflict-policy).
K3.4 Ensure checkpoint/deadline cancellation always emits a deterministic stage event before terminal run_error.
K3.5 Persist explicit cancellation evidence details into final run artifacts when cancellation occurs mid-pipeline.

K4. Asupersync Orchestration Packet (Mostly Complete; Remaining Open)

K4.1 Define stage-budget defaults and env overrides.
K4.2 Emit orchestration budget declaration event at run start.
K4.3 Execute stage work under budget-aware orchestration wrappers.
K4.4 Map timeouts to deterministic stage timeout codes.
K4.5 Terminate timed-out subprocesses in command runner.
K4.6 Add baseline timeout/budget parsing tests.
K4.7 Add explicit tests proving cancellation stage-event ordering relative to terminal robot envelopes.
K4.8 Add explicit tests proving cancellation evidence persistence semantics.

K5. Backend Parity Packet (Open)

K5.1 Whisper.cpp adapter parity audit and selective flag-surface expansion. (Added: threads, processors, no-gpu, prompt, carry-initial-prompt, no-fallback, suppress-nst, offset-ms, duration-ms, audio-ctx, word-threshold, suppress-regex. Fixed -ns → -nth bug.)
K5.2 Insanely-fast adapter parity audit and selective flag-surface expansion.
K5.3 Diarization adapter edge-case hardening for speaker/timestamp parsing. (Covered: 14+ edge-case tests including extract_speaker_prefix, matches_short_speaker_label, is_speaker_label, parse_srt_segments, malformed SRT blocks, timestamp overflow/negative, mixed valid/corrupt blocks.)
K5.4 Add line-in/stream ingest parity tests crossing ingest and backend boundaries. (Covered by unix integration stub backend tests for file/stdin/mic envelopes.)
K5.5 Add deterministic diagnostics for unsupported adapter options.
K5.6 Expand adapter malformed-artifact and mixed-format output tests. (Covered: 30+ tests for empty/null/string/number/boolean/array roots, missing text, missing timestamps, mixed malformed payloads, deeply nested garbage, whitespace-only words, integer coercion, negative timestamps, infinity, large arrays, word-level chunks.)
K5.7 Add explicit CLI-level hf-token override for insanely-fast diarization path (retain env fallback precedence semantics). (Implemented: --hf-token in CLI, request-level override in BackendParams, adapter precedence request override -> env fallback, readiness checks updated, integration tests added.)
K5.8 Add insanely-fast transcript-path override option and wire into adapter artifact contract/tests. (Implemented: --transcript-path in CLI, request-level path override in BackendParams, insanely-fast adapter output-path selection + directory creation, unit/integration tests added.)

K6. Robot Contract and Automation Ergonomics (Open)

K6.1 Replace static schema example with generated/validated schema source of truth.
K6.2 Add contract tests asserting required stable fields for every streamed stage line.
K6.3 Add machine-readable mode for runs listing (JSON/NDJSON output option).
K6.4 Add golden tests for stage code/message compatibility across major failure classes.
K6.5 Add tests asserting timeout/cancel stage events are emitted before terminal run_error in all failure paths.

K7. Sync and Recovery Hardening (Partially Complete)

K7.1 Add stale/corrupt lock archival behavior tests.
K7.2 Add lock release safety via drop guard semantics.
K7.3 Add import behavior tests for conflict-file write failures.
K7.4 Add manifest compatibility tests for major mismatch and backward-compatible minor expectations.
K7.5 Add row-count mismatch tests across conflict-present vs conflict-absent paths.
K7.6 Add recovery smoke fixtures/scripts validating documented runbook procedures.

K8. Deterministic Replay Envelope Uplift (Open)

K8.1 Persist normalized-input content hash in run metadata.
K8.2 Persist backend command identity/version metadata in run metadata.
K8.3 Persist output payload hash for replay drift comparisons.
K8.4 Add replay-comparison helper for semantic drift detection.
K8.5 Add determinism tests for replay envelope fields/hashes.

K9. TTY Audio Robust-Mode Hardening (Open)

K9.1 Add per-frame integrity checks (checksum/hash).
K9.2 Add sequence-gap detection and explicit gap error reporting.
K9.3 Define retransmit/recovery policy for missing/corrupt frames. (Covered: deterministic retransmit-plan API/CLI from gap + integrity telemetry, plus protocol docs.)
K9.4 Add tests for out-of-order, duplicate, and missing-frame windows.
K9.5 Document robust-mode protocol versioning and compatibility semantics.

K10. TUI Reliability Follow-Ups (Open)

K10.1 Add tests for run selection and scrolling over large synthetic datasets.
K10.2 Add smoke coverage for empty DB and transient DB-open failures.
K10.3 Validate refresh behavior under high event volume.
K10.4 Add operator-facing warning legend for fallback/divergence semantics.

K11. Methodology Artifacts and Governance (Complete for Current Scope)

K11.1 Add operational playbook doc.
K11.2 Add master TODO/bead map doc.
K11.3 Add definition-of-done doc.
K11.4 Add risk register doc.
K11.5 Cross-link docs in README/spec architecture docs.

K12. Execution Discipline for All Future Packets

K12.1 After substantive edits: run cargo fmt --check.
K12.2 After substantive edits: run cargo check --all-targets.
K12.3 After substantive edits: run cargo clippy --all-targets -- -D warnings.
K12.4 After substantive edits: run cargo test.
K12.5 After substantive edits: run feature checks (tui, gpu-frankentorch, gpu-frankenjax) as applicable.
K12.6 After each packet: record quality-gate outcomes and residual risks in this tracker.

K13. Alien-Uplift Candidate Queue (EV-Ranked; Derived from Canonical Graveyard)

K13.1 Add explicit tail-latency decomposition artifacts per stage (p50/p95/p99, queueing vs service vs external process) and bind them to stage budget tuning decisions. (Implemented: orchestration.latency_profile stage event + evidence artifact stage_latency_decomposition_v1, per-stage queue/service/external decomposition, p50/p95/p99 fields, and deterministic budget-tuning recommendations with tests in orchestrator::tests::stage_latency_profile_*.)
K13.2 Promote backend routing from shadow-only to policy-controlled execution behind a hard safe-mode gate (static order fallback remains always available). (Implemented: execute_with_order uses recommended order; calibration gate falls back to static; FRANKEN_WHISPER_ROUTING_SAFE_MODE=1 disables active routing.)
K13.3 Add calibration and drift guardrails for adaptive routing (coverage/error-budget monitor; auto-fallback trigger on drift). (Implemented: calibration_score < min_calibration threshold discards recommended order; configurable via FRANKEN_WHISPER_ROUTING_MIN_CALIBRATION env.)
K13.4 Add anytime-valid sequential evidence guard (e-process/SPRT-style thresholding) for runtime enable/disable of adaptive routing actions. (Implemented: e_process computed as inverse posterior margin clamped [1,100]; feeds into FallbackPolicy::should_fallback via EvalContext; tested in e_process_inversely_related_to_posterior_margin.)
K13.5 Add policy/artifact provenance fields (policy_id, artifact_hash, schema_version) to routing evidence and enforce deterministic reject on incompatible policy artifacts. (Implemented: provenance block with policy_id, schema_version, loss_matrix_hash; tested in backend_selection_routing_log_contains_provenance_fields + loss_matrix_hash_is_deterministic.)
K13.6 Add deterministic replay artifact pack per packet (env.json, manifest.json, repro.lock) for reproducible routing and timeout behavior analysis. (Implemented: src/replay_pack.rs with 11 unit tests.)
K13.7 Add explicit expected-loss matrix documentation and tests for routing action choices (latency risk, quality risk, failure risk). (Implemented: quality_proxy, latency_proxy, posterior_success_probability tested in backend/mod.rs with 14+ dedicated tests.)
K13.8 Add a machine-readable decision ledger browser path for robot/TUI operators (at minimum: decision id, top evidence terms, fallback reason). (Implemented: evidence field in RunReport + robot run_complete envelope + TUI event display.)

K14. Native-Engine Convergence + Conformance (New, from cross-agent feedback)

K14.1 Reframe architecture docs from adapter-first language to engine-contract + native-port target state.
K14.2 Add runtime segment conformance contract enforcement (segment-monotonic-v1) with invariant tests.
K14.3 Define explicit compatibility envelope (text/timestamp/speaker/calibration tolerances) in executable test form.
K14.4 Build golden-corpus conformance harness for parity/drift validation across engine implementations. (Implemented: tests/conformance_harness.rs::golden_corpus_cross_engine_parity_harness + fixture corpus under tests/fixtures/conformance/corpus/, validating whisper.cpp / insanely-fast / diarization golden artifacts against canonical envelopes and pairwise cross-engine tolerance checks.)
K14.4a Seed fixture-driven conformance harness (tests/conformance_harness.rs + tests/fixtures/conformance/*.json).
K14.5 Persist replay envelope metadata (input_hash, engine identity/version, output hash) and add drift comparator.
K14.6 Add explicit GPU device/stream ownership + cancellation telemetry in orchestration/report artifacts. (Implemented: logical_stream_owner_id + logical_stream_kind now emitted in acceleration.context, cancellation-fence telemetry payload persisted in stage event + evidence, warnings emitted when fence is tripped, and dedicated orchestrator tests added for owner-id/fence semantics.)
K14.7 Promote TTY transport to robust-mode protocol (versioning, sequence, integrity, backpressure, recovery policy). (Implemented across src/tty_audio.rs, CLI surfaces, protocol docs, and tests: protocol negotiation, sequence/gap handling, CRC32/SHA integrity, backpressure + retransmit control frames, fail-closed/skip-missing recovery policy, deterministic retransmit planning.)

L. Active Full-Execution Packet (2026-02-22, user directive: "do ALL of that now")

L0. Control Plane and Tracker Discipline

L0.1 Create this packet and keep it as the authoritative execution ledger for this turn.
L0.2 Baseline current test health before edits (cargo test -q) to establish known-good starting point.
L0.3 Update task states after each material edit/test batch.
L0.4 Final reconciliation: propagate all completed work back to K-open items and close/move stale rows.

L1. Correctness and Contract Hardening (Critical Path)

L1.1 Expand robot_error_code() regression coverage across all FwError variants.
L1.2 Guarantee checkpoint cancellation emits explicit stage event before terminal run_error.
L1.3 Attach explicit cancellation evidence payload terms to cancellation stage events.
L1.4 Add tests covering cancellation stage-event ordering and cancellation evidence emission.
L1.5 Align sync docs/CLI terminology (--conflict-policy reject|overwrite) and remove stale wording.

L2. Robot Contract Stability and Machine Ergonomics

L2.1 Replace static hand-written robot schema output with source-of-truth schema builder.
L2.2 Add tests asserting required fields for each stage NDJSON line.
L2.3 Add machine-readable output mode for runs command (plain|json|ndjson).
L2.4 Add tests for new runs output modes and stable field presence.
L2.5 Add golden/contract tests for stage code/message classes including timeout/cancel/error.

L3. Sync and Recovery Hardening

L3.1 Add import failure-path tests when writing sync_conflicts.jsonl fails.
L3.2 Add explicit schema-version compatibility tests (major mismatch; minor compatibility).
L3.3 Add row-count mismatch tests for conflict-present vs conflict-absent scenarios.
L3.4 Add recovery smoke fixture helper(s) for runbook-critical paths.

L4. TTY Robust-Mode Hardening

L4.1 Add per-frame integrity field (checksum/hash) and validate on decode.
L4.2 Add sequence continuity checks with explicit gap/duplicate/out-of-order errors.
L4.3 Define decode policy for malformed/missing frames (deterministic fail mode).
L4.4 Add tests for out-of-order, duplicate, missing-frame, and checksum-failure paths.
L4.5 Document protocol versioning + compatibility behavior.

L5. Backend Parity and Diagnostics

L5.1 Re-audit adapter option forwarding vs legacy surfaces and close obvious forwarding gaps.
L5.2 Add adapter diagnostics notes for unsupported or ignored flags where applicable.
L5.3 Add parser tests for mixed/malformed backend outputs not yet covered.

L6. Replay/Determinism Uplift (If scope permits in this turn)

L6.1 Persist normalized-input content hash in run-level artifacts.
L6.2 Persist backend command identity/version metadata in run-level artifacts.
L6.3 Persist output payload hash and add deterministic replay-compare helper.
L6.4 Add tests for replay envelope completeness and hash determinism.

L7. TUI Reliability Follow-Ups (If scope permits in this turn)

L7.1 Add run-selection/scroll tests over larger synthetic datasets.
L7.2 Add empty-db/transient-open-failure smoke tests.
L7.3 Add high event-volume refresh resilience check(s).
L7.4 Add operator-facing warning legend semantics coverage.

L8. Quality Gates + Handoff

L8.1 Run cargo fmt --check.
L8.2 Run cargo check --all-targets.
L8.3 Run cargo clippy --all-targets -- -D warnings.
L8.4 Run cargo test.
L8.5 Run feature checks (--features tui, --features gpu-frankentorch, --features gpu-frankenjax).
L8.6 Update this tracker with quality-gate outputs, residual risks, and explicit carry-forward items.
L8.7 Quality-gate outcomes: all gates passed on this packet (fmt, check, clippy -D warnings, test, check --features tui, test --features tui, check --features gpu-frankentorch, check --features gpu-frankenjax).

L9. Carry-Forward Gaps (Explicit)

L9.1 Recovery smoke fixture/scripts for runbook-critical flows (K7.6 / L3.4).
L9.2 Replay envelope persistence + deterministic replay comparator (K8.* / L6.*).
L9.3 TUI reliability workload tests (K10.* / L7.*).
L9.4 Remaining backend parity packet for whisper.cpp + ingest line-in/stream envelope tests (K5.1, K5.3, K5.4).
L9.5 TTY retransmit/recovery semantics beyond fail-closed protocol v1 (K9.3). (Closed by retransmit-plan artifact + docs + tests.)

M. Active Closure Packet (2026-02-22, user directive: "do ALL of that now")

M0. Packet Control and Ledger Hygiene

M0.1 Open this packet as the live granular task ledger for final closure scope.
M0.2 Re-scan canonical open rows (K5.4, K9.3, L9.4, L9.5) and constrain this packet to those gaps.
M0.3 Update this packet status after each implementation/test batch.
M0.4 Final reconciliation: propagate this packet outcomes back into K/L sections.

M1. K5.4 Ingest↔Backend Parity Closure (line-in/stream envelope tests)

M1.1 Add integration helper to provision deterministic whisper.cpp stub backend for test-mode execution. (write_whisper_cpp_stub_binary in tests/cli_integration.rs)
M1.2 Add fixture helper to generate synthetic audio input usable by ffmpeg normalization paths. (generate_silent_wav in tests/cli_integration.rs)
M1.3 Add file-input end-to-end parity test crossing ingest → normalize → whisper_cpp backend stub.
M1.4 Add stdin-input end-to-end parity test crossing ingest → normalize → whisper_cpp backend stub.
M1.5 Add mic/line-in-input end-to-end parity test using explicit ffmpeg source/format envelope.
M1.6 Assert stable backend identity/output contract in each mode (backend=whisper_cpp, transcript/segment invariants).
M1.7 Mark K5.4 and L9.4 status based on implemented evidence.

M2. K9.3/L9.5 Retransmit/Recovery Semantics Closure

M2.1 Add explicit retransmit plan data model (range request artifact) to TTY module. (RetransmitRange, RetransmitPlan in src/tty_audio.rs)
M2.2 Derive deterministic retransmit ranges from sequence gaps + integrity failures. (retransmit_plan_from_report + range collapse helper)
M2.3 Add reusable API to compute retransmit plan from inbound NDJSON stream. (retransmit_plan_from_reader, retransmit_plan_from_stdin)
M2.4 Add CLI surface for retransmit planning (tty-audio retransmit-plan) with machine-readable JSON output.
M2.5 Add unit tests for range compression and retransmit request determinism. (retransmit_plan_merges_gap_and_integrity_sequences_into_ranges)
M2.6 Add decode+plan integration tests for mixed gap/corrupt frame windows. (tty_audio_retransmit_plan_outputs_missing_and_corrupt_ranges)
M2.7 Update protocol docs with explicit retransmit handshake policy and compatible failover behavior.
M2.8 Update README command examples for retransmit planning flow.
M2.9 Mark K9.3 and L9.5 status based on implemented evidence.

M3. Regression Guarding and Quality Gates

N. Active Autonomy Packet (2026-02-22, user directive: continue autonomously)

N0. Control + Re-Assimilation

N0.1 Re-read AGENTS.md and README.md in full before new edits.
N0.2 Run explorer-assisted architecture/gap audit against canonical open rows (K13.1, K14.4, K14.6, K14.7).
N0.3 Reconcile stale rows and confirm K5.7/K5.8/K13.1/K14.4 are implemented with concrete evidence in code/tests.

N1. K14.7 Robust TTY Protocol Promotion (Operational Control Plane)

N1.1 Add concrete retransmit_response control-frame variant for round-trip protocol completeness.
N1.2 Emit explicit handshake control frame at start of tty-audio encode output stream.
N1.3 Implement mixed-line parser (audio + control) for NDJSON frame streams.
N1.4 Add decode-path handshake negotiation + control-frame validation (handshake ordering, duplicate handshake rejection, codec compatibility checks).
N1.5 Keep legacy compatibility: decode path still accepts audio-only streams with no handshake.
N1.6 Add robust unit coverage for handshake/control interleave, invalid control ordering, duplicate handshake, unsupported codec, and control/audio frame classification.

N2. K14.6 Acceleration Telemetry Completion

N2.1 Add deterministic logical stream-owner identity derivation for acceleration telemetry.
N2.2 Add explicit cancellation-fence artifact payload (status/error/error_code/budget/checked_at) for acceleration stage.
N2.3 Extend acceleration.context stage event payload with stream-kind/owner + cancellation-fence telemetry and persist via events/evidence.
N2.4 Add orchestrator tests for stream-owner encoding and cancellation-fence payload semantics.

N3. Concurrent API Drift Integration Hardening

N3.1 Integrate cancellation-aware storage path while preserving broad call-site compatibility (persist_report + persist_report_with_token split).
N3.2 Integrate cancellation-aware ingest path while preserving public API compatibility (materialize_input + materialize_input_with_token split).
N3.3 Integrate cancellation-aware acceleration path while preserving public API compatibility (apply + apply_with_token split).
N3.4 Resolve clippy strictness regressions caused by API integration drift.

N4. Documentation Sync

N4.1 Update docs/tty-audio-protocol.md with explicit control-frame schema (handshake, handshake_ack, retransmit_request, retransmit_response, ack, backpressure).
N4.2 Update protocol narrative to describe handshake-first encode + control-frame-interleaved decode behavior.
N4.3 Update README.md TTY section to reflect control-frame handshake/retransmit model.

N5. Quality Gates (This Packet)

N5.1 cargo fmt --check
N5.2 cargo check --all-targets
N5.3 cargo clippy --all-targets -- -D warnings
N5.4 cargo test
N5.5 cargo check --all-targets --features tui (passed; upstream warning-only noise from /data/projects/frankentui)
N5.6 cargo check --all-targets --features gpu-frankentorch
N5.7 cargo check --all-targets --features gpu-frankenjax

O. Active Autonomy Packet (2026-02-22, user directive: "do ALL of that now")

O0. Control and Scope Lock

O0.1 Confirm follow-up scope from prior handoff: tolerance contract alignment + control-plane CLI + retransmit loop automation.
O0.2 Keep this section as live detailed tracker and update per material sub-step. (Now backed by P master packet + linked br graph.)
O0.3 Preserve non-destructive workflow and compatibility with existing CLI/API surfaces.

O1. Conformance Tolerance Contract Alignment

O1.1 Decide canonical default tolerance (50ms vs 100ms) and ensure docs + code agree. (Canonical: 50ms / 0.05 sec.)
O1.2 Patch src/conformance.rs default and tests if canonical value changes. (Code already aligned to 0.05; retained and validated.)
O1.3 Patch docs/engine_compatibility_spec.md and any README references to match canonical value.
O1.4 Add/adjust regression tests for default tolerance semantics. (Conformance and CLI harness coverage revalidated in full test pass.)

O2. TTY Control CLI Surface

O2.1 Extend CLI model with tty-audio control subcommand family. (src/cli.rs)
O2.2 Add control emit variants: handshake, handshake-ack, ack, backpressure, retransmit-request, retransmit-response. (src/cli.rs, src/main.rs, src/tty_audio.rs)
O2.3 Add argument parsing for sequence vectors (--sequences) and codec/version fields. (src/cli.rs)
O2.4 Wire main.rs dispatch to emit exactly one NDJSON control frame per control command invocation. (src/main.rs)

O3. Scripted Retransmit Loop Automation

O3.1 Add deterministic helper to derive retransmit_request frame from decode telemetry/plan. (src/tty_audio.rs)
O3.2 Add tty-audio control retransmit-loop command that scans stdin frames and emits control action(s) deterministically. (src/cli.rs, src/main.rs, src/tty_audio.rs)
O3.3 Ensure loop command supports explicit recovery policy and bounded rounds semantics. (src/cli.rs, src/tty_audio.rs)
O3.4 Ensure loop command emits machine-readable output only (NDJSON control lines). (src/main.rs, src/tty_audio.rs)

O4. Tests and Contracts

O4.1 Add CLI parse tests for new tty-audio control variants. (tests/cli_integration.rs)
O4.2 Add unit tests for control-frame emission helpers and retransmit-loop planner behavior. (src/tty_audio.rs)
O4.3 Add integration tests invoking binary for at least one control emit command and retransmit-loop flow. (tests/cli_integration.rs)
O4.4 Reconcile any golden/schema docs if command outputs add new operational examples. (tests/robot_contract_tests.rs updated for current 7-event schema contract)

O5. Documentation + Tracker Reconciliation

O5.1 Update README with new control command usage snippets. (README.md)
O5.2 Update docs/tty-audio-protocol.md with control CLI workflow and retransmit-loop behavior.
O5.3 Mark O1–O5 and any affected K/L/M/N rows complete with evidence notes.

O6. Quality Gates (Mandatory)

O6.1 cargo fmt --check
O6.2 cargo check --all-targets
O6.3 cargo clippy --all-targets -- -D warnings
O6.4 cargo test
O6.5 cargo check --all-targets --features tui (passes; warning-only upstream noise in /data/projects/frankentui)
O6.6 cargo check --all-targets --features gpu-frankentorch (passed after src/accelerate.rs API-drift fixes)
O6.7 cargo check --all-targets --features gpu-frankenjax (passed after src/accelerate.rs API-drift fixes)

P. Master Program Backlog (2026-02-22, explorer+skill synthesis, authoritative)

P0. Governance, Overlap Check, and Tracking Discipline

P0.1 Re-read AGENTS.md + README.md in full before reopening planning.
P0.2 Run explorer-assisted codebase archaeology across docs, source architecture, tests/quality, and legacy gap map.
P0.3 Use required skills for this packet (porting-to-rust, rust-cli-with-sqlite, alien-artifact-coding, alien-graveyard) and extract concrete action items.
P0.4 Run br overlap checks (br list, br search) to avoid duplicate backlog creation.
P0.5 Create missing br issues for uncovered work and wire dependency edges.
P0.6 Validate dependency graph has no cycles (br dep cycles --json).
P0.7 Keep this packet updated as the single high-granularity source during O/P execution.

P1. Control-Plane Closure Packet (O1–O6 mapped to `br`)

P2. Test and Verification Gaps (from explorer audit)

P3. Native Engine Replacement Program (legacy subprocess -> Rust engines)

P4. Alien-Artifact Decision Contract Hardening

P4.1 Ensure adaptive routing evidence payload explicitly records state space, action space, loss matrix, posterior terms, and calibration metrics. (src/backend/mod.rs routing payload + backend contract tests)
P4.2 Ensure deterministic fallback trigger is encoded and persisted for every adaptive decision. (fallback_active, fallback policy metadata, persisted stage event payload in src/backend/mod.rs / src/orchestrator.rs)
P4.3 Ensure all adaptive controller paths have conservative deterministic safe-mode fallback. (FRANKEN_WHISPER_ROUTING_SAFE_MODE static-order branch in src/orchestrator.rs)
P4.4 Add regression tests that fail if decision-contract fields are absent from stage event payloads. (transcribe_backend_routing_stage_event_has_required_decision_contract_fields in tests/cli_integration.rs)

P5. SQLite/JSONL Operational Guarantees (durability and recovery)

P5.1 Re-validate one-way sync lock + atomicity invariants after P1/P2 changes. (src/sync.rs lock/atomic tests including lock_prevents_concurrent_sync, export_error_releases_lock_via_drop_guard)
P5.2 Re-run sync/recovery smoke scenarios with crash-interrupt simulation for drift detection. (tests/recovery_smoke.rs suite + cargo test)
P5.3 Ensure version markers and conflict artifacts remain stable and documented. (SYNC_STRATEGY.md, RECOVERY_RUNBOOK.md, sync_conflicts.jsonl tests in src/sync.rs)
P5.4 Ensure no two-way merge behavior has been introduced by control-plane/test additions. (import/export path remains explicit one-way with policy-bound conflict handling in src/sync.rs)

P6. Finalization and Handoff Criteria for this Program Packet

P6.1 Mark completed rows in O and P with concrete evidence references (files/tests/commands).
P6.2 Confirm br graph remains cycle-free after each dependency mutation. (2026-02-22: br dep cycles --json => count: 0 after issue creation + reparenting.)
P6.3 Run br sync --flush-only at packet close and verify JSONL export. (2026-02-22: Nothing to export (no dirty issues).)
P6.4 Summarize remaining risks (especially native-engine replacement not yet complete).
- Native-engine replacement program (P3) pilot packet is now delivered for all three engines with runtime toggles; dominant remaining risk is production-quality inference parity/perf beyond deterministic pilots.
- GPU feature matrix now compiles cleanly; ongoing risk is API drift in optional accelerator integrations (frankentorch/frankenjax) requiring periodic compatibility sweeps.
- Conformance artifact generation now emits bridge/native bundle artifacts, but corpus breadth is still small and should be expanded before hard rollout promotion.
P6.5 Propose next execution order using only ready, dependency-unblocked br items.
- 1. Expand conformance corpus breadth (long-form, multilingual, multi-speaker overlap, silence-heavy fixtures) and tighten rollout gates.
- 1. Harden native pilot paths toward true inference parity/perf (replace deterministic pilot kernels with real runtime integrations).
- 1. Keep benchmark baselines current (tty_bench + sync_bench) and fail fast on >20% regressions per docs/benchmark_regression_policy.md.
P6.6 Capture current quality-gate baseline failures discovered during this planning packet.
- cargo fmt --check passes.
- cargo check --all-targets passes.
- cargo clippy --all-targets -- -D warnings passes.
- cargo test passes (latest snapshot: 2032 library tests + full integration/recovery/replay/conformance suites green; only explicitly ignored fixture-generator tests remain ignored).
- cargo check --all-targets --features tui passes (warning-only upstream noise in /data/projects/frankentui and non-fatal src/tui.rs dead-code warnings).
- cargo check --all-targets --features gpu-frankentorch passes.
- cargo check --all-targets --features gpu-frankenjax passes.
- 2026-02-22 follow-up: full matrix re-run on isolated cache (CARGO_TARGET_DIR=/data/projects/franken_whisper/target_local) to avoid mixed-nightly artifact drift; fmt, check, clippy -D warnings, test, and all three feature checks passed.
- 2026-02-22 follow-up: br dep cycles --json reported count: 0; br sync --flush-only --json exported no dirty rows.
- 2026-02-22 follow-up: sync_bench still reproduces upstream io_uring panic noise under criterion stress; captured evidence in /tmp/franken_whisper_sync_bench_2026-02-22.log (panic lines: 1,253,267) and downgraded sync baselines to provisional in docs/benchmark_regression_policy.md.
- 2026-02-22 follow-up: backend/replay stage events now include explicit execution-path metadata (implementation, execution_mode, native_rollout_stage, native_fallback_error) with integration coverage in tests/cli_integration.rs (transcribe_backend_stage_payload_exposes_execution_metadata).

P7. Execution-Path Provenance + Benchmark Blocker Refresh (2026-02-22)

P7.1 Reproduce sync benchmark blocker on current tree and capture concrete evidence artifact.
P7.2 Add explicit backend execution-path metadata to backend.ok and replay.envelope stage payloads.
P7.3 Add regression/integration coverage for backend execution-path payload fields.
P7.4 Update compatibility + README docs to reflect execution-path payload contract.
P7.5 Reconcile benchmark policy docs with blocked sync baseline state and captured probe values.
[!] P7.6 Remove upstream frankensqlite io_uring panic source and re-lock sync throughput baselines after stable reruns.
P7.7 Re-run mandatory quality gates and feature checks after P7 edits.
- CARGO_TARGET_DIR=/data/tmp/franken_whisper-target cargo fmt --check passes.
- CARGO_TARGET_DIR=/data/tmp/franken_whisper-target cargo check --all-targets passes.
- CARGO_TARGET_DIR=/data/tmp/franken_whisper-target cargo clippy --all-targets -- -D warnings passes.
- CARGO_TARGET_DIR=/data/tmp/franken_whisper-target cargo test passes.
- Feature checks pass for tui, gpu-frankentorch, gpu-frankenjax (non-fatal warning noise remains in /data/projects/frankentui and dead-code warnings in src/tui.rs under tui feature).

Q. Execution Packet — Conformance Breadth + Rollout Gates + Native Runtime + Bench Guardrails (2026-02-22)

Q0. Packet governance and tracking discipline

Q0.1 Open packet Q as the authoritative checklist for this execution pass.
Q0.2 Keep every deliverable decomposed into implementation + tests + docs + validation subtasks.
Q0.3 Update this packet after each material edit batch with explicit evidence paths.
Q0.4 Final reconciliation: zero unresolved packet tasks unless explicitly blocked with root-cause evidence.

Q1. Expand conformance corpus breadth (long-form, multilingual, overlap, silence-heavy)

Q1.1 Add long-form fixture with multi-minute timeline and dense segment chain.
Q1.2 Add multilingual fixture covering at least mixed English + Romance-language segments.
Q1.3 Add multi-speaker-overlap stress fixture with near-boundary timestamp tolerance pressure.
Q1.4 Add silence-heavy fixture with sparse speech islands and long silent gaps.
Q1.5 Add corresponding golden artifacts under tests/fixtures/golden/ for all new corpus fixtures.
Q1.6 Keep fixture formats compatible with harness loaders (json_payload / diarization_srt).
Q1.7 Ensure all added fixtures pass canonical conformance comparison at 50ms default tolerance.
Q1.8 Add fixture-level metadata tags needed for rollout-gate coverage checks.

Q2. Tighten rollout/conformance promotion gates

Q2.1 Add explicit corpus coverage gate in conformance harness (required scenario classes).
Q2.2 Add explicit minimum corpus size gate for bridge/native promotion confidence.
Q2.3 Add explicit per-engine presence gate (bridge/native entries required per backend family).
Q2.4 Add pairwise drift cap checks beyond within_tolerance() boolean.
Q2.5 Emit gate summary fields into target/conformance/bridge_native_conformance_bundle.json.
Q2.6 Add regression tests validating new gate logic and failure diagnostics are deterministic.
Q2.7 Update docs/native_engine_contract.md rollout gate section to match executable harness checks.
Q2.8 Update docs/engine_compatibility_spec.md gate references to include new corpus breadth criteria.

Q3. Upgrade native backend runtime internals beyond duration-only pilot outputs

Q3.1 Replace duration-only segmentation in whisper_cpp_native with waveform-aware segmentation kernel.
Q3.2 Replace duration-only segmentation in insanely_fast_native with waveform-aware segmentation kernel.
Q3.3 Replace duration-only segmentation in whisper_diarization_native with waveform-aware segmentation + speaker lane assignment kernel.
Q3.4 Introduce shared audio analysis utility for native engines (WAV parse, frame RMS, active-region extraction).
Q3.5 Preserve cancellation checkpoints through all new native analysis loops.
Q3.6 Preserve deterministic output for identical input bytes and identical request params.
Q3.7 Preserve native/bridge fallback safety behavior and runtime metadata contract.
Q3.8 Update native raw-output telemetry to include analysis provenance (frame size, active regions, coverage).

Q4. Native runtime validation and contract hardening

Q4.1 Add unit tests for shared waveform analysis utility edge cases (empty/short/corrupt/minimal WAV).
Q4.2 Add unit tests proving native segmentation is content-sensitive (silence vs tone vs mixed energy).
Q4.3 Add unit tests proving deterministic reproducibility for identical audio input.
Q4.4 Add unit tests proving cancellation checkpoints trigger during long analysis loops.
Q4.5 Add tests ensuring native result invariants (monotonic timestamps, confidence bounds, speaker labels) remain valid.
Q4.6 Add tests ensuring native engines still satisfy capability superset and naming contracts.

Q5. Benchmark guardrail enforcement automation

Q5.1 Add executable guardrail checker tool for tty_bench + sync_bench vs baseline thresholds.
Q5.2 Parse criterion output robustly (estimates) and compute regression deltas.
Q5.3 Fail checker on >20% regression with clear per-benchmark diagnostics.
Q5.4 Add fixture/tests for guardrail checker parser + threshold logic.
Q5.5 Update docs/benchmark_regression_policy.md with checker usage and CI/local workflow.
Q5.6 Add optional CI workflow or script hook entrypoint for benchmark guardrail checks.

Q6. Full validation and closeout

R. Execution Packet — Speculative Streaming Orchestrator (`bd-qlt.6`) (2026-02-22)

R0. Selection, Claim, and Coordination

R0.1 Run bv --robot-next, bv --robot-priority, bv --robot-triage, bv --robot-plan.
R0.2 Select highest-impact actionable bead from robot triage output.
R0.3 Mark selected bead in_progress via br update.
R0.4 Register current session in Agent Mail and discover active peer agents.
R0.5 Request focused explorer-agent gap analyses for orchestrator/integration/tests.
R0.6 Record triage rationale and dependency context in this tracker packet.

R1. Orchestrator API and Contract Alignment

R1.1 Re-audit src/streaming.rs current SpeculativeStreamingPipeline implementation.
R1.2 Re-audit src/speculation.rs contracts (WindowManager, CorrectionTracker, SpeculationStats).
R1.3 Design file-level processing API that preserves deterministic window advancement.
R1.4 Decide bounded-final-window behavior and encode deterministic rule.
R1.5 Define cancellation checkpoint hook strategy for per-window loop.
R1.6 Define event-log contract for partial, confirm, retract, correct, and stats events.

R2. Speculative Pipeline Core Implementation

R2.1 Add file-level loop method (process_file/equivalent) in src/streaming.rs.
R2.2 Add internal helper to process explicit precomputed windows (shared by single-window + file-loop paths).
R2.3 Ensure per-window fast/quality execution uses ConcurrentTwoLaneExecutor.
R2.4 Ensure WindowManager and CorrectionTracker state transitions remain coherent in all outcomes.
R2.5 Ensure loop advances by deterministic step (window_size_ms - overlap_ms) with guard against zero-progress.
R2.6 Ensure final output is assembled through merged corrected transcript contract.

R3. Event Emission and Evidence Semantics

R3.1 Append deterministic RunEvent entries for early fast partial emissions.
R3.2 Append deterministic confirm events for non-corrected windows.
R3.3 Append retract + correct events for corrected windows.
R3.4 Append speculation-stats summary event at end-of-run API path.
R3.5 Ensure event sequence numbering is monotonic and stable.
R3.6 Ensure event timestamps are RFC3339 and payloads are schema-compatible with robot helpers.

R4. Stats and Robot Contract Alignment

R4.1 Extend SpeculationStats with confirmations_emitted to match bead contract.
R4.2 Populate confirmations_emitted from CorrectionTracker in streaming stats aggregation.
R4.3 Update robot required-fields list for transcript.speculation_stats.
R4.4 Update robot speculation_stats_value payload to include confirmations.
R4.5 Update affected tests/assertions for the revised stats schema.

R5. Test Coverage for `bd-qlt.6`

R5.1 Add focused tests for single-window confirm path.
R5.2 Add focused tests for single-window correct path (retract+correct state/event behavior).
R5.3 Add focused tests for multi-window file-loop behavior and deterministic advancement.
R5.4 Add focused tests for event sequencing and required payload fields.
R5.5 Add focused tests for stats aggregation including confirmations and correction rate.
R5.6 Add focused tests for cancellation-hook short-circuit behavior.

R6. Validation, Bead Updates, and Handoff

R6.1 Run cargo fmt --check.
R6.2 Run cargo check --all-targets.
R6.3 Run cargo clippy --all-targets -- -D warnings.
R6.4 Run cargo test.
R6.5 Update br bead status/comments based on implementation completion state. (bd-qlt.6 moved open -> in_progress -> closed)
R6.6 Send coordination update to discovered peer agents (or document none-active state). (Agent Mail discovery showed no active peer agents beyond current session identity.)
R6.7 Reconcile all R* rows with concrete evidence paths and residual risks.

T. Cross-Project Hardening Packet — `frankensqlite` io_uring Backend + `franken_whisper` Methodology Reconciliation (2026-02-23)

T0. Session discipline and scope control

T0.1 Re-confirm franken_whisper/AGENTS.md full constraints before editing.
T0.2 Preserve non-destructive policy in both repositories (franken_whisper, frankensqlite).
T0.3 Record cross-repo scope explicitly: io_uring backend replacement hardening in frankensqlite plus architecture/methodology reconciliation in franken_whisper.
T0.4 Avoid reverting unrelated dirty worktree files from prior agents.

T1. `frankensqlite` io_uring backend hardening (feature precedence + fallback)

T1.1 Audit unfinished cfg migration points in crates/fsqlite-vfs/src/uring.rs.
T1.2 Remove mutual-exclusion assumption and make linux-asupersync-uring win when both backend features are enabled.
T1.3 Convert all remaining #[cfg(feature = "linux-uring-fs")] code paths that conflict with precedence to all(feature = "linux-uring-fs", not(feature = "linux-asupersync-uring")).
T1.4 Keep compile-time guard requiring at least one Linux io_uring backend feature.
T1.5 Validate IoUringRuntime debug/status/is_available behavior under each backend mode.
T1.6 Ensure bridge fallback remains sticky-disabled after panic/poison detection.

T2. `frankensqlite` fallback correctness + tests

T2.1 Add deterministic test hook for forced asupersync backend initialization failure (#[cfg(test)] gate only).
T2.2 Add regression test asserting init-failure disables backend and falls back to unix path.
T2.3 Ensure existing poisoned-lock fallback tests continue passing for uring-fs path.
T2.4 Resolve feature-unification dead code warning by aligning unix.rs helper cfg gate with precedence rule.

T3. `frankensqlite` top-level feature passthrough

T3.1 Add backend feature passthrough in crates/fsqlite-core/Cargo.toml.
T3.2 Add backend feature passthrough in crates/fsqlite/Cargo.toml.
T3.3 Add backend feature passthrough in crates/fsqlite-cli/Cargo.toml.
T3.4 Preserve workspace dependency inheritance semantics (avoid invalid workspace=true + default-features=false combination).
T3.5 Validate package-level feature selection compiles for fsqlite-core, fsqlite, fsqlite-cli.

T4. `frankensqlite` regression fixes surfaced by mandatory quality gates

T4.1 Fix btree interior distribution edge case that produced consumed trailing divider corruption error.
T4.2 Add unit regression test for interior distribution orphan-divider avoidance.
T4.3 Fix UPDATE OF trigger semantics regression in fsqlite-core to skip unchanged listed columns.
T4.4 Fix SSI pivot regression by aborting commit when dangerous structure (has_in_rw && has_out_rw) is present before FCW success path.
T4.5 Keep SSI evidence ledger drafting intact for abort decisions introduced by early dangerous-structure abort.

T5. `frankensqlite` validation matrix (backend + package + gates)

T6. `franken_whisper` mandatory reread + architecture comprehension

T6.1 Read AGENTS.md fully (line-by-line).
T6.2 Read README.md fully (all 1,103 lines).
T6.3 Reconcile docs against implementation reality via explorer-agent architecture report.
T6.4 Confirm project intent: engine-first unified schema + deterministic robot mode + sqlite/jsonl durability + optional TUI + tty audio transport.

T7. External-feedback reconciliation backlog (from peer agent critique)

T7.1 Confirm existing code already uses engine-trait framing (not wrapper-only adapter framing) in src/backend/mod.rs.
T7.2 Confirm conformance harness exists and emits bundle artifact (tests/conformance_harness.rs).
T7.3 Confirm replay determinism artifacts exist (src/replay_pack.rs, conformance docs/tests).
T7.4 Identify remaining real gap: orchestrator placeholder stages (VAD, separation, punctuation, diarization) still marked as placeholder implementations.
T7.5 Define explicit compatibility envelope doc addendum for parity targets (text/timestamp/speaker/confidence tolerances) as enforceable release gates. (implemented in docs/engine_compatibility_spec.md section 9 with release-gate matrix + mandatory execution checks)
T7.6 Add dedicated invariants/property tests for stage-order determinism and event-order replay under cancellation/failure paths. (completed in src/orchestrator.rs via strengthened cancellation/failure ordering tests, contiguous-seq invariants, and replay-order fingerprint assertions; tracked by bd-xp7 closed 2026-02-25.)
T7.7 Add a focused operator-facing protocol note clarifying tty-audio replayability semantics and framing guarantees. (implemented in docs/tty-replay-guarantees.md, linked from protocol/readme docs)

T8. Closeout packet requirements

T8.1 Publish cross-repo change summary with file-level references. (see docs/cross_repo_change_summary_2026-02-25.md)
T8.2 Publish quality gate outcomes (pass/fail + notable long-running suites). (2026-02-25 via rch: fmt pass, check --all-targets pass, clippy --all-targets -D warnings pass; full cargo test runs to completion with 14 residual non-bd-xp7 failures, while all bd-xp7-specific tests pass.)
T8.3 Publish residual risks (placeholder stages in franken_whisper; long SSI tests runtime cost in frankensqlite). (see docs/closeout_residual_risks_2026-02-25.md)
T8.4 Publish next concrete execution packets with clear ownership and verification criteria. (see docs/next_execution_packet_2026-02-25.md)

U. Cross-Repo Completion Packet — Golden Drift + SSI Runtime + Architecture Backlog (2026-02-23)

U0. Task-control and bookkeeping hygiene

U0.1 Open packet U as current-turn source-of-truth execution checklist.
U0.2 Expand all remaining work into granular sub-tasks before implementation.
U0.3 Keep status transitions explicit (pending -> in progress -> done/blocked) as work proceeds.
U0.4 Record command evidence and file paths for each completed sub-task.

U1. `frankensqlite` golden-checksum drift resolution (`fsqlite-harness`)

U1.1 Reproduce failing test: cargo test --workspace --exclude fsqlite-e2e and confirm bd_1lsfu_2_core_sql_golden_checksums failure mode.
U1.2 Confirm drift category from test diagnostics (parser/execution blake3 mismatches across fuzz fixtures).
U1.3 Quantify drift scope (fixture count and parser-vs-execution breakdown) from failure artifact output. (2026-02-25 rerun after restoring local-only corpus path reached case=checksum_mismatch: observed fixture=010_index_and_ordering changed with execution_blake3 mismatch and missing fuzz_sql_parser/* fixture IDs against worker expected state; fuzz_dir_canonicalize no longer present.)
U1.4 Run controlled checksum refresh flow using project-recommended command for this gate. (rch exec -v -- env FSQLITE_UPDATE_GOLDEN=1 cargo test -p fsqlite-harness --test bd_1lsfu_2_core_sql_golden_checksums -- --nocapture reported case=manifest_updated for crates/fsqlite-harness/conformance/core_sql_golden_blake3.json.)
U1.5 Re-run cargo test -p fsqlite-harness --test bd_1lsfu_2_core_sql_golden_checksums and verify green. (offloaded via rch exec -- ...; pass: test_bd_1lsfu_2_core_sql_golden_checksums ... ok.)
U1.6 Re-run adjacent harness checksum/manifest tests to ensure no partial-update inconsistency. (all offloaded via rch: bd_mblr_3_5_1_1_manifest_ingestion_regression, bd_mblr_5_4_1_log_quality_golden, bd_mblr_7_6_1_bisect_replay_manifest, and bd_2fas_wal_checksum_chain_recovery_compliance all passed.)
U1.7 Document whether refreshed checksums are attributable to pre-existing parser/codegen changes in dirty tree. (Current evidence indicates primary blocker was missing local-only fuzz corpus (fuzz/corpus/fuzz_sql_parser), not a new parser/codegen code change in this session.)

U2. `frankensqlite` bd-3plop SSI runtime containment

U2.1 Reproduce extreme runtime behavior in crates/fsqlite-e2e/tests/bd_3plop_5_ssi_serialization_correctness.rs::ssi_serialization_correctness_ci_scale.
U2.2 Verify no hard crash/deadlock signature (active CPU + advancing worker process) during long run.
U2.3 Review test workload constants and retry policy to identify worst-case wall-clock amplification vectors.
U2.4 Review recent fsqlite-core SSI path edits to avoid introducing pathological over-abort behavior.
U2.5 Roll back over-eager pre-check abort path in commit planning; keep decision-card semantics tied to actual SSI/FCW outcome path.
U2.6 Keep targeted SSI decision tests green after rollback/refinement.
U2.7 Add runtime guardrails for CI-scale test (time budget / workload scaling) if still non-practical after behavioral fix.
U2.8 Validate ssi_serialization_correctness_ci_scale and ssi_serialization_correctness_single_writer_smoke complete within practical envelope on this host.

U3. `franken_whisper` architecture backlog from external feedback

U3.1 Add explicit compatibility-envelope doc section with crisp parity definitions:
- text parity target
- timestamp tolerance bound(s)
- diarization label stability envelope
- confidence comparability semantics.
U3.2 Define release-gate criteria mapping envelope targets to pass/fail checks.
U3.3 Add/extend deterministic replay/event-order invariant tests covering:
- stage ordering monotonicity
- event sequence determinism under failure path
- event sequence determinism under cancellation path.
U3.4 Add or update robot schema contract assertions for any new/clarified event invariants.
U3.5 Add operator-facing protocol note for tty replay/framing guarantees and link it from README/docs index.
U3.6 Ensure added docs align with existing docs/tty-audio-protocol.md semantics (no contradictory claims).

U4. Cross-repo quality gates and evidence capture

U4.1 frankensqlite: re-run cargo fmt --check.
U4.2 frankensqlite: re-run cargo check --all-targets.
U4.3 frankensqlite: re-run cargo clippy --all-targets -- -D warnings.
[~] U4.4 frankensqlite: drive cargo test to full completion or isolate concrete blockers with reproducible commands and logs.
U4.5 frankensqlite: after U1/U2 fixes, re-run mandatory test gates to verify blocker closure.
U4.6 franken_whisper: run mandatory gates after U3 edits (fmt, check, clippy -D warnings, test).

U5. Final reconciliation and handoff quality

U5.1 Mark all completed packet rows (T, U) with final statuses and evidence references. (final bead state after closeout: bd-1a1=closed, bd-244=closed, bd-217=closed)
U5.2 Summarize exact changed files in both repos. (updated docs/cross_repo_change_summary_2026-02-25.md with current-session file list and command evidence)
U5.3 Summarize exact pass/fail quality-gate matrix by command. (updated docs/cross_repo_change_summary_2026-02-25.md gate matrix)
U5.4 List residual risks and what remains blocked vs completed. (updated docs/closeout_residual_risks_2026-02-25.md)
U5.5 Provide concrete next execution packets only for genuinely remaining work. (updated docs/next_execution_packet_2026-02-25.md)

FilesExpand file tree

TODO_IMPLEMENTATION_TRACKER.md

Latest commit

History

TODO_IMPLEMENTATION_TRACKER.md

File metadata and controls

TODO_IMPLEMENTATION_TRACKER.md

Legend

Meta Tracking Discipline

A. FW-P2C-003 Native Accelerated Adapter Layer

A1. Discovery and API reconnaissance

A2. Interface design

A3. Frankentorch implementation

A4. Frankenjax implementation

A5. Pipeline integration

A6. Tests

B. Real-Time Robot Mode Stage Streaming

B1. Event architecture

B2. CLI robot mode integration

B3. Non-robot flow compatibility

B4. Tests

C. FrankenTUI Run Status + Transcript Timeline

C1. Mandatory $frankentui skill first pass

C2. TUI UX scope definition (for this repo)

C3. Implementation

C4. Data plumbing

C5. Tests/build checks for TUI feature

D. Documentation and Contract Updates

E. Validation and Quality Gates

F. Finalization

S. Fresh-Eyes Audit Pass (2026-02-22)

S1. Audit scope and findings

S2. Fixes applied

S3. Regression coverage

S4. Quality gates

T. Randomized Deep Audit Pass (2026-02-23)

T0. Execution Control

T1. Random Sampling + Flow Mapping

T2. Fresh-Eyes Critical Review

T3. Bug Confirmation + Fixes

T4. Test Reinforcement

T5. Mandatory Quality Gates

Blockers / Assumptions / Deferred

Live Notes

G. Active Execution Packet (2026-02-22) — S1 + S2 + A1

G0. Granular Control Plane

G1. S1 Real-Time Robot Stage Streaming Hardening

G1.1 Event-flow correctness

G1.2 Persistence + stream consistency

G1.3 Robot contract tests

G2. S2 SQLite ↔ JSONL One-Way Sync Commands

G2.1 CLI/command surface

G2.2 Locking and atomicity

G2.3 Export pipeline (db -> jsonl)

G2.4 Import pipeline (jsonl -> db)

G2.5 Storage integration support

G2.6 Sync tests

G3. A1 Adaptive Backend Routing (Shadow Mode + Evidence Ledger)

G3.1 Shadow decision model

G3.2 Evidence artifact

G3.3 Shadow-mode safety

G4. Documentation + parity updates for this packet

G5. Mandatory quality gates and handoff

H. Active Execution Packet (2026-02-22) — Full User Request (All 4 Streams)

H0. Control and Tracking

H1. Sync CLI + SQLite/JSONL Ops Hardening

H1.1 Surface and contract audit

H1.2 Locking and atomicity hardening

H1.3 Import/export correctness hardening

H1.4 Sync tests

H2. Asupersync Cancel-Correct Orchestration Upgrade

H2.1 Stage budget model

H2.2 Budgeted stage execution

H2.3 Fallback safety + orphan prevention

H2.4 Tests for orchestration guarantees

H3. Backend Parity + Streaming Ergonomics Hardening

H3.1 Backend parity deltas

H3.2 Streaming ergonomics

H3.3 Tests for backend/streaming hardening

H4. Frankentui-Style Planning Methodology Artifacts (for this repo)

C1. Mandatory `$frankentui` skill first pass

G2.3 Export pipeline (`db -> jsonl`)

G2.4 Import pipeline (`jsonl -> db`)