kandev/docs/plans/threads-home-default/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-09-10	done	REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-001 REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-002 REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-003	../../specs/ui/system-design/task-listing-display-preferences.md

Implementation Plan: Threads Home Default

Overview

Add Threads to the existing portable Startup Page choice, honor it on bare startup and Home navigation, and keep device-local listing memory independent. Implement the settings contract first, then routing, then the localized choice and desktop/mobile browser proof. All work orders are sequential.

This task's workspace is /home/zeval/.kandev/tasks/choose-threads-as-de_94whggoq/kandev-2. The initial worktree was clean. No reviewed package for a fixed Threads Home default was present; the prior task-listing plan is completed historical work. This package was handed off before implementation, which the user authorized with the subsequent "go for impl" request.

Sources and reconciliation

• Owning requirements retain REQ-UI-TASK-LISTING-DISPLAY-PREFERENCES-001, extract the already shipped startup behavior into 002, and define the extension in 003. UI owns the reusable presentation preference, not task or workspace state.
• System design moves technical material out of the old requirement's migrated prose and defines precedence without duplicating the Threads deck contract.
• view-preference.ts and its tests already accept Threads. The requirement and public task-listing documentation still listed only three modes; that mismatch is reconciled in this package, not treated as missing deck support.
• At reconciliation, StartupPage, NormalizeStartupPage, applyStartupPage, the settings radio card, and frontend parsing accepted only overview/last task.
• At reconciliation, workspaceHomeHref and homeDestinationHref duplicated Home policy; nav-home additionally used a workspace-less overview override.
• ADR 0041, ADR 0023, and Office mode retain settings and workspace authority. No new ADR is needed: this is a bounded extension whose rationale is preserved in the owning design.

Scope

In scope

• Portable startup_page: "threads", preserving the existing default and patch/revision semantics across storage, HTTP, WS, and boot hydration.
• Fixed Threads Home overriding remembered mode only for generic Home and bare startup. An explicit route remains explicit.
• Desktop/sidebar, phone/menu, settings-exit, workspace-picker, and Home-command wiring through the shared destination policy.
• Startup settings copy, discovery aliases, all locales, and browser evidence.
• Public task-listing documentation when implementation ships.

Out of scope

• Parent dirty worktree, its demo data, swipe-indicator timing, and mobile topbar normalization. A phone Home href change is wiring only.
• New Kandev tasks/sessions, agent launch, subagent delegation, commit, push, PR, or a new worktree as an execution mechanism.
• New per-device or per-workspace Home stores, schema migrations, feature flags, or fixed defaults for every other listing mode.
• Changing task Back/Task overview links, task lifecycle, Threads saved-view selection, deck filtering, or resource budgets.

Technical approach

1. Portable startup choice

Extend internal/user/models and internal/user/service to retain/validate threads. Verify the existing DTO, JSON settings store, revision-guarded service, event, and mapUserSettingsState boot paths. Extend frontend StartupPage and the common settings mapper; the same field already flows through Appearance draft/save and the settings store. Do not add a column or new default field. See Task 01.

2. Home intent and entry routing

Centralize Home href policy in lib/navigation/workspace-home.ts; adapt the manifest and direct callers. Carry the saved startup choice through NavContext/useNavContext. Home in a non-Office workspace resolves directly to Threads when selected. Preserve existing overview links for existing choices; nav-home's old overview override is bypassed only for the new choice.

Bare root resolution belongs to startup-page.ts and PageClient, using existing explicit-destination guards and one redirect per resolution. Expose workspace-scoped bootstrap readiness in useKanbanRouteBootstrap so settings and workspace data settle before the default applies. Fix the local listing hook's synthetic loaded: true write to preserve real readiness. Empty/error bootstrap paths must settle without requiring board snapshots or workflows. See Task 02.

3. Selectable settings and integrated proof

Add the third radio to StartupPageSettingsCard; reuse the existing Appearance contributor and shared Save/discard/error flow. Revise descriptions and search aliases in all locales to distinguish last-used overview, startup-only last task, and fixed Threads Home. Existing native settings rows and Threads deck provide mobile composition. See Task 03.

Update the how-to section Find and organize tasks in docs/public/tasks-and-workflows.md with supported device modes, the three startup choices, and Home versus explicit-route behavior. Publication belongs to implementation, not the preceding design-only turn.

Tests

The following additions and extensions implement the acceptance coverage. Each work order records its RED/GREEN results.

