kandev/docs/plans/default-changes-focus-guard/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-08-31	done	REQ-UI-TASK-LAYOUT-PROFILES-001	../../specs/ui/system-design/task-layout-profiles.md

Implementation Plan: Restrict Changes Auto-focus

Overview

Restrict automatic Changes activation to the Default layout's Files and Changes group. The implementation and its regression tests form one sequential work order.

Scope

In scope

• Apply one shared eligibility rule to active-task and returning-task updates.
• Track the active built-in or custom profile identity across preset application, restores, task switches, and reloads.
• Require the stable Default top-right group.
• Require exactly the Files and Changes tabs in that group.
• Preserve the current tab in VS Code, Plan, Preview, compact, and custom group compositions.

Out of scope

• Change Git-status detection, fingerprinting, or inactive-task pending state.
• Change backend layout-profile persistence or panel placement.
• Change mobile or tablet task layouts.

Technical approach

Changes activation guard

Update activateChangesPanel in apps/web/components/task/changes-panel-focus.ts. Require the active profile to be the built-in Default, use RIGHT_TOP_GROUP as the layout identity, and permit activation only when the live group contains exactly files and changes. Persist the active profile identity with each environment-scoped Dockview layout so copied custom profiles remain ineligible after restores and task switches. Carry the effective default's identity alongside its layout when seeding the store, so a reserved customized Default remains built-in Default during fresh builds and Reset Layout while arbitrary custom defaults remain custom.

Keep both activation callers on this shared helper. ChangesTab uses it for active-task count increases. useChangesPanelAutoFocus uses it after inactive-task updates.

Keep an ineligible pending update available for a later eligible layout. Do not change the pending-state cleanup rules.

Regression coverage

Add direct unit coverage for the activation guard in apps/web/components/task/changes-panel-focus.test.ts.

Replace the E2E expectation that activates Changes in any non-Agent group. The new scenario selects the VS Code preset, leaves VS Code active, and creates another Git update. The test proves that the vscode | files | changes group does not lose focus.

Add store and profile-identity coverage for a reserved customized Default used as the effective default during fresh build and Reset Layout, plus the existing env-profile read/write paths.

Tests

• AC-UI-TASK-LAYOUT-PROFILES-001.11: Unit cases cover the eligible Default group, a non-Default group, and a Default group with an extra VS Code tab.
• AC-UI-TASK-LAYOUT-PROFILES-001.11: Unit and store-integration cases cover a copied Default custom profile, built-in override identity, and per-environment profile persistence.
• AC-UI-TASK-LAYOUT-PROFILES-001.11: Existing state tests preserve reload baselining and inactive-task attention.
• AC-UI-TASK-LAYOUT-PROFILES-001.11: A reserved customized Default keeps built-in identity through a fresh build and Reset Layout; arbitrary saved profile IDs remain custom.

E2E tests

• AC-UI-TASK-LAYOUT-PROFILES-001.11: Update apps/web/e2e/tests/layout/changes-panel-focus.spec.ts with the reported VS Code group scenario.
• Existing Default-layout scenarios continue to prove eligible activation for active and returning tasks.
• No mobile E2E case is required. Mobile and tablet task layouts do not mount DockviewDesktopLayout or this focus hook.

Work orders

• Task 01: Restrict Changes auto-focus (done)

Verification results

• pnpm exec vitest run components/task/changes-panel-focus.test.ts: passed, 20 tests before the fixup and 20 tests after the fixup.
• pnpm exec vitest run lib/local-storage.test.ts lib/state/dockview-store.test.ts lib/state/dockview-preset-persistence.test.ts components/task/changes-panel-focus.test.ts: passed, 92 tests.
• pnpm run typecheck: passed.
• pnpm test: passed, 1,677 test files and 14,381 tests (4 skipped).
• pnpm run lint: passed.
• pnpm e2e:run tests/layout/changes-panel-focus.spec.ts -- --grep "VS Code group": passed.
• The complete changes-panel-focus.spec.ts suite passed, 6 tests, with the desktop PR capture enabled.
• python3 ../../scripts/lint-spec-files.test.py: passed, 20 tests.
• python3 scripts/lint-spec-files.py --all: passed when run from the repository root.
• git diff --check: passed.

Risks

• A loose panel-membership check can allow another editor tab to lose focus.
• A guard that uses the current fallback group can misidentify a non-Default layout as the Default layout.
• Removing pending state for an ineligible layout can lose later attention after a switch to the Default layout.