docs/TASKS.md

# TASKS.md — Midnight Static Execution Tracker

Deadline: **June 15, 2026**. Target submit: **June 14 evening**.

Status legend:

- `[x]` done
- `[~]` partially done / usable but not final
- `[ ]` not started
- `[>]` next / current focus
- `[D]` deferred or cut unless time allows

## Current Position

We have a live Hugging Face Space with a working Gradio fallback, one instant
showcase rerun, a schema-valid fixture writer, Kokoro TTS, and a crude mixer.

Live Space:

https://huggingface.co/spaces/build-small-hackathon/midnight-static

Current recommended focus:

1. Build the custom radio UI.
2. Post social update #1 after the UI is visually credible.
3. Run real Nemotron smoke on GPU infra.

## Phase 1 — Foundation And Repo

1.1. `[x]` Initialize repo via Codex with project skeleton.

1.2. `[x]` Add `AGENTS.md`, docs, `uv` project metadata, tests.

1.3. `[x]` Set repo-local Git author to `Codex <codex@openai.com>`.

1.4. `[x]` Add `.env` protection and `.env.example`.

1.5. `[x]` Keep `uv run pytest` green before pushes.

Current evidence:

- First commit: `8c16939 Initialize Midnight Static scaffold`
- Latest test count: 14 passing

## Phase 2 — Script Schema And Writer Boundary

2.1. `[x]` Define shared script schema in `midnight_static.schema`.

2.2. `[x]` Add deterministic fixture writer.

2.3. `[x]` Add writer contract and `--writer fixture` pipeline option.

2.4. `[x]` Add five-premise writer smoke test.

2.5. `[~]` Add `NemotronWriter` implementation boundary.

Notes:

- `NemotronWriter` targets `nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16`.
- Local macOS BF16 smoke failed because the model requires `mamba-ssm`.
- Llama-Nemotron fallback avoided that import path but checkpoint fetch was
  interrupted after 3m47s.
- Real Nemotron smoke should move to GPU infra.

2.6. `[>]` Run real Nemotron smoke on deployment GPU path.

2.7. `[ ]` Add one retry on invalid model JSON, then fixture fallback.

## Phase 3 — Voice And Audio Pipeline

3.1. `[x]` Verify Kokoro voice IDs from `hexgrad/Kokoro-82M`.

3.2. `[x]` Lock `VoiceID` enum.

3.3. `[x]` Render full fixture scene with multi-voice Kokoro.

3.4. `[x]` Add crude mixer: dialogue + hardcoded bed + SFX.

3.5. `[x]` One-command typed premise → mixed WAV:

```bash
uv run python -m midnight_static.pipeline --mode crude "a phone booth that rings under the sea"
```

3.6. `[ ]` Add production mixer chain:

- AM radio band-pass / saturation
- vinyl crackle
- ducking under dialogue
- LUFS normalization
- MP3 export

3.7. `[ ]` Add SFX retrieval/generation trace interface.

3.8. `[ ]` Add music bed/sting library interface.

## Phase 4 — Live Space

4.1. `[x]` Add Gradio app entrypoint.

4.2. `[x]` Fix Space build packaging.

4.3. `[x]` Fix Space runtime launch.

4.4. `[x]` Publish Space under hackathon org.

4.5. `[x]` Add README Space metadata/frontmatter.

4.6. `[x]` Add model inventory table.

4.7. `[x]` Add Codex and Modal sections to README.

4.8. `[x]` Add three instant showcase reruns.

4.9. `[x]` Add showcase selector in Gradio UI.

4.10. `[ ]` Add README links for demo video, social post, blog, dataset,
adapter, and traces as they become available.

## Phase 5 — Showcase And Demo Quality

5.1. `[x]` Showcase 1: `a phone booth that rings under the sea`.

5.2. `[x]` Showcase 2: `two rival lighthouse keepers, one light`.

5.3. `[x]` Showcase 3: `a wedding where every guest recognizes the wrong bride`.

5.4. `[x]` Add showcase selector in Gradio UI.

5.5. `[x]` Manual listen test for all showcase broadcasts.

- First listen found the three reruns too similar.
- Fixed by adding hand-authored showcase scripts with distinct genres, casts,
  voices, and scene structures.

5.6. `[ ]` Tune levels if showcases are harsh, too quiet, or unclear.

Never cut:

- showcase broadcasts
- listen test
- README tags/model table
- demo video

## Phase 6 — Custom Radio UI

6.1. `[x]` Build static radio visual shell.

6.2. `[x]` Genre dial interaction.

6.3. `[x]` Premise input as telegram slip.

6.4. `[x]` ON AIR loading/state sequence.

6.5. `[>]` Playback with script display.

6.6. `[ ]` Keep Gradio fallback available.

6.7. `[D]` Call-in microphone / ASR mode.

6.8. `[D]` FLUX poster generation.

Notes:

- Off-Brand score depends heavily on this phase.
- Do not block the live Space on this phase; the plain app is already live.

## Phase 7 — Modal, Dataset, And Fine-Tune

7.1. `[ ]` Add `modal/gen_dataset.py`.

7.2. `[ ]` Generate 400 validated examples.

7.3. `[ ]` Human skim pass, 45 minute cap.

7.4. `[ ]` Publish dataset to HF Hub.

7.5. `[ ]` Add `modal/finetune.py`.

7.6. `[ ]` Train LoRA and publish adapter.

7.7. `[ ]` Evaluate base vs LoRA.

7.8. `[ ]` Add `modal/batch_audio.py`.

7.9. `[ ]` Generate SFX/music library and manifest.

Notes:

- This phase needs Modal credentials.
- This phase is high prize evidence but not required for the app to be live.

## Phase 8 — Social, Blog, And Submission

8.1. `[>]` Social post #1: build-in-public with live Space link.

8.2. `[ ]` Add social post link to README.

8.3. `[ ]` Social post #2: radio UI reveal.

8.4. `[ ]` Demo video, 60-90 seconds.

8.5. `[ ]` Add demo video link to README.

8.6. `[ ]` Blog / Field Notes post.

8.7. `[ ]` Publish traces dataset.

8.8. `[ ]` Run `docs/SUBMISSION.md` checklist.

8.9. `[ ]` Final fresh-browser test on desktop and mobile.

8.10. `[ ]` Submit.

## Deferred / Cut Unless Ahead

9.1. `[D]` VoxCPM2 G1 gate.

Reason: Kokoro is working, and OpenBMB/MiniCPM evidence is not core to the
current path.

9.2. `[D]` BillShield-lite side project.

Reason: Midnight Static still needs showcase, UI, social, and submission work.

9.3. `[D]` FLUX posters.

Reason: only after custom radio UI and demo basics are done.

## Standing Rules

- Commit small via Codex throughout.
- Keep `uv run pytest` green before every push.
- If a task takes more than 2x estimate, cut scope or downgrade it.
- Never commit `.env` or tokens.
- Prefer live, audible, demonstrable progress over deeper model work that is
  invisible to judges.