Jake
c5460a169c
Operationalises the ChatGPT/Jake roadmap-synthesis pass into four
release-boundary documents at docs/release/. Synthesis call:
v0.1 = stable local capture product
v0.2 = Garden Inbox / review cards
v1.0 = PKM-complete + commercial track
Two factual audits ran first per Jake's explicit instruction — release
hardening only, no architecture refactors, no Garden Inbox work:
AUDIT 1 — MCP surface
=====================
Verdict: PASSES the v0.1 trust posture.
- Read-only by design (`//! No writes — Lumotia's Tauri app remains the only writer`)
- Stdio-only transport (newline-delimited JSON-RPC 2.0); no TCP/Unix
listener, no bind, no network exposure
- Database opened via `lumotia_storage::init_readonly` — structurally
enforced, not just convention
- 4 tools, all SELECT-only: list_transcripts, get_transcript,
search_transcripts, list_tasks
- Zero matches for INSERT/UPDATE/DELETE/fs::write/fs::remove/
create_dir/spawn_blocking in the crate
- Separate binary (`crates/mcp/src/main.rs`) — not part of the running
Tauri app; user must explicitly launch and wire into client config
- Honest nuance flagged in known-limitations: a wired client gets read
access to the entire transcript history + task list — no per-row
permission boundary in v0.1
AUDIT 2 — LLM failure surface
=============================
Verdict: data-loss path PASSES; UX-wedge path PARTIAL (documented).
- post_process_segments (file + live pipeline): tracing::warn! on Err,
segments stay at rule-based output. Raw transcript preserved.
- cleanup_transcript_text_cmd (DictationPage): frontend try/catch
returns raw text unchanged on Err. Raw transcript preserved.
- extract_tasks_from_transcript_cmd (DictationPage): frontend falls
back to rule-based extractTasks (regex + verb list) on Err.
- extract_content_tags_cmd (HistoryPage): per-row try/catch; toast on
failure; transcript untouched.
- Hung llama.cpp: no tokio::time::timeout on the spawn_blocking call.
Raw transcript preserved; rest of app functional; LLM status chip
stays on "Cleaning up" until restart. Soft edge — documented in
known-limitations as v0.2 hygiene candidate. Not implemented per
"release hardening only" instruction.
THE FOUR DOCS
=============
docs/release/v0.1-checklist.md
- 10-step tester acceptance test (install → capture → cleanup →
task → MicroSteps → timer → history search)
- Must-ship list per surface (product, onboarding, artefacts, docs,
quality gates, trust+security, release-blockers, smoke-test
matrix)
- Activation metrics for private beta (3 min to first capture, 3
captures in 24h, 7-day return, etc.) + v0.1 public launch
(20 install, 15 first-capture, 10 return, 5 pay-£39)
- Pre-tag verification sequence
- Explicit out-of-scope list (Garden Inbox, Phases B-E/G/I/J, etc.)
docs/release/v0.1-known-limitations.md
- User-facing rewrite, not engineer-speak
- Power assertions per platform (Linux idle / macOS App Nap / Windows
sleep) with practical workarounds
- MCP read-only/local-only posture with the
"all transcripts visible to your wired client" honest nuance
- AI cleanup/extraction failure table — what fails, what you see,
what's preserved
- Settings page progressive-disclosure status
- Internal engine refactor (orchestrator dormant) framed for users
- Explicit "what's NOT in v0.1" call-outs
- Reporting issues + crash-dump location
docs/release/v0.2-garden-roadmap.md
- Headline: "review cards for turning messy dictations into notes,
tasks, topics and links" — tangible, not PKM-overloaded
- Garden Inbox scope (raw / cleaned / suggested title-type-folder-
project / extracted tasks / suggested tags / possible links /
confidence / Accept-Edit-Park-Archive)
- Engine architecture Phases B-E pairing
- Explicit "NOT in v0.2" list (no graph, no canvas, no PKM marketing,
no cloud provider, no premium voices)
- Open decisions for v0.2 scope freeze deferred until v0.1 ships +
20 testers run
docs/release/how-lumotia-is-built.md
- Public-facing trust page; honest disclosure that AI-assisted
human-directed, then evidence
- The real silent-data-loss bug the drill caught (Phase A.7 fix
ff8dda0) framed as proof the process works
- Phase B atomiser audit: 9 surgical fixes including the FIFO hang,
LlmEngine unload race, purge-vs-restore SELECT-then-DELETE race
- Supply-chain pre-flight (npm audit signatures + --ignore-scripts +
pinned dev deps + pinned rust toolchain)
- MCP read-only audit + LLM failure audit cross-referenced
- Anti-patterns explicitly avoided (no telemetry exfiltration, no
silent AI dependency, no "audit log later", etc.)
- Calibrated to "AI use is survivable; sloppy undisclosed untested
AI use is not" — RPCS3 framing cited
Verification:
- cargo fmt --check: clean (no Rust changed)
- All four docs are user-readable, not commit-log-derivative
- Cross-references resolve (every internal path quoted exists)
160 lines
9.0 KiB
Markdown
160 lines
9.0 KiB
Markdown
---
|
||
name: v0.1-checklist
|
||
type: release
|
||
tags: [release, v0.1, checklist, tester-acceptance, activation-metrics]
|
||
description: "Source of truth for 'are we allowed to ship v0.1?'. The must-ship list, the 10-step tester acceptance test, the activation metrics for private beta + v0.1, signing/notarisation status, and the per-platform smoke-test matrix. Updated whenever an item lands."
|
||
---
|
||
|
||
# Lumotia v0.1 release checklist
|
||
|
||
**Locked scope:** v0.1 ships the stable local capture product. Garden Inbox is v0.2. Cloud providers stay dormant. OEM verification stays v0.2+. See `docs/release/v0.2-garden-roadmap.md` for what comes next.
|
||
|
||
**Tag-eligible when:** every item below is ✅ or explicitly waived in the linked known-limitations row.
|
||
|
||
## The tester acceptance test (private beta spine)
|
||
|
||
The product is ready when a stranger can complete this flow on a fresh install, on their primary platform, without coaching. Time it: if it takes more than ten minutes including the model download, the onboarding needs more work.
|
||
|
||
1. Install Lumotia from the artefact for their platform.
|
||
2. Open the app. First-run onboarding starts automatically.
|
||
3. Grant microphone permission via the OS prompt the onboarding surfaces.
|
||
4. Pick or download a speech model (sensible default suggested).
|
||
5. Test recording (a short pre-supplied prompt the onboarding asks them to read).
|
||
6. See the live transcript appear.
|
||
7. Stop dictation. See the cleaned transcript.
|
||
8. Extract one task from the transcript.
|
||
9. Break the task into MicroSteps and start a 5-minute timer on the first one.
|
||
10. Find the dictation again in History via search.
|
||
|
||
Every step has a green path. Every step has a clearly-named failure mode in the known-limitations doc. No step depends on a feature that's marked v0.2 or later.
|
||
|
||
## Must-ship
|
||
|
||
### Product surface (already shipped, verify via Phase A/B/C dogfood passes)
|
||
|
||
- [ ] Phases 1–8 functional on Linux primary, parity-tested on macOS + Windows
|
||
- [ ] Phase 9a — native OS save-dialog Markdown export (single + bulk + collision-suffixing)
|
||
- [ ] Phase 9b — LLM content tags with manualTags promote-on-click
|
||
- [ ] Phase 9d — sparkline + badge a11y + `prefers-reduced-motion` respect
|
||
- [ ] Phase 9c — Settings sanity pass: Start Here / transcription basics / model picker / privacy / accessibility / advanced (full 7-group regroup deferred to v0.2)
|
||
|
||
### First-run onboarding (engine architecture Phase F — promoted to v0.1 must-ship)
|
||
|
||
- [ ] Onboarding steps wired in `src/lib/pages/FirstRunPage.svelte`: permissions → model check/download → test recording → cleaned transcript surfaced → "you're ready" → main UI
|
||
- [ ] First-run gate routes anyone with no onboarding-event record through this flow
|
||
- [ ] `onboarding_events` SQLite table (`completed_at`, `skipped`, `version`) + migration
|
||
- [ ] Onboarding Tauri commands
|
||
- [ ] Skip-onboarding path for users who already have transcripts on disk (post-rebrand migration)
|
||
- [ ] Time-to-first-capture measurable from the onboarding events (raw signal for activation metrics)
|
||
|
||
### Release artefacts + trust path
|
||
|
||
- [ ] Three-way version sync: `Cargo.toml` workspace + `src-tauri/Cargo.toml` + `package.json` + `tauri.conf.json` all on `0.1.0`
|
||
- [ ] `CHANGELOG.md` seeded with Phase 1–8 outcomes in end-user voice (not commit-log style)
|
||
- [ ] Release notes drafted in plain language (one page max, no jargon)
|
||
- [ ] Windows code-signing certificate sourced + signing wired into `tauri build`
|
||
- [ ] macOS notarisation + Gatekeeper acceptance via Apple Developer ID (or documented Gatekeeper-warning workaround if notarisation isn't available)
|
||
- [ ] Linux AppImage SHA-256 checksum published alongside artefact + GPG signature optional
|
||
- [ ] "What warning you may see on first install" documented per platform (SmartScreen / Gatekeeper)
|
||
- [ ] CI green on Linux/macOS/Windows artefact builds on tag push
|
||
- [ ] Manual smoke-test on each platform artefact before public release (see matrix below)
|
||
|
||
### Documentation surface
|
||
|
||
- [ ] `docs/release/v0.1-known-limitations.md` complete + user-readable
|
||
- [ ] `docs/release/how-lumotia-is-built.md` complete + linked from README
|
||
- [ ] Privacy + AI-use disclosure page (what stays local, what optionally reaches the network, what NEVER leaves the machine)
|
||
- [ ] README updated for v0.1 launch: install paths per platform, first-run expectations, where to file issues
|
||
|
||
### Quality gates carried forward from Phase A + B
|
||
|
||
- [ ] `cargo test --workspace` — green
|
||
- [ ] `cargo fmt --check` — clean
|
||
- [ ] `cargo clippy --workspace --all-targets -- -D warnings` — clean
|
||
- [ ] `npm run test` — green
|
||
- [ ] `npm run check` — 0 errors / 0 warnings
|
||
- [ ] `scripts/dogfood-rebrand-drill.sh` — 8/8 probes pass (carry from Phase A)
|
||
- [ ] Rust toolchain still pinned to `rust-toolchain.toml`
|
||
- [ ] npm dev deps still exact-pinned
|
||
|
||
### Trust + security boundary verified
|
||
|
||
- [ ] MCP surface read-only / stdio-only / no write tools confirmed (see Audit 1 in `docs/release/how-lumotia-is-built.md`)
|
||
- [ ] LLM failure paths preserve raw transcript / extract tasks via fallback / never block export (see Audit 2 in `docs/release/how-lumotia-is-built.md`)
|
||
- [ ] `lumotia-cloud-providers` crate compiles but has no UI exposure (KI-04)
|
||
- [ ] `npm audit signatures` runs in `run.sh` and on CI before any tag
|
||
|
||
### Release-blocker resolution
|
||
|
||
- [ ] **RB-08** macOS App Nap power-assertion runtime verification on Apple Silicon (resolve or document with workaround per `KI-01`)
|
||
- [ ] Decision recorded per platform-power-assertion item: KI-02 Linux idle inhibit, KI-03 Windows sleep prevention — fix-if-tiny vs document-as-known-limitation (see known-limitations doc)
|
||
|
||
### Smoke-test matrix (executed against final tagged artefacts)
|
||
|
||
| Platform | Install | First-run | Capture | Cleanup | Export | History search | Uninstall + reinstall preserves transcripts |
|
||
|---|---|---|---|---|---|---|---|
|
||
| Linux (AppImage on Fedora) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||
| Linux (AppImage on Ubuntu LTS) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||
| macOS (Apple Silicon, .dmg) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||
| macOS (Intel, .dmg) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||
| Windows (.msi on Win 11) | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
|
||
|
||
A single ❌ in any cell is a tag-blocker.
|
||
|
||
## Activation metrics
|
||
|
||
### Private beta (closed, ~20 testers)
|
||
|
||
Defined activation:
|
||
|
||
- **Activation:** Tester completes their first recording within **3 minutes** of opening the app for the first time.
|
||
- **Core value:** Tester creates **3 useful captures** in the first 24 hours.
|
||
- **Retention:** Tester returns within **7 days** and uses history / search / review.
|
||
- **Quality:** Tester accepts or edits at least **one extracted task**.
|
||
- **Trust:** Tester can articulate **what stays local** if asked.
|
||
|
||
Capture mechanism: opt-in anonymous local-only telemetry (`onboarding_events` table + a tiny `lumotia_events` table for first-capture / first-export / first-search events). No exfiltration. The tester reads these themselves and reports back qualitatively.
|
||
|
||
### Public v0.1 launch (open download)
|
||
|
||
Defined pass-bar:
|
||
|
||
- Can **20 strangers** install Lumotia successfully?
|
||
- Can **15 of them** complete first capture?
|
||
- Can **10 of them** use it twice within a week?
|
||
- Can **5 of them** say they would pay **£39** for a Founding Licence?
|
||
|
||
If we don't hit these numbers, the answer is iteration on first-run + clarity-of-pitch, not feature additions.
|
||
|
||
## Out of scope for v0.1 (explicit non-goals)
|
||
|
||
To stop ourselves second-guessing under release pressure, these are pinned **not in v0.1**. Reopening any of them moves the ship date.
|
||
|
||
- Garden Inbox / review cards / suggested routing → **v0.2**
|
||
- Engine Phase B filter-chain refactor → **v0.2**
|
||
- Engine Phase C vocabulary crate → **v0.2**
|
||
- Engine Phase D model warmup coordinator → **v0.2**
|
||
- Engine Phase E dictionary quick-add → **v0.2**
|
||
- Engine Phase G OpenAI Whisper API provider → **v0.2 at earliest, with BYOK / off-by-default / never-required / clearly-labelled framing**
|
||
- Engine Phase I OEM verification → **v1.0 commercial track**
|
||
- Engine Phase J full degraded-mode indicator → **v0.2** (data-loss path closed in v0.1 per Audit 2; the UI-wedge case is documented in known-limitations)
|
||
- Full SettingsPage 7-group regroup → **v0.2**
|
||
- Rust-side OS-activity watcher for nudges → **v0.2 if ever**
|
||
- Obsidian plugin → **v0.2 ecosystem play**
|
||
- Mobile companion → not on any current track
|
||
- Cloud sync → not on any current track
|
||
|
||
## Pre-tag verification (the morning of)
|
||
|
||
In order, before `git tag v0.1.0`:
|
||
|
||
1. Re-run all quality gates fresh on a clean checkout.
|
||
2. Re-run `scripts/dogfood-rebrand-drill.sh` against a freshly-built binary.
|
||
3. Re-execute the 10-step tester acceptance flow personally on Linux.
|
||
4. Confirm the smoke-test matrix is fully green for the platforms we're announcing.
|
||
5. Confirm known-limitations doc has no item marked "TBD" or "pending decision".
|
||
6. Confirm `CHANGELOG.md` + release notes are user-readable, not commit-log dumps.
|
||
7. Tag, push to both remotes, watch CI complete the per-platform builds, smoke-test one artefact per platform from the CI output.
|
||
|
||
If any step fails, the day's ship is off. Reopen, fix, repeat.
|