From f19dc7c26cf3b813707c94ab5f6596a31f896d5d Mon Sep 17 00:00:00 2001 From: stan44 Date: Sun, 5 Apr 2026 17:15:11 -0500 Subject: [PATCH] Document RC1 release-candidate state --- LEGACY_HARDWARE_VALIDATION.md | 28 ++++++----- README.md | 20 ++++++++ RELEASE_CANDIDATE.md | 36 ++++++++++++++ THISPER_IMPLEMENTATION_PLAN.md | 61 ++++++++++++------------ THISPER_STATUS.md | 53 ++++++++++++-------- communication_translator_project_plan.md | 9 ++++ 6 files changed, 144 insertions(+), 63 deletions(-) create mode 100644 RELEASE_CANDIDATE.md diff --git a/LEGACY_HARDWARE_VALIDATION.md b/LEGACY_HARDWARE_VALIDATION.md index 904289e..674b6e1 100644 --- a/LEGACY_HARDWARE_VALIDATION.md +++ b/LEGACY_HARDWARE_VALIDATION.md @@ -1,6 +1,6 @@ # Legacy Hardware Validation -This report exists to close the remaining Phase 2 validation work against the target profile: older desktop hardware with limited RAM where Thisper must remain responsive and low-overhead. +This report exists to close the remaining release-candidate validation work against the target profile: older desktop hardware with limited RAM where Thisper must remain responsive and low-overhead. ## Validation Checklist @@ -13,40 +13,46 @@ This report exists to close the remaining Phase 2 validation work against the ta ### Repeated Cross-App Rewrite -- Scenario: Use `Ctrl + Alt + R` repeatedly across plain-text targets such as Notepad and browser text boxes. +- Scenario: Use `Ctrl + Alt + R` repeatedly across plain-text targets such as Notepad, browser text boxes, and lightweight game chat surfaces. - Acceptance target: No destructive replacement on provider failure, no clipboard corruption after failures, stable repeated use without restart. -- Current evidence: Informal real-world usage is positive, but no structured pass is recorded yet. -- Status: `remaining` +- Current evidence: Informal real-world usage is positive across multiple programs and even some games. One known host-app incompatibility exists where the T3 Chat app steals focus on the hotkey path. +- Status: `partially validated` ### Long-Form Desktop Rewrite - Scenario: Rewrite a multi-paragraph block through the main window and inspect diff/output toggles. - Acceptance target: UI remains responsive during rewrite and the diff view reflects only actual edits. -- Current evidence: Main UI build path is working and has been used successfully, but no formal timing pass is logged yet. -- Status: `remaining` +- Current evidence: Main UI rewrite has been used successfully in normal writing flow, but no structured timing pass is logged yet. +- Status: `partially validated` ### Successive Rewrites Without Restart - Scenario: Perform multiple rewrites in sequence from both the main UI and the global shortcut flow. -- Acceptance target: No cumulative instability, no stale model state, no stuck loading state. -- Current evidence: Runtime observability is now present to support this pass, but the pass itself is still pending. -- Status: `remaining` +- Acceptance target: No cumulative instability, no stale model state, no stuck loading state, and no credential-loss regression after restart. +- Current evidence: Runtime observability and secure key persistence are in place. Informal usage is positive, but the pass itself is not fully recorded yet. +- Status: `partially validated` ### Resource Footprint - Scenario: Observe memory use and responsiveness on constrained hardware during idle, active rewrite, and tray-hidden states. - Acceptance target: No runaway memory growth and acceptable perceived latency for short text. -- Current evidence: Build/runtime artifacts are large in development, but that is mostly `target/`; release footprint still needs explicit validation. +- Current evidence: Development footprint is dominated by build artifacts in `target/`, so the meaningful missing data is runtime memory and release-build behavior on older hardware. - Status: `remaining` +## Known Compatibility Notes + +- `T3 Chat`: hotkey path can defocus the text box because the host app reacts to the shortcut first +- rich editors and secure fields: still best-effort and may not behave like plain-text targets + ## What To Record During The Pass - idle memory use - active rewrite latency for short and medium inputs - whether the tray/hotkey path remains responsive after long idle time - whether clipboard restoration remains correct after both success and failure +- whether secure credential persistence survives multiple app restarts - any target app classes that consistently fail or behave inconsistently ## Completion Rule -Phase 2 desktop validation is complete when each scenario above has an explicit observed result recorded here, including failures or caveats. +The desktop release candidate is fully validated when each scenario above has an explicit observed result recorded here, including failures or caveats. diff --git a/README.md b/README.md index 35950c3..c762c11 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,23 @@ Thisper is a typing-first communication translator. It rewrites raw text into clearer text while staying as close as possible to the original meaning, voice, uncertainty, and tone. +## Release Candidate Status + +Thisper is currently a `desktop typed-workflow release candidate`. + +What is considered in-scope and ready for release-candidate use: + +- desktop text-to-text rewrite workflow +- cross-app selected-text rewrite via `Ctrl + Alt + R` +- tray/background operation +- native secure API key persistence +- protected URL preservation + +What still remains before a broader general release: + +- structured legacy hardware validation +- final commercial license allowlist decision + ## Current Desktop Scope - Desktop text-to-text rewrite UI with diff review @@ -50,6 +67,7 @@ If no API key is configured, Thisper brings the main window forward instead of a - Secure fields and some application surfaces may block selection, copy, paste, or synthetic key events. - Clipboard restoration currently preserves prior plain-text clipboard contents. Non-text clipboard formats are not yet restored. - If a rewrite attempts to drop a protected URL, Thisper now fails that rewrite instead of silently removing the link. +- Some host apps can intercept the hotkey before Thisper sees it. The known example so far is the T3 Chat app defocusing its own text box. - Model fidelity still depends on prompt behavior. High-value detail protection is planned, but not part of the current Phase 2 completion scope. ## Setup @@ -107,6 +125,8 @@ Current status: See: +- `RELEASE_CANDIDATE.md` for the current desktop release-candidate lock - `THISPER_STATUS.md` for current completion status +- `THISPER_IMPLEMENTATION_PLAN.md` for the release-candidate scope - `LEGACY_HARDWARE_VALIDATION.md` for the Phase 2 validation checklist and report - `PHASE3_SPEECH_PLAN.md` for the queued next-phase speech scope diff --git a/RELEASE_CANDIDATE.md b/RELEASE_CANDIDATE.md new file mode 100644 index 0000000..441861a --- /dev/null +++ b/RELEASE_CANDIDATE.md @@ -0,0 +1,36 @@ +# Thisper Release Candidate + +Current designation: `RC1 candidate` + +This document locks the current desktop typed workflow into a release-candidate state. + +## Included In RC1 + +- desktop text-to-text rewrite UI +- diff review +- explicit rewrite modes +- cross-app selected-text rewrite via `Ctrl + Alt + R` +- tray/background operation +- native secure API key persistence +- protected URL preservation +- local-only runtime observability + +## Known Issues Accepted In RC1 + +- some host apps may intercept the hotkey before Thisper can act +- rich editors and secure fields remain best-effort +- non-text clipboard formats are not restored yet +- broader protected-term handling is not implemented yet + +## Exit Criteria Before General Release + +- legacy hardware validation report completed +- commercial license allowlist decision finalized +- Rust license audit policy aligned with that decision + +## Primary Reference Docs + +- `README.md` +- `THISPER_STATUS.md` +- `THISPER_IMPLEMENTATION_PLAN.md` +- `LEGACY_HARDWARE_VALIDATION.md` diff --git a/THISPER_IMPLEMENTATION_PLAN.md b/THISPER_IMPLEMENTATION_PLAN.md index 79b5bd6..21e2bb0 100644 --- a/THISPER_IMPLEMENTATION_PLAN.md +++ b/THISPER_IMPLEMENTATION_PLAN.md @@ -1,18 +1,41 @@ # Thisper Implementation Plan -This plan reflects the current repo state and the remaining work needed to close desktop Phase 2 before speech begins. +This plan reflects the current repo state and the work needed to move the desktop typed workflow from release candidate to general release. -## Completed Baseline +## Current State - Desktop text-to-text MVP is complete. - The provider boundary exists and Gemini is integrated. -- Secure credential storage is implemented. +- Native secure credential storage is implemented. - Global shortcut and clipboard rewrite are implemented. -- Streaming rewrite is implemented. - Tray and background lifecycle are implemented. - Runtime observability is implemented locally in-memory. +- Protected URL preservation is implemented. -## Remaining To Close Phase 2 +## Release Candidate Scope + +The current release candidate covers the desktop typed workflow only. + +### Included + +- main rewrite UI +- explicit rewrite modes +- diff review +- copy output +- secure settings for the Gemini API key +- `Ctrl + Alt + R` selected-text rewrite +- tray/background operation +- native secure credential handling +- protected URL preservation + +### Known Limits Accepted For The Release Candidate + +- rich editors and some browser surfaces are still best-effort +- non-text clipboard formats are not restored yet +- host-app hotkey conflicts can still occur in specific apps +- broader high-value term protection is not implemented yet + +## Remaining To Close Before General Release ### 1. Validation @@ -25,34 +48,10 @@ This plan reflects the current repo state and the remaining work needed to close - Decide the commercial allowlist policy. - Update Rust audit configuration to match that policy. -## Current Desktop Contract - -### Main UI - -- typed input and output panes -- explicit rewrite modes -- diff review -- copy output -- secure settings for the Gemini API key - -### Cross-App Utility - -- `Ctrl + Alt + R` triggers selected-text rewrite -- default global mode is `Preserve Voice` -- selected text is only replaced after a complete rewrite succeeds -- app can remain hidden in the tray while the hotkey stays active - -### Tray Lifecycle - -- closing the main window does not quit by default -- first close shows a tray hint -- later closes hide to tray -- tray menu supports show, rewrite, and quit - ## Queued Next -After Phase 2 is closed: +After the desktop release candidate is validated: 1. start the speech phase from `PHASE3_SPEECH_PLAN.md` -2. queue trust refinements such as protected terms and high-value detail preservation +2. expand trust protections beyond URLs into protected terms and factual tokens 3. revisit optimization work only after validation data exists diff --git a/THISPER_STATUS.md b/THISPER_STATUS.md index 6e3658f..0637a6e 100644 --- a/THISPER_STATUS.md +++ b/THISPER_STATUS.md @@ -2,28 +2,32 @@ This is the single source of truth for current delivery status. +Current release state: `desktop typed-workflow release candidate` + +Phase 2 feature scope is implemented. The remaining work is validation and release-policy closure, not missing core desktop functionality. + ## Completed ### Desktop MVP Foundation - Status: `completed` -- Rationale: The desktop app, main rewrite UI, mode selector, copy flow, and diff review are all implemented and working. +- Rationale: The desktop app, main rewrite UI, mode selector, copy flow, and diff review are implemented and in active use. - Acceptance condition: User can paste text, rewrite it, inspect diff, and copy output without leaving the app. - Repo pointer: `src/`, `index.html`, `src/styles.css`, `src-tauri/src/lib.rs` ### Provider Abstraction And Gemini Integration - Status: `completed` -- Rationale: Rewrite logic is abstracted behind a provider trait and Gemini is implemented as the current backend, including streaming. +- Rationale: Rewrite logic is abstracted behind a provider trait and Gemini is implemented as the current backend. - Acceptance condition: Main UI and cross-app rewrite both run through the provider boundary instead of hard-coded prompt logic in the UI. - Repo pointer: `src-tauri/src/translator.rs`, `src-tauri/src/gemini.rs`, `src-tauri/src/lib.rs` -### Secure Credential Storage +### Native Secure Credential Storage - Status: `completed` -- Rationale: The Gemini API key is stored in the system credential store rather than a plaintext app file. -- Acceptance condition: Saving a key through Settings persists it securely across app restarts. -- Repo pointer: `src-tauri/src/lib.rs`, `README.md` +- Rationale: API key storage now uses native platform protection instead of a misleading generic claim. On Windows this is DPAPI-encrypted app-local storage; other supported desktop platforms continue to use the native credential backend. +- Acceptance condition: Saving a key through Settings persists it securely across app restarts and the key is never written in plaintext. +- Repo pointer: `src-tauri/src/credentials.rs`, `src-tauri/src/lib.rs`, `README.md` ### Global Shortcut And Clipboard Rewrite @@ -35,17 +39,24 @@ This is the single source of truth for current delivery status. ### Tray And Background Operation - Status: `completed` -- Rationale: Thisper now supports tray-based lifecycle management and continued hotkey operation while the window is hidden. +- Rationale: Thisper supports tray-based lifecycle management and continued hotkey operation while the window is hidden. - Acceptance condition: Closing the window hides to tray after the first hint, tray actions restore or quit correctly, and the hotkey remains active while hidden. - Repo pointer: `src-tauri/src/lib.rs`, `src/main.ts`, `index.html`, `src/styles.css` ### Runtime Observability - Status: `completed` -- Rationale: In-memory runtime metrics now track rewrite attempts, success/failure counts, last error, last model, and last rewrite duration. -- Acceptance condition: Frontend can query and display runtime status without storing raw user text. +- Rationale: In-memory runtime metrics track rewrite attempts, success/failure counts, last error, last model, and last rewrite duration without storing raw user text. +- Acceptance condition: Frontend can query and display runtime status locally. - Repo pointer: `src-tauri/src/lib.rs`, `src/main.ts` +### Protected URL Preservation + +- Status: `completed` +- Rationale: Links are now treated as protected content and may not be silently removed during rewrites. +- Acceptance condition: If a rewrite tries to drop a protected URL, it fails instead of returning altered text. +- Repo pointer: `src-tauri/src/gemini.rs`, `README.md` + ### License Audit Automation - Status: `completed` @@ -53,13 +64,13 @@ This is the single source of truth for current delivery status. - Acceptance condition: `licenses:npm`, `licenses:rust`, and `licenses:all` are available and documented. - Repo pointer: `package.json`, `src-tauri/deny.toml`, `README.md` -## Remaining For Phase 2 Completion +## Remaining Before General Release ### Legacy Hardware Validation Pass - Status: `remaining` - Rationale: The implementation is in place, but the acceptance report still depends on a structured pass against the target hardware profile. -- Acceptance condition: The validation checklist is executed and the report is updated with actual observed results. +- Acceptance condition: The validation checklist is executed and the report is updated with explicit observed results. - Repo pointer: `LEGACY_HARDWARE_VALIDATION.md` ### Commercial License Allowlist Decision @@ -69,19 +80,19 @@ This is the single source of truth for current delivery status. - Acceptance condition: A written allowlist decision is made and the Rust audit configuration is aligned with that decision. - Repo pointer: `src-tauri/deny.toml`, `README.md` -## Queued After Phase 2 +## Queued After Release Candidate ### Speech Input Phase - Status: `queued` -- Rationale: Speech is the next planned phase after desktop Phase 2 is closed, but it is not part of current completion criteria. -- Acceptance condition: Phase 2 is marked complete and the speech scope starts from the queued plan. +- Rationale: Speech is the next planned phase after the current desktop release candidate is validated. +- Acceptance condition: Release-candidate validation is closed and the speech scope starts from the queued plan. - Repo pointer: `PHASE3_SPEECH_PLAN.md` -### High-Value Detail Protection +### High-Value Detail Protection Expansion - Status: `queued` -- Rationale: Protected terms, factual token preservation, and drift flags are important trust refinements, but they are not blocking current Phase 2 completion. +- Rationale: URLs are protected now, but broader protected terms, factual token preservation, and drift flags are still future trust refinements. - Acceptance condition: Add protected-term rules, token-preservation checks, and a stricter retry path without breaking current flows. - Repo pointer: `communication_translator_project_plan.md` @@ -90,20 +101,20 @@ This is the single source of truth for current delivery status. ### Mobile Platforms - Status: `deferred` -- Rationale: Android and iOS are not part of current Phase 2 desktop completion. +- Rationale: Android and iOS are not part of the current desktop release candidate. - Acceptance condition: Revisit after speech planning and desktop validation. - Repo pointer: `PHASE3_SPEECH_PLAN.md` ### Local Models And Multi-Provider Routing - Status: `deferred` -- Rationale: The provider boundary exists, but local execution and multi-provider fallback are not required to close the current desktop scope. -- Acceptance condition: Re-enter scope only after current desktop workflow is fully validated. +- Rationale: The provider boundary exists, but local execution and multi-provider fallback are not required for the current desktop release candidate. +- Acceptance condition: Re-enter scope only after the current desktop workflow is fully validated. - Repo pointer: `src-tauri/src/translator.rs` ### Major UI Redesign - Status: `deferred` -- Rationale: Current priority is lifecycle reliability and trust, not visual redesign. -- Acceptance condition: Only revisit after Phase 2 acceptance and trust refinements. +- Rationale: Current priority is reliability, trust, and release readiness, not visual redesign. +- Acceptance condition: Only revisit after release-candidate validation and trust refinements. - Repo pointer: `src/`, `index.html`, `src/styles.css` diff --git a/communication_translator_project_plan.md b/communication_translator_project_plan.md index 2ec092a..0149715 100644 --- a/communication_translator_project_plan.md +++ b/communication_translator_project_plan.md @@ -1,5 +1,14 @@ # Communication Translator Project Plan +This document is the long-term product vision and design philosophy. + +For current implementation state and release readiness, use: + +- `README.md` +- `RELEASE_CANDIDATE.md` +- `THISPER_STATUS.md` +- `THISPER_IMPLEMENTATION_PLAN.md` + ## Working Name Use a placeholder name until the product identity becomes obvious through use.