# Development and release plan

Public release preparation follows the gates below. Marketplace submission remains a separate owner-reviewed action.

## Phase 1 — Baseline and rollback

- Inventory the working standalone QML, controller, compiler, Voxtype configuration, models, hotkeys, runtime state, and dependencies.
- Record current versions and global bindings.
- Confirm the standalone surface can be restored without reinstalling packages.
- Prohibit transcript, recording, model, credential, and machine-state files from Git.

Exit gate: a documented rollback procedure restores the current working flow.

## Phase 2 — Runtime-contract research

- Validate against the installed Omarchy version, not an assumed upstream version.
- Inspect first-party `panel`, `service`, and keep-loaded examples read-only.
- Verify manifest schema, entry-point names, lifecycle functions, IPC, imports, reload behavior, and logging.
- Inspect a maintained Marketplace plugin for repository, test, dependency, and documentation conventions.

Exit gate: `manifest.json` validates before the plugin is enabled.

## Phase 3 — Architecture and privacy

- Keep the QML UI in the shared Omarchy shell.
- Keep capture, transcription, and AI compilation outside the shared process.
- Define explicit state transitions and failure results.
- Use XDG paths and restrictive file permissions.
- Treat transcript content as untrusted data inside the compiler prompt.
- Preserve the intended destination window and fail safely to clipboard.
- Reserve a capability extension seam without defining W1.

Exit gate: architecture and threat model reviewed against implementation.

## Phase 4 — Plugin implementation

- Build `Jukebox.qml` as a keep-loaded panel.
- Port the spectrum analyzer, model selector, timer, processing animation, drag, and resize behavior.
- Preserve the Marshall-inspired material system and WCAG-compliant labeling.
- Implement lifecycle `open()` and `close()` methods.
- Package backend commands and provide idempotent setup/removal scripts.
- Keep the standalone surface active until shared-shell parity is demonstrated.

Exit gate: the new plugin loads without a second Quickshell process or shell errors.

## Phase 5 — Automated verification

- `omarchy plugin validate` passes.
- `qmllint` passes against the installed shell imports.
- Manifest/entry-point/dependency tests pass.
- State-machine and lock tests cover re-entry and every failure edge.
- Compiler tests cover corrections, domain inference, detail preservation, injection resistance, no fabrication, same-model retry, and empty output.
- Layout tests prove no control overlap at minimum, typical, and maximum widths.
- Accessibility tests cover labels, contrast, pointer states, non-focus-stealing behavior, and global keyboard operation.
- Secret scanning and repository-content checks pass.

Exit gate: all automated checks are green from a clean checkout.

Add GitHub Actions when repository authentication has explicit `workflow` scope. Until then, the same validation script is required locally and from a pristine clone.

## Phase 6 — Desktop end-to-end verification

Test on the installed Omarchy environment:

1. discover, validate, enable, summon, hide, and close with Escape where applicable;
2. Super+F9 start and Super+F10 finish;
3. click Finish + Upscale;
4. Luna, Terra, and Sol selection and persistence;
5. short speech, 15-minute simulation/fixture, and disk-chunked long-session behavior;
6. resize at 520, 800, 1070, and 1120 px;
7. drag, edge clamping, monitor geometry changes, and shell restart persistence;
8. destination focus retained versus changed during processing;
9. missing microphone, missing binary, empty transcript, transcription timeout, compiler failure, clipboard failure, and analyzer crash;
10. hot reload, rescan, shell restart, disable, re-enable, clean removal, and rollback.

Exit gate: no lost prompt, no wrong-window injection, no duplicate recorder, no shell crash, and no unresolved QML error.

## Phase 7 — Visual evidence

- Capture curated screenshots at narrow, typical, and large sizes.
- Capture idle/summoned, recording, selected-model, hover, pressed, processing, success, and error/recovery states.
- Record a concise setup demo and a complete voice-to-expert-prompt workflow.
- Edit captures to remove private window titles, transcripts, notifications, account identifiers, and unrelated desktop content.
- Export web-friendly video plus a short GIF or animated preview where file size permits.
- Record exact commands and environment versions used to produce evidence.

Exit gate: visuals demonstrate real behavior without leaking personal information.

## Phase 8 — Release candidate review

- Complete README, setup, architecture, security, privacy, troubleshooting, contribution, and uninstall documentation.
- Verify repository history contains no secrets or private speech.
- Tag a release candidate only after all checks pass.
- Compare the repository against current Marketplace publishing requirements.
- Present the repository, evidence, test report, known limitations, and rollback instructions to the owner.

Exit gate: explicit owner approval before Marketplace submission.