From 78f09d386d09362e2da87c565c95411095e5cf4c Mon Sep 17 00:00:00 2001 From: Ross Tomsic Date: Fri, 25 Sep 2026 00:14:24 -0400 Subject: [PATCH] Record everyday-use roadmap --- PROJECT_SPEC.md | 47 ++++++++++++++++++++++++++++++++++++------ README.md | 32 ++++++++++++++-------------- docs/BACKLOG.md | 50 +++++++++++++++++++++++++------------------- docs/STATUS.md | 55 ++++++++++++++++++++++++++++++++++++------------- 4 files changed, 128 insertions(+), 56 deletions(-) diff --git a/PROJECT_SPEC.md b/PROJECT_SPEC.md index 763166d..c4f09a4 100644 --- a/PROJECT_SPEC.md +++ b/PROJECT_SPEC.md @@ -4,12 +4,16 @@ > > **Product:** A transcript-first, touch-native SSH client for Android with a real terminal as a seamless fallback. > -> **Status:** Exploratory MVP specification +> **Status:** Exploratory MVP baseline with an everyday-use refinement roadmap > > **Primary implementation target:** Native Android, Kotlin, Jetpack Compose --- +Sections describing the exploratory MVP record the implemented baseline. The +everyday-use refinement section below supersedes them where its planned behavior +differs; [current status](docs/STATUS.md) distinguishes shipped work from issues. + ## 1. Product thesis Most Android SSH clients optimize for faithfully reproducing a desktop terminal on a phone. @@ -1097,8 +1101,8 @@ Exit criterion: > The app can be handed to a technical alpha tester without knowingly unsafe defaults. Implementation status (2026-07-31): the required deliverables are implemented. -Device-credential and biometric gating remain optional backlog decisions rather -than phase exit criteria. +Device-credential and biometric gating were optional for the MVP. Per-use +approval for future saved SSH passwords is now planned in #46. ### Phase 5 — Alpha polish @@ -1114,7 +1118,7 @@ Deliverables: - Exportable sanitized bug report - Signed internal APK -Exit criterion: +Original exit criterion, superseded on 2026-09-25 without being met: > Ten real users can perform small remote tasks for two weeks and provide useful product feedback. @@ -1164,10 +1168,41 @@ gate. Independent CI passed, and the resulting permanent-key alpha.6 installed over alpha.5 with retained state intact. Password and retained imported-key authentication, Diagnostics, structured commands, and same-session raw-terminal behavior passed on the Galaxy S25 Ultra. Alpha.6 is the accepted tester build. -Alpha distribution is direct invited sharing while Phase 5 is open. Because the +Alpha distribution was direct invited sharing during Phase 5. Because the repository is public, any published GitHub prerelease would be public. Sufficient invited technical-alpha use is the -remaining Phase 5 boundary. +original Phase 5 boundary, now superseded by the everyday-use roadmap. + +### Everyday-use refinement (current roadmap) + +[Roadmap issue #44](https://github.com/R055LE/threadline/issues/44) replaces the +unfinished Phase 5 exit criterion. Its implementation issues are ordered around +connection, the command loop, multiple sessions, then transcript polish and +release validation. Signed builds continue through invited sharing; public +release requires a separate decision. + +- A reusable SSH identity contains a remote username and a password or imported-key + choice. A host profile may remember a preferred identity. Existing usernames + migrate without guessing or copying credentials. +- Saved SSH passwords are opt-in and require device approval for each use on + Android 11 or newer. Older supported devices keep session-only passwords. + Imported-key passphrases and replies to privilege prompts remain session-only. +- A running transcript command can accept user-initiated ordinary or masked PTY + replies. Replies are separate from the next command draft and are not stored as + commands or diagnostic input. Remote output is untrusted and can still echo or + print a secret; prompt recognition never authenticates a request. +- Automatic execution routing keeps straightforward shell-state changes in the + persistent Bash shell, isolates recognizable strict or shell-terminating + commands, and asks before ambiguous mixed commands. An accessible override + remains. A failed or exited shell offers an explicit fresh connection and + never claims to preserve lost shell state. +- Up to three SSH sessions may be live at once. Each has its own PTY, terminal, + transcript, draft, and lifecycle. The foreground service remains active while + any session is live. Process death ends live sessions; archived output is not a + resumed connection. +- Completed turns are checkpointed during a live non-ephemeral session. Saved + history search and large-output navigation operate within bounded retention. + Ephemeral sessions write no command or output history. --- diff --git a/README.md b/README.md index c9f4a3b..a3dd393 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,15 @@ Threadline is an exploratory, transcript-first SSH client for Android. The product idea is that commands should feel like messages and output should feel like responses, while a real terminal remains underneath for interactive work. -## Alpha status +## Current roadmap and alpha status -**[Phase 5: Alpha polish](docs/STATUS.md) is in progress.** Its feature slices -and owner-device acceptance through alpha.11 are complete. Alpha.5 installed in +The [everyday-use roadmap](https://github.com/R055LE/threadline/issues/44) is +the current work track. It starts with faster connection, then improves the +command loop, multiple sessions, and transcript navigation. Phase 5's original +ten-user, two-week exit criterion was superseded without being met. + +Phase 5's feature slices and owner-device acceptance through alpha.11 are +complete. Alpha.5 installed in place but is rejected because a release-shrinker failure prevents SSH connection. Alpha.6 corrects that failure and has passed independent CI, permanent signing, in-place update, and physical acceptance. Alpha.7 adds local @@ -23,15 +28,15 @@ anchors completed turns at the start of the new card while preserving bottom-follow for active output. Its signed owner-device check passed the same four-step sequence. Alpha.12 is the current source candidate. It adds an explicit raw-terminal Keyboard action and keeps the Transcript/Terminal switch -at the right side of the connected header in both views. The remaining product -boundary is invited technical-alpha use sufficient to evaluate whether ten real -users can complete small remote tasks for two weeks and provide useful feedback. +at the right side of the connected header in both views. The current issue +sequence and acceptance boundaries are in [the status page](docs/STATUS.md). The current accepted signed build is `0.1.0-alpha.11`; the current source candidate is `0.1.0-alpha.12`. Alpha.5, alpha.9, and alpha.10 are immutable rejected artifacts. Alpha.12 owner-device acceptance is pending. Signed builds are shared directly with invited testers. -There is no public signed APK or GitHub prerelease while Phase 5 is open. +There is no public signed APK or GitHub prerelease during the everyday-use +roadmap; public release is a separate decision. Testers should obtain the APK and its checksum from the owner through the agreed private channel, then follow the [technical-alpha guide](docs/alpha-testing.md). @@ -280,14 +285,11 @@ risks are recorded in ## Project status -Phases 0 through 4 are complete. **Phase 5: Alpha polish is in progress.** Its -accessibility/error, large-output performance, Samsung physical-validation, and -basic-onboarding slices are implemented. The installed-update preservation -check is complete. Direct invited sharing is the selected alpha distribution -path, with no public prerelease while Phase 5 remains open. Sufficient -technical-alpha use is the remaining boundary. Additional device and OEM -coverage, including Pixel, is opportunistic alpha evidence rather than a -separate release gate. +Phases 0 through 4 are complete. Phase 5's accessibility/error, large-output +performance, Samsung physical-validation, basic-onboarding, and installed-update +preservation slices are implemented. Its original technical-alpha exit criterion +was superseded, not completed. Direct invited sharing continues for the +everyday-use roadmap; additional device and OEM coverage remains useful evidence. Alpha packaging preparation now defines the permanent release/debug identities, explicit alpha versioning, interactive off-repository key creation, local diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 3a5ae38..626a1b0 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -1,12 +1,14 @@ # Threadline backlog -This file records deliberately deferred product and hardening decisions. Items -here are not part of the current phase exit criteria unless they are explicitly -promoted into a milestone. +This file records deferred product and hardening decisions and the reasoning +behind items now promoted into the everyday-use roadmap. Current priorities and +issue links are in [STATUS.md](STATUS.md) and +[roadmap #44](https://github.com/R055LE/threadline/issues/44). ## Device-credential gating -**Status:** Deferred optional hardening; not a Phase 4 blocker. +**Status:** Per-use device approval for opt-in saved SSH passwords is planned +in #46; gating existing imported keys remains deferred. Threadline does not currently persist passwords or private-key passphrases. Imported private keys are encrypted at rest by an app-scoped Android Keystore @@ -19,7 +21,8 @@ looks like when the platform credential is unavailable. ## Biometric gating -**Status:** Deferred optional hardening; not a Phase 4 blocker. +**Status:** A supported strong biometric is one allowed approval method for +saved SSH passwords in #46. Gating existing imported keys remains deferred. Biometrics are not desired where they do not address a demonstrated risk. Do not add a biometric prompt merely because the platform supports one. Reconsider @@ -34,8 +37,7 @@ claimed. ## Expanded large-output navigation -**Status:** Deferred visual and interaction polish; not a Phase 5 performance -blocker. +**Status:** Promoted to #56 for the everyday-use roadmap. Physical Samsung validation confirmed that expanding and collapsing the retained 128 KiB transcript tail remains functional without freezing. The @@ -159,8 +161,8 @@ made that execution contract unambiguous. ## Persistent-shell exit recovery -**Status:** Isolated execution implemented and physically accepted in alpha.8; -automatic shell restart remains deferred. +**Status:** Isolated execution was accepted in alpha.8. Explicit fresh-shell +recovery is planned in #50; automatic routing is planned in #51–#52. Transcript Send intentionally evaluates inside the persistent Bash shell so directory changes, exports, aliases, and functions survive between cards. That @@ -186,8 +188,8 @@ process that died with the old shell. ## Responses to running commands -**Status:** Deferred interaction and security design; same-session raw terminal -input is the current path. +**Status:** User-initiated ordinary and masked replies are planned in #48; +same-session raw terminal input is the current path. Plain prompts such as `read -p`, package-manager confirmations, and `sudo` password requests do not necessarily emit terminal control sequences. The @@ -208,8 +210,8 @@ Keep a manual terminal handoff reachable for every running command. ## Opt-in saved password authentication -**Status:** Deferred product and security decision; not an assumed future -feature. +**Status:** Opt-in saved SSH passwords with per-use device approval are planned +in #46; passwords remain session-only in current builds. Passwords are currently session-only by design. Threadline already has app-scoped Android Keystore encryption for imported private keys, but applying @@ -224,7 +226,8 @@ saved host profile into a saved credential. ## Transcript-history presentation -**Status:** Deferred UX polish; current bounded plain history is functional. +**Status:** Saved-history search is planned in #55; other presentation polish +remains deferred. Current bounded plain history is functional. Physical testing confirmed that persisted sessions and turns can be recovered, but the archive presentation is deliberately utilitarian. A later design pass @@ -242,8 +245,8 @@ and the rule that history must not accidentally become credential storage. ## Home navigation and session dashboard -**Status:** One retained active session implemented and physically accepted in -alpha.7; multiple concurrent sessions deferred. +**Status:** One retained active session was accepted in alpha.7. Three +independent live sessions and switching are planned in #53–#54. Threadline now allows navigation Home while retaining the one active foreground-service-backed session. Home identifies the active session, offers @@ -301,7 +304,8 @@ layout choice that can be tested in both modes. ## Deferred connection-profile options -**Status:** Deferred product design; not required for the current MVP or Phase 5. +**Status:** Reusable identity selection and a preferred identity per profile are +planned in #45–#47. Other profile options remain deferred. The current host profile intentionally stores display name, endpoint, and username without an authentication mode or credentials. Before adding an @@ -341,7 +345,8 @@ persisted output or metadata remains reachable elsewhere. ## Live transcript search -**Status:** Deferred transcript polish; persisted-history search is also future work. +**Status:** Live search remains deferred; bounded saved-history search is +planned in #55. Search must define whether it covers the retained in-memory tail, collapsed content, ANSI-styled text, the current session, saved history, or all of them. @@ -350,7 +355,9 @@ secondary index of terminal output. ## Technical-alpha evidence collection -**Status:** Design before implementation; no remote analytics are authorized. +**Status:** The original ten-user Phase 5 criterion was superseded without being +met. Invited-tester acceptance for the everyday-use roadmap is planned in #57; +no remote analytics are authorized. The alpha needs enough evidence to distinguish isolated test success from useful day-to-day behavior. Start with an explicit tester checklist, a short feedback @@ -362,8 +369,9 @@ content, host data, or terminal output merely to claim that metrics exist. ## Automated release-path and device acceptance -**Status:** Deferred test-infrastructure design; manual physical acceptance -through alpha.8 is complete. +**Status:** Combined minified, installed-update, owner-device, and invited-tester +validation is planned in #57. Earlier manual physical acceptance remains valid +for the builds it covered. The core debug Android suite and static release-shrinker checks run in public CI, but alpha.5 showed the remaining gap: assembling a minified APK is not the same diff --git a/docs/STATUS.md b/docs/STATUS.md index fc196e5..51c7c3c 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,16 +1,40 @@ # Threadline current status -Updated: 2026-09-08 +Updated: 2026-09-25 This is the canonical execution-status page. `PROJECT_SPEC.md` remains the normative product and technical specification. Dated investigations are historical evidence for the boundary they record; their old "next" or "remaining" sections do not override this page. -## Current milestone +## Current milestone: everyday use -**Phase 5 — Alpha polish is in progress.** Phases 0 through 4 are complete. +The owner superseded Phase 5's ten-user, two-week exit criterion on 2026-09-25. +It was not completed. [Issue #44](https://github.com/R055LE/threadline/issues/44) +is the current roadmap; [issue #2](https://github.com/R055LE/threadline/issues/2) +is closed as superseded. Phases 0 through 4 remain complete, and the completed +Phase 5 feature slices remain part of the app. -Five Phase 5 slices are implemented: +Deliver the roadmap in four increments: + +1. **Faster connection:** reusable identities, opt-in saved SSH passwords, and + direct saved-host connection from Home (#45–#47). +2. **Smoother command loop:** manual replies to running commands, live transcript + checkpoints, explicit fresh-shell recovery, and automatic execution routing + (#48–#52). +3. **Multiple sessions:** up to three independent live SSH sessions, one-tap + switching, and an aggregate notification (#53–#54). +4. **Transcript polish and acceptance:** saved-history search, large-output + navigation, and grouped release validation (#55–#57). + +Start with the connection increment for the first tester-visible gain. Issues +without a dependency may be worked independently. Signed builds continue through +direct invited sharing; public release needs a separate decision. No feature in +this roadmap is implemented merely because its issue is open. + +## Phase 5 checkpoint (historical) + +Five Phase 5 slices were implemented before its original exit criterion was +superseded: - **Accessibility and error UX:** typed, non-secret errors; direct recovery and focus movement; assertive announcements; navigable headings; spoken terminal-key labels; and connected-session @@ -232,15 +256,18 @@ final brand design remains out of scope. This also does not require a dedicated signed alpha. In-place update and owner-device launcher-mask acceptance remain for the next shared candidate. -## Remaining Phase 5 boundaries +## Superseded Phase 5 boundary -- Technical-alpha use sufficient to evaluate the Phase 5 exit criterion. +The technical-alpha use criterion was superseded by the everyday-use roadmap in +#44 and closed as #2. This is a change of goal, not evidence that ten users +completed two weeks of use. ## Alpha distribution: direct invited sharing, decided 2026-08-09 -The alpha goes to invited testers directly. **No public GitHub prerelease while -Phase 5 is open**, even though this repository is public and a release would be -straightforward to publish. +The alpha goes to invited testers directly. This remains the distribution +policy through the everyday-use roadmap. The following records the original +2026-08-09 decision; no public GitHub prerelease is planned before a separate +release decision. What decided it was not caution about the artifact, which is in good shape. It was reach against contact. A public prerelease means anyone can install a build @@ -273,8 +300,7 @@ Additional physical-device and OEM coverage, including Pixel, should be collecte during technical alpha. The completed Samsung pass satisfies the dedicated physical-device boundary; no specific handset brand is a separate Phase 5 gate. -Choose the smallest remaining boundary with the user before implementation. Do not infer that the -list order is a priority decision. +Use #44 and its child issues for the current order and acceptance boundaries. ## Completed milestone summary @@ -291,6 +317,7 @@ supporting record. ## Deferred decisions -Device-credential and biometric gating are optional hardening decisions, not Phase 4 or Phase 5 -blockers. Their reconsideration criteria are recorded in the [backlog](BACKLOG.md). Passwords and -private-key passphrases remain session-only. +Per-use device approval for opt-in saved SSH passwords is planned in #46; +passwords and private-key passphrases remain session-only in current builds. +Gating existing imported keys remains a separate optional decision in the +[backlog](BACKLOG.md).