[WS-CLI-001-49] Add TUI guide downloads and findings

.commitrail/INDEX.md

@@ -11,7 +11,7 @@ for current product capability.
 | [WS-AGENT-001](initiatives/WS-AGENT-001/OVERVIEW.md) | Planned | Neutral document tools plus OpenAI Agents SDK and OmniCoreAgent original-guide qualifications are delivered through the same public API, durable worker, parser and MinIO path. Retain the exact external provider/account and selected-image AWS evidence, then prove the broader hosted Flow contribution journey before deployment claims. |
 | [WS-DB-002](initiatives/WS-DB-002/OVERVIEW.md) | Complete | Shared UUIDv7 record generation, native-UUID relationships and fresh v0.1 baseline; natural-owner retry custody and aligned CI/local setup |
 | [WS-MCP-002](initiatives/WS-MCP-002/OVERVIEW.md) | Planned | 108 tools through WS-MCP-002-12 cover access, guide setup, contributor workspace, contribution policies, checker/artifact operations and task execution/submissions; task operations/imports and assembled release proof remain. |
-| [WS-CLI-001](initiatives/WS-CLI-001/OVERVIEW.md) | Planned | Public Go CLI setup, contributor/manager workflows, administrative and operational commands, Finance policies and contribution exports are detailed in the overview; -43 proves the connected local unpaid automated-acceptance journey. -44 prepares four native release archives and a gated manual publisher; -47 hardens its administrator-bypass guard. Protected release-environment and immutable-tag ruleset configuration/verification, first publication and public-asset audit remain. -46 adds the separate system-reader project catalogue; -48 adds the opt-in read-only contributor TUI. Detailed findings/Evidence remain manual CLI handoffs; TUI writes/management, public human-review controls and hosted proof are separate. Current revision context never substitutes for historical evidence. |
+| [WS-CLI-001](initiatives/WS-CLI-001/OVERVIEW.md) | Planned | Public Go CLI setup, contributor/manager workflows, administrative and operational commands, Finance policies and contribution exports are detailed in the overview; -43 proves the connected local unpaid automated-acceptance journey. -44 prepares four native release archives and a gated manual publisher; -47 hardens its administrator-bypass guard. First publication and public-asset audit remain operational work. -46 adds the separate system-reader project catalogue; -48 adds contributor TUI navigation and -49 adds findings pages and confirmed verified guide downloads. Evidence remains a manual CLI handoff; TUI product writes/management, public human-review controls and hosted proof are separate. Current revision context never substitutes for historical evidence. |
 | [WS-ARCH-001](initiatives/WS-ARCH-001/OVERVIEW.md) | Planned | Public admission-backed initial/remediation Submission entry and supported false-policy guide activation are implemented over selected production delivery. New false/pass effects require LIVE REV; a known pre-effect non-live refusal has bounded retry, with exhausted delivery dead-lettered. The [bounded local public/worker drill](initiatives/WS-ARCH-001/planning/PLAN.md#first-complete-contributor-milestone) starts from public guide inputs with recorded inference; hosted operation and live human review remain. |
 | [WS-ART-001](initiatives/WS-ART-001/OVERVIEW.md) | Planned | Verified input/output custody, exact-cause replacement and public admission-backed ZIP/Submission entry are delivered. The bounded local public/worker drill passed; hosted operation and setup-fault handling remain separate. |
 | [WS-AUTH-001](initiatives/WS-AUTH-001/OVERVIEW.md) | Planned | Exact fixed-router custody, checker remediation and checker retry are delivered. The ART Operator backend prerequisite adds exact system-Operator artifact reads and independently guarded verification retry; WS-CLI-001-43 consumes all nine public ART operations, while hosted S3 proof remains separate. Public entry and supported false-guide activation use current exact AUTH/SQL custody; human decision authority remains later work. |

.commitrail/initiatives/WS-CLI-001/OVERVIEW.md

@@ -60,8 +60,10 @@ It does not claim a tag, published binary or signed/notarized artifact.
 
 [WS-CLI-001-48](WS-CLI-001-48.md) adds the opt-in read-only contributor
 workbench: exact-grant projects, one-page Ready/active Mine/own Submissions,
-fresh details and explicit Mine context/intake reads. Detailed findings and
-contribution evidence remain inert CLI handoffs. All mutations, management
+fresh details and explicit Mine context/intake reads.
+[WS-CLI-001-49](WS-CLI-001-49.md) adds exact-Submission findings pages and
+ordered locked-guide selection with explicit verified single-document download.
+Contribution evidence remains an inert CLI handoff. Product mutations, management
 screens and operation-specific recovery remain separate TUI boundaries; this
 interface does not depend on first binary publication or system-wide discovery.
 
@@ -73,7 +75,7 @@ and separate guide-bound review/revision policy configuration. The commands
 the existing public writes with caller-owned replay keys and policy `If-Match`.
 The backend owns manager authorization for new writes, policy semantics, replay and activation;
 editing/configuring a guide does not approve or activate it. Other public API
-client gaps and the broader TUI beyond -48 remain separate work. Binary distribution's
+client gaps and the broader TUI beyond -49 remain separate work. Binary distribution's
 workflow is prepared by -44; a protected release run and public-asset audit
 remain operational work.
 
@@ -324,13 +326,14 @@ that human's credential, not a registered agent identity.
 Make every operation complete without a terminal: stable JSON output, safe
 errors, exit status, and no required prompts. Add optional terminal assistance
 only where it improves an actual workflow. The opt-in `workstream tui` browses
-the bounded contributor reads in -48 using the same client operations and never
+the bounded contributor reads in -48/-49 using the same client operations, including
+confirmed verified guide downloads and paged checker findings, and never
 becomes a second state machine. Further screens require stable public contracts
 and their own proof. Prefer
 purposeful commands over generating a flag mirror of every OpenAPI route.
 
 Go is the chosen implementation language. Cobra owns command parsing/help and
-completion. The bounded -48 workbench uses Bubble Tea, Bubbles and Lip Gloss;
+completion. The bounded -48/-49 workbench uses Bubble Tea, Bubbles and Lip Gloss;
 noninteractive commands retain their existing behavior. Do not add Python, TypeScript, or Rust duplicate
 CLIs. Keep the package independent of backend and MCP runtime dependencies.
 
@@ -422,8 +425,9 @@ CLIs. Keep the package independent of backend and MCP runtime dependencies.
    journey through contribution export, with negative intake and authority checks.
    Hosted and human-review journey proof remain separate.
    Unfinished human review/revision is not current CLI implementation scope.
-26. **Optional TUI:** -48 supplies read-only contributor navigation through
-   existing typed reads. In-TUI findings/Evidence, writes and management remain
+26. **Optional TUI:** -48 supplies contributor navigation through existing typed
+   reads; -49 adds findings pages and confirmed verified guide downloads.
+   In-TUI Evidence, product writes and management remain
    separate boundaries; Evidence first needs a shared typed single-page client
    port without changing complete CLI exports. Never require a TUI for agents
    or scripts.

.commitrail/initiatives/WS-CLI-001/WS-CLI-001-49.md

@@ -0,0 +1,148 @@
+# WS-CLI-001-49 — Contributor guide and findings in the terminal
+
+- Initiative: `WS-CLI-001`
+- Durable disposition: `Planned`
+- Intended merge outcome: Replace guide/findings handoffs with bounded interactive reads and explicit verified guide downloads.
+
+## Intent
+
+Issue #688 tracks the remaining terminal experience. Main's read-only workspace
+opens exact task/context/intake and Submission details but sends users back to
+explicit commands for detailed findings and guide originals. The public APIs
+and their validation already exist. This slice removes those handoffs without
+adding product mutations or changing backend authority.
+
+## Bounded change
+
+Extend existing TUI navigation, request generations, cancellation and safe text
+rendering. WorkContext supplies assignment-sensitive ordered guide metadata;
+DownloadGuideDocument verifies exact same-origin content, SHA-256 and byte count.
+Use an explicit destination entry and confirmation before downloading. Extract
+the existing CLI private-file/no-overwrite publication operation into a shared
+owner if needed; both callers must use it, not duplicate filesystem policy.
+Keep binary documents out of terminal rendering; no system viewer launch or
+shell execution. Metadata must never be labelled verified bytes.
+
+Expose typed paged findings through the existing validated SubmissionFindings
+operation, updating affected explicit callers rather than adding a second
+transport/decoder. Display exact run identity/current-versus-historical state,
+checker/check ID, status, severity, path/line, message and suggested fix.
+Continuation is explicit and bound to selected Submission/task; never infer
+acceptance from checker success. Navigation/refresh invalidate stale responses;
+denial clears affected observations. Every displayed untrusted value uses the
+existing terminal sanitizer and bearer suppression.
+
+Allowed paths: cli/internal/tui/, affected api/submission_reads.go and its
+callers/tests, existing guide download command and a narrowly shared download
+owner, cli/tests/integration/test_tui_http.py and focused guide/findings process
+tests, cli/README.md, docs/design/cli-terminal-experience.md,
+docs/roadmap_status.md and affected WS-CLI-001 records/index when their next
+boundary changes. The shared owner may use platform-specific permission files
+and tests; cli/go.mod may promote the already-pinned x/sys dependency from
+indirect to direct for Windows file-handle ACL operations. No new dependency or
+version, backend, workflow or release changes.
+
+## Boundaries and alternatives
+
+Do not add claim/start/prepare/submit, polling, credential storage, local replay
+journals, PDF rendering, automatic viewer launch, task examples, directory
+creation, overwrite, or download-all implicit chains. Existing explicit commands
+remain available. A separate raw-HTTP TUI client or duplicate download helper
+was rejected because it would fork validation and custody rules.
+
+## Risk and review routing
+
+L1: untrusted terminal data and local filesystem publication. Plan review before
+implementation; focused security, QA and reuse/architecture review of affected
+owners; documentation review for capability claims. Human merge remains required.
+No new authority decision is needed; if a backing contract is missing, report
+the gap rather than invent it.
+
+## Acceptance criteria
+
+- Assigned task guide screen preserves exact server ordering, identities and
+  hashes; no documents for an unassigned task or task-example disclosure.
+- Explicit download writes private temporary content; checksum/size failure or
+  missing bytes publishes no final file. Existing files/symlinks are not replaced.
+  Cancellation/navigation cannot silently publish an unobserved success.
+- Findings load only for the selected Submission and task, preserve all returned
+  statuses and historical/current run distinctions, and follow explicit cursors.
+- Denial, malformed/misbinding responses, token/control-character content,
+  late responses and quit remain safe. Narrow/plain terminals stay usable.
+- Focused Go tests and real socket/PTY process tests exercise new screens and
+  failure boundaries. Existing native suite runs unchanged on all four platforms;
+  no skipped assertions or CI weakening. Retain existing public PostgreSQL
+  guide/findings authorization proof; a TUI test does not certify hosted service.
+- Update affected capability ledger/README/design claims together; run markdown
+  links, stale wording, Go tests/vet and review before merge readiness.
+
+## Human review focus
+
+Confirm destination/confirmation usability, exact locked identity visibility,
+no-overwrite and integrity failure behavior, and honest checker outcome labels.
+
+## Evidence
+
+Plan review required explicit staged publication, typed findings with preserved
+Raw output, and reachable keyboard transitions; the concrete contract below
+incorporates those corrections. Runtime proof is the focused Go owner tests and
+built-process native terminal tests, plus existing explicit guide/source and
+submission regressions. Hosted native and public-API checks remain required
+before merge readiness; current results belong in the PR trust bundle.
+
+This cohesive slice exceeds the preferred 500-line L1 guideline: new staging
+and cancellation tests, native interaction regressions, and removal of both
+existing publication implementations account for much of the change. Splitting
+the helper from its consumers would leave duplicated custody rules; the two
+read surfaces share the bounded navigation extension. No backend, CI, new dependency
+or product-policy boundary changes are included. Focused reviewers inspect filesystem
+security, state/navigation correctness and owner reuse separately.
+
+## Concrete state and owner contract
+
+Mine detail keeps Overview, Context and Intake in their existing order, then
+adds Guide. Guide freshly reads WorkContext; arrows select one ordered document.
+`d` edits an existing-directory destination, Enter opens confirmation showing
+task/document identity, directory and computed UUID filename, and `y` starts
+staging. Esc cancels editing/confirmation without I/O. No directory is created.
+Submission detail Tab alternates Overview and Findings. Findings fetches 50
+runs; `n` replaces that page using its exact cursor, `r` restarts at page one.
+Back, refresh, project changes, denial and quit invalidate pending work.
+
+The narrow shared owner is `cli/internal/download/`. Move the bound-root and
+private-publication behavior from `command/guide_reads.go` there and update
+all consumers: `command/task_guide.go`, `command/guide_reads.go` and
+`command/task_batch_source.go`. CLI consumers stage then publish synchronously;
+do not preserve duplicate implementations. TUI registers an abortable stage
+before dispatch. Async work can only write/verify/sync/close temporary bytes.
+Only the current-generation receive may synchronously publish the no-overwrite
+hard link and set the visible success state, before another key is processed.
+Abort/Publish are idempotent and race-serialized. Invalidation/Close marks an
+in-flight stage aborted; cleanup does not require delivery of its response,
+including on Windows where a writer may still hold an open file.
+
+Windows mode bits do not enforce private access. Create the stage atomically
+with a protected current-user-only DACL relative to the already-bound directory
+handle, with exclusive-create/non-directory semantics; failure returns no stage.
+Do not tighten inherited permissions after creation: a foreign reader could
+retain a handle acquired before tightening. POSIX uses mode 0600.
+Native tests inspect the actual platform permission boundary and exercise
+symlink refusal without skipped assertions. This replaces the incorrect
+cross-platform assumption that 0600 alone provides private staging.
+
+SubmissionFindings returns a typed one-of result containing Raw plus Page or
+Run (only the mode-appropriate member populated), using its existing decoder.
+CLI JSON and text continue rendering Raw unchanged; TUI consumes Page. Receive
+checks every run's task and Submission against selected row/detail, as well as
+request cursor, generation and selector. Preserve nullable fields, predecessor
+and current-run flag. No alternative decoder or transport is introduced.
+
+Named proof additions: Go typed page/exact-run and unchanged raw-output tests;
+TUI selection/confirmation/current-receipt tests; download stage tests for
+bound/symlink directories, existing file/symlink, native private temporary content,
+checksum/size/missing/transport failure, and delayed writer Abort cleanup.
+Extend test_tui_http.py and its tui_terminal_support.py binary-response fixture
+to exercise actual PTY navigation, explicit confirmation, download success,
+cancel/quit before delayed completion, findings pagination/misbinding, every
+finding status and hostile text. These tests remain in the native four-platform
+suite. Retain prior input, denial and terminal lifecycle assertions.

cli/README.md

@@ -26,8 +26,8 @@ non-terminal input/output and JSON mode before making an API request.
 
 Start with your exact-grant projects, then browse **Ready**, **Mine** (active
 assignments) and **Submissions**. Enter opens fresh contributor-safe task or
-owned Submission detail. Active Mine details also offer explicit Context and
-Intake reads. Each list fetches one page; filtering searches only that loaded
+owned Submission detail. Active Mine details offer Context, Intake and Guide
+sections. Submission detail also offers paged Findings. Each list fetches one page; filtering searches only that loaded
 page. Project membership, terms and action hints are observations, not authority
 for a later operation. Workstream rechecks each public read.
 
@@ -39,15 +39,21 @@ for a later operation. Workstream rechecks each public read.
 | `n` / `r` | Fetch the next page / refresh the current view |
 | `/` | Filter loaded names/titles locally; Enter finishes and Esc cancels |
 | `c` / `?` | Show inert CLI arguments / keyboard help |
-| `q` / Ctrl+C | Quit and cancel outstanding client reads |
-
-This first workspace is read-only: it does not claim/start work, prepare or
-submit ZIPs, download documents, export records, poll, acquire tokens or save
-local history. Guide metadata is not proof of downloaded-byte integrity.
-Detailed findings and contribution evidence are clearly labelled manual CLI
-handoffs, not populated TUI screens; displayed arguments never execute or copy
-automatically. Use `submission findings SUBMISSION_ID` and
-`contributions --project PROJECT_ID` explicitly when needed.
+| `d` in Guide | Enter an existing download directory; Enter reviews the target, `y` confirms |
+| `q` / Ctrl+C | Quit and cancel outstanding client reads; `q` is text during text entry, Ctrl+C always quits |
+
+The workspace makes no product mutation requests: it does not claim/start work,
+prepare or submit ZIPs, export records, poll, acquire tokens or save local
+history. Guide metadata is not proof of downloaded-byte integrity. In Guide,
+select one document, enter an existing real directory and confirm the exact
+target. Verified bytes are published under the document's UUID filename without
+overwriting an existing file. Cancelled or failed downloads are not published.
+PDF/Office documents are downloaded, not rendered or opened automatically.
+Findings display each returned run's identity, current flag and checker evidence;
+they do not imply acceptance. `n` fetches one next findings page.
+Contribution evidence remains a manual CLI handoff: use
+`contributions --project PROJECT_ID`. Displayed arguments never execute or copy
+automatically.
 
 A denial clears affected content; expired authentication clears the session's
 work data. Network failure is shown as unavailable, never as an empty queue or

cli/go.mod

@@ -8,6 +8,7 @@ require (
 	charm.land/lipgloss/v2 v2.0.6
 	github.com/charmbracelet/x/term v0.2.2
 	github.com/spf13/cobra v1.10.2
+	golang.org/x/sys v0.47.0
 )
 
 require (
@@ -26,5 +27,4 @@ require (
 	github.com/spf13/pflag v1.0.9 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	golang.org/x/sync v0.22.0 // indirect
-	golang.org/x/sys v0.47.0 // indirect
 )