Acceptance criteria	Evidence
001.3 to 001.6, 001.12	view-preference.test.ts and use-task-listing-view.test.tsx: Threads, invalid/missing/legacy values, blocked writes, phone Pipeline fallback, startup choice unchanged by view changes
002.1, 002.5, 003.3	Backend TestApplyStartupPage, TestScanUserSettingsStartupPage, DTO/event/boot startup tests; new repository startup persistence tests for SQLite/PostgreSQL and separate users; frontend mapper/WS startup cases
002.2 to 002.4	startup-page.test.ts, page-client.test.tsx: workspace-local recent task, no matching task, explicit overview/task/workflow guards, no recent-task resume for Threads
003.4, 003.6	New lib/navigation/workspace-home.test.ts Home matrix; existing navigation resolver, sidebar workspace-navigation, Home affordance, and app-destinations hook tests
003.4, 003.5, 003.7	page-client.test.tsx, new src/kanban-route-startup.test.tsx, and view-navigation.test.ts: competing remembered value, deferred bootstrap, stale workspace completion, explicit routes, empty workspace/deck, failed bootstrap recovery
003.1, 003.2	New appearance-settings-state.test.ts startup draft/patch/rebase cases; existing general-settings/save-provider regressions and browser radio/save/discard/error flow
003.8	Phone E2E: labelled radio row at least 44px high, tap Save, Home to native deck, explicit route reload, no horizontal overflow

The unchanged workflow-filter and rich-row criteria (001.1, 001.2, 001.7 to 001.11) retain the completed prior plan's evidence. Existing task-listing desktop/mobile specs run as regression neighbours because this change touches their shared view navigation.

E2E tests

Use isolated worker fixtures only. Capture settings before patches and restore them in afterEach, acquiring testPage before changing persistent defaults. Use causal save-response waits and final UI assertions; no fixed sleeps or larger locator timeouts. Rebuild through the managed runner. Confirm each project discovers its intended tests; desktop and mobile run separately.

Extend e2e/tests/settings/startup-page.spec.ts (chromium):

• saves Threads as the Home default independently of the last listing: choose and save Threads, reload Settings, use List, assert /tasks survives reload, then use Home and reload bare root to reach Threads in the same workspace. Clearing only the listing key cannot disable fixed Threads. Covers 003.1 to 003.5 and 003.7.
• keeps Threads draft changes pending until saved: discard the selection; then fail one settings save, retain the prior backend choice and retryable draft, and retry successfully. Covers 003.2.
• keeps every Home entry in the selected workspace: brand/Home row, settings exit, Home command, and workspace picker target the selected workspace. Include two non-Office workspaces with distinct task titles, then test the empty Threads state. Covers 003.4, 003.6, 003.7.
• preserves explicit destinations with a Threads Home default: select Kanban/Pipeline/List, reload, use a workflow URL and explicit task/session route, and follow a focused Threads URL. Verify path, workspace, and focus remain intact; browser Back/Forward does not force Home. Covers 003.5.
• Retain both existing last-task tests for 002.1 to 002.4. Add a real second browser context or fresh browser session using the same user backend with no listing key to prove 003.3; do not run the test fixture's settings reset in that second context.

Extend e2e/tests/settings/mobile-startup-page.spec.ts (mobile-chrome):

• saves Threads from phone settings and returns Home after using List: enter Settings through phone navigation, tap the labelled Threads row, Save, reload, switch to List through the drawer, and tap the mobile menu Home row. Verify workspace, native deck, and a subsequent reload. Covers 003.1 to 003.4, 003.6, 003.8.
• keeps explicit phone destinations with Threads selected: List reload, task/Task overview links, and focused Threads link remain explicit; missing local memory still permits Threads on Home. Assert row hit area, Save visibility, safe-area clearance, and no horizontal overflow. Covers 003.5, 003.7, 003.8; retain the existing last-task scenario.

Extend the Home-focused cases in e2e/tests/office/sidebar-navigation.spec.ts and mobile-office-navigation.spec.ts using startup_page: "threads" to prove Office Home still works from shared Settings surfaces (003.6). These are normal chromium and mobile-chrome navigation tests, not the provider routing project. Do not exercise provider-routing scenarios for this change.

Work orders

• Task 01: Persist the Threads startup choice (wave 1, done)
• Task 02: Resolve Threads Home navigation (wave 2, depends on 01, done)
• Task 03: Expose the Threads Home choice (wave 3, depends on 02, done)

Verification results

PR fixup scope also includes preserving disabled-Office phone Home routing, repairing the workspace-picker test fixture, direct fallback resolver coverage, and aligning specification index labels and backend verification build tags. Task 02 records the remediation sequence and completed local validation. The later full frontend CI run exposed three more incomplete navigation test fixtures. Their test-only repair and expanded desktop/phone Home assertions are also recorded in Task 02; no additional product contract change is needed. The current-main merge retained both UI design index entries and passed the 122-test navigation suite, full web lint/typecheck/i18n, tagged startup/boot tests, and 21 focused desktop/phone browser scenarios. Broad frontend and current-head remote CI/review results are tracked in the PR delivery evidence. Later E2E CI exposed a startup-readiness regression when switching to All Workflows. Task 02 owns recording the hydrated fast-path completion, regression coverage for live filters and route changes, and focused browser verification. The existing listing-availability contract is clarified before this repair. The landed parent polish moved phone Home into the shared menu. Preserve its header and swipe implementation unchanged, retain the Threads choice through the shared navigation context, and update this package's phone entry-point tests and current design. The mobile parked-session flake is a separate test-profile cleanup defect, with no product contract change. After this integration, 109 focused frontend tests and 73 desktop/phone E2E tests passed, including every failed CI filter case and the profile cleanup regression. Full web lint/typecheck/i18n and specification/harness/public-docs validators passed. Tasks 02 and 03 record exact commands; current-head remote CI and review remain pending until the remediation push is verified.

• python3 scripts/lint-spec-files.test.py: passed, 30 tests.
• python3 scripts/lint-spec-files.py --all: passed for all specification files.
• git diff --check -- docs/specs docs/plans: passed.
• Task 01: startup enum/persistence, boot mapping, SQL guard, and SQLite and PostgreSQL fresh/replay/upgrade conformance passed. Frontend mapping and WS: 87 tests passed.
• Task 02: 148 routing/navigation tests passed, including delayed and cancelled bootstrap, Office, empty/error fallback, and explicit destinations.
• Implementation-checkpoint frontend run: 272 tests passed across 21 files, including blocked/malformed local storage and settings draft/rebase/save regressions.
• Task 03: 19 browser tests passed with strict WS checks and no retries: desktop startup/listing 8, phone startup/listing 5, desktop Office Home 3, and phone Office navigation 3. Native phone screenshots were inspected; temporary artifact paths are recorded in Task 03.
• Typecheck, focused ESLint, all locale checks, and the production build passed.
• Public docs validation passed for 46 pages and its validator test passed.
• PR review remediation: the E2E settings response now declares the optional workspace and workflow IDs used by cleanup. A targeted compiler check reproduced both unknown-to-string errors before the fix and passed afterward; two API-helper tests and focused ESLint passed. The helper change is test-only.
• PR routing remediation: 88 focused frontend tests and seven phone E2E tests passed against a rebuilt web bundle, with retries disabled. The new disabled-Office regression failed on the old href before the fix. Typecheck, focused ESLint, specification and public-docs validation passed. Backend startup, boot mapping, and SQLite conformance passed with -tags fts5 -race; PostgreSQL was not rerun for this frontend/documentation-only remediation.
• Requirements are active, system design is current, and all three work orders are done. The task-owned disposable PostgreSQL fixture was removed after successful persistence and upgrade checks.

Each work order records its exact implementation commands and results; execution was authorized by the user's subsequent "go for impl" request. Public documentation changes were completed in Task 03. At the implementation checkpoint, no commit, push, PR, agent delegation, or parent-worktree edit had been performed. The user subsequently authorized PR publication and fixup.

Risks

• A single forgotten Home consumer or the palette override would make the preference appear inconsistent. Integration coverage must click those actual entry points, not only test the resolver.
• home=overview already means remembered overview and suppresses recent-task resume. Treating it as generic Home would break explicit view selection.
• Deferred settings hydration could navigate to remembered List before the portable Threads choice arrives. Empty workspaces must not deadlock the readiness gate, and Office must resolve before task-listing defaults.
• This is a per-user choice applied to the current workspace, not a new per-workspace default. Settings copy must make the distinction from local recent-task and listing memory clear.
• Old binaries normalize unknown startup values to overview; normal release upgrade preserves existing values, but downgrades do not understand Threads.
• PostgreSQL coverage requires a disposable test database via KANDEV_TEST_POSTGRES_DSN; record a skip as missing evidence, not success.