Carlos Florêncio
16 KiB
id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design
| id | title | status | wave | depends_on | plan | requirements | acceptance_criteria | system_design | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 06-concise-help-and-tabs | Concise Task behavior help and header tabs | complete | 6 |
|
plan.md |
|
|
|
Task 06: Concise Task behavior help and header tabs
Summary
Replace the long Task behavior page with Tasks, Conversation, and Runtime header tabs. Keep all sections expanded and use one short description plus an info button for each setting. This work order supersedes the collapsed-runtime direction from the original delivery.
In scope
- Reuse the Data & Logs tab composition and preserve settings links and cross-tab drafts.
- Add shared desktop-hover/keyboard and touch-drawer information presentation.
- Apply the copy inventory to every Task behavior setting, including compound runtime fields and profile choices.
- Remove repeated introductions, the collapsed runtime summary, and redundant inline technical paragraphs.
- Retain essential inline restrictions, current errors, and managed-value notices.
- Update all six real locales, pseudo generation, affected tests, and documentation.
Out of scope
- New pages, sidebar entries, or backend settings behavior.
- Changing switch polarity, profile fallback logic, limits, or permissions.
- A copy rewrite of unrelated settings pages. The shared info component remains reusable there.
- Third-party plugin content or a new global tooltip system.
Acceptance
- Tabs preserve values, Save/Reset, error recovery, and existing search fragments. Runtime needs no expansion action.
- Every Task behavior setting has one concise visible description and keyboard/touch-accessible optional information.
- Desktop and phone checks prove the new composition and existing persistence behavior without weakening prior regression assertions.
Visible-copy inventory
These are starting English strings, not new backend semantics. Keep existing stable keys when their meaning remains valid. Descriptions wrap naturally. Do not shrink fonts, truncate text, or enforce a one-line height. Retain unique details from current strings in info content. Remove repeated statements rather than duplicating them in multiple popups.
| Setting | Short description | Info content |
|---|---|---|
| Open new tasks automatically | Open a task after you create it. | Staying on the current view does not prevent task or agent start. |
| Agent-generated titles | Let the agent name new tasks from their prompt. | Required prompt, provisional name, rename fallback, manual edits, and save timing. |
| Profile for agent-created tasks | Choose the default profile for tasks created by agents. | Explicit/workflow precedence, effective creating-session values, parent fallback, scope, and cost implications. |
| Prevent auto-start on open | Keep agents stopped when reopening tasks after a restart or from the final workflow step. | Start agent remains available. Preserve the current switch meaning. |
| Archive confirmation | Review cleanup options before archiving a task. | Existing cleanup, subtask, and confirmation behavior. |
| Unread divider | Mark messages received while a task was out of view. | Read tracking continues when the visual divider is off. |
| Anchored prompt | Keep your last prompt visible while scrolling on desktop. | Trigger conditions and desktop-only scope. |
| Jump to last prompt | Show a button to return to your latest prompt. | Existing visibility threshold and navigation behavior. |
| Jump to start | Show a button to return to the start of the conversation. | Existing scroll threshold and destination. |
| Auto-scroll control | Show a button to pause or resume transcript auto-scroll. | Per-session behavior and what this preference changes. |
| Todo checklist | Show the agent's todo checklist in the task panel. | Desktop panel placement and manual panel additions. |
| Only show nonempty checklist | Hide the pinned checklist when it has no items. | Dependency on the checklist toggle and retained saved value. |
| Enable automatic-session limit | Queue automatic starts when the session limit is reached. | Instance scope and interaction with workflow WIP limits. |
| Maximum automatic sessions | Manual starts can exceed this limit. | Positive-integer constraint, effective source, and automatic-start behavior. |
| Maximum queued messages | Limit pending messages per session. Use 0 for unlimited. | Admission timing, existing queue preservation, retries, and override precedence. |
| Allow queued message merging | Combine related queued messages before the agent reads them. | Sender, adjacency, workflow/system exclusions, and entity-reference limit. |
| Automatic message merging | Merge compatible consecutive messages automatically. | Session override, compatibility checks, and new-admission-only behavior. |
| Keep host awake | Prevent the computer running Kandev from sleeping during tasks. | OS mechanism, release timing, remote host scope, and platform limitations. |
Profile option descriptions become “Reuse the creating session's profile” and “Use the workspace's default profile”. Keep the full precedence rules in the setting's info content, including cases where workflow profiles win. Avoid changing technical wording by inference. Compare retained information with the existing profile and runtime source contracts.
ASCII UI preview
UI-05 / UI-06 / UI-07: Concise settings
Task behavior [Tasks] [Conversation] [Runtime]
Group heading
+--------------------------------------------------+
| Setting label (i) [control]|
| One short description. |
+--------------------------------------------------+
Runtime: all limit, queue, and power sections expanded.
Phone: tabs below title; tap (i) opens a details drawer.
See the full previews. Tab labels, expanded groups, optional information, and preserved Save are required. The applicable criteria are listed in frontmatter.
Technical notes
Use SettingsPageHeader, SettingsTabs, SettingsTabsList, SettingsTabsPanel, and useSettingsTab.
Keep visited panels mounted. Use the existing target-to-tab mapping pattern from Data & Logs.
Keep both queue/session state owners single-mounted and preserve their contributor IDs.
Aggregate panel dirty/error status without creating duplicate save contributors.
Add SettingsInfo beside the label in SettingsRow, outside the associated label element.
Reuse Tooltip, Drawer, and useTouchDrawer. Use the sleep info control as a reference.
Keep control helpers associated through aria-describedby. Info has its own localized accessible name.
Use short noninteractive technical content on desktop and the same content in a scrollable phone drawer.
Remove runtime disclosure props and obsolete runtime-only attention/summary helpers after checking all callers. Keep general disclosure discovery support used by other settings surfaces. Update scoped self-documenting-settings guidance to distinguish short inline effects from optional implementation details. Current permission, validation, and managed-value notices remain inline.
Verification
Start from the repository root. Dependencies already exist in this worktree. Write focused tests before behavior changes. The two concise-help E2E files below are new outputs of this work order.
(cd apps/web && pnpm exec vitest run components/settings/settings-info.test.tsx components/settings/settings-group.test.tsx components/settings/settings-tabs.test.tsx components/settings/task-behavior-settings.test.tsx components/settings/task-behavior-tabs.test.ts components/settings/settings-save-provider.test.tsx components/settings/mcp-task-agent-profile-default-settings.test.tsx components/settings/sleep-inhibition-settings.test.tsx hooks/domains/settings/use-settings-tab.test.ts lib/settings-discovery/target.test.ts)
(cd apps/web && pnpm run typecheck)
(cd apps/web && pnpm run i18n:check)
(cd apps/web && pnpm run i18n:ratchet)
(cd apps/web && pnpm exec eslint components/settings hooks/domains/settings/use-settings-tab.ts lib/settings-discovery --max-warnings 0)
(cd apps/web && pnpm e2e:run e2e/tests/settings/task-behavior-concise-help.spec.ts e2e/tests/settings/settings-composition.spec.ts e2e/tests/settings/settings-manual-save.spec.ts e2e/tests/system/message-queue-settings.spec.ts e2e/tests/system/session-capacity-settings.spec.ts e2e/tests/settings/todo-list-panel.spec.ts e2e/tests/task/mcp-task-agent-profile-default.spec.ts e2e/tests/task/unread-divider-preference.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome e2e/tests/settings/mobile-task-behavior-concise-help.spec.ts e2e/tests/settings/mobile-settings-composition.spec.ts e2e/tests/system/mobile-message-queue-settings.spec.ts e2e/tests/system/mobile-session-capacity-settings.spec.ts e2e/tests/settings/mobile-general-settings.spec.ts e2e/tests/task/mobile-mcp-task-agent-profile-default.spec.ts e2e/tests/task/mobile-unread-divider-preference.spec.ts)
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
git diff --check
Also run every existing test whose selector or navigation path changes and record its exact command.
Use rg to inventory tests opening Task behavior before editing them, including task, workflow, and kanban suites.
Replace the old openTaskBehaviorRuntime helper's expansion action with selection of the visible Runtime tab.
Conversation-specific tests must select Conversation. Preserve their value and persistence assertions.
The managed E2E runner builds fresh artifacts. Do not overlap suites or bypass its resource limits.
Required scenarios:
- Tasks default, explicit Runtime query, unknown-query fallback, and every existing target-to-tab mapping.
- Repeated discovery into a previously visited hidden panel, with actual focus after activation.
- Edit across tabs, Save/Reset all contributors, preserve drafts on tab change, and reveal a failed inactive-tab save once.
- Inline load/permission/managed-value errors, without popup-only recovery instructions.
- Runtime controls visible immediately after tab selection. No collapsed settings sections.
- Hover and keyboard focus reveal desktop help. Touch opens the drawer; dismissal returns focus and preserves the draft.
- Real 44px hit targets, 767px/768px geometry, coarse-pointer tablet, long translations, and no horizontal document overflow.
- Concise visible text. MCP identifiers and fallback algorithms appear only in optional info.
- Current manual-save, capacity, queue, title, profile, and conversation assertions remain intact.
Files likely touched
apps/web/components/settings/task-behavior-settings.tsxand its testsapps/web/components/settings/settings-group.tsxand its testsapps/web/components/settings/settings-info.tsxand.test.tsx(new)- Existing creation, title, profile, opening, archive, unread, transcript, todo, and sleep settings components
apps/web/components/settings/system/message-queue-settings.tsxandsession-capacity-settings.tsxapps/web/lib/settings-discovery/catalog/preferences.tsapps/web/e2e/helpers/settings-composition.tsand all affected route consumers- New concise-help E2E files and existing composition/runtime tests
apps/web/src/locales/{en,pt-pt,zh-cn,zh-hk,zh-tw,ja,pseudo}/apps/web/AGENTS.md, affected Task behavior sections underdocs/public/, and this package
Dependencies
Tasks 01 through 05 are complete. Reuse their implementation and review fixes.
Risks
- Hidden visited panels can consume discovery focus too early.
- Tab changes can lose drafts if domain owners unmount.
- Shortening copy can erase scope or precedence facts. Preserve them in info and retain active restrictions inline.
- Hover-only help can exclude phones or keyboard users.
- Tests can continue asserting old disclosure behavior unless all route consumers are audited.
Parallelism
sequential
Inputs
- Requirements
- System design
- Header tabs contract
- Existing Data & Logs composition and sleep-prevention tooltip/drawer
/tdd,/mobile-parity,/e2e, andapps/web/AGENTS.md
Results
Implemented on 2026-09-22. Tasks, Conversation, and Runtime reuse the header tabs and retain visited drafts. Every Task behavior control has concise copy and optional desktop/touch information. Runtime sections stay expanded. The existing save coordinator exposes contributor status for tab badges and one-time error recovery. Discovery skips optional info buttons and focuses the setting after tab activation.
Validation:
- Focused Vitest suite: 10 files, 63 tests passed, including save-coordinator state, Reset recovery, and all nine discovery mappings.
- Desktop regression suite: 37 passed, including composition, manual save, cross-tab Save/Reset/failure, queue/capacity, todo, MCP profile, and unread preference.
- Mobile regression suite: 22 passed, including 390/767/768/900px touch geometry, long pseudo translations, drawer focus return, runtime permissions, profile, and unread preference.
- Typecheck, scoped ESLint, six-locale/pseudo checks, documentation catalog/spec lint, and harness checks passed.
- Final targeted browser reruns: 14 desktop and 7 mobile tests passed against fresh production artifacts, including the final profile markup and capacity description association.
RED tests reproduced missing info interaction, tab ownership, contributor status, stale failure after Reset, and discovery focusing the info button.
Browser regressions also caught outdated selectors and tooltip-copy assertions, which now use the intended tab/help flow without removing persistence or permission checks.
The Traditional Chinese generator ran with --namespace settings; its unrestricted run found a pre-existing residual Simplified Chinese string in workflows.openAgentSettings and refused to write that unrelated namespace.
Final browser reruns (from apps/web):
pnpm e2e:run e2e/tests/settings/task-behavior-concise-help.spec.ts e2e/tests/system/message-queue-settings.spec.ts e2e/tests/system/session-capacity-settings.spec.ts e2e/tests/task/mcp-task-agent-profile-default.spec.ts
pnpm e2e:run --no-build --project mobile-chrome e2e/tests/settings/mobile-task-behavior-concise-help.spec.ts e2e/tests/system/mobile-session-capacity-settings.spec.ts e2e/tests/task/mobile-mcp-task-agent-profile-default.spec.ts
The second command reused the immediately preceding fresh build. No source changed between these runs.
The final focused Vitest rerun passed all 63 tests after the last production edit.
Public docs are reference/how-to navigation updates; the obsolete all-in-one Task Behavior screenshot was removed from the operations guide.
Harness validation passed (19 harness tests, 36 specification-linter tests, full harness lint, and the targeted harness-lint hook).
The frontend guide shrank from 300 to 297 lines.