> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase21-session04-shortcut-and-overlay-layering/tasks.md).

# Task Checklist

**Session ID**: `phase21-session04-shortcut-and-overlay-layering` **Total Tasks**: 21 **Estimated Duration**: 3-4 hours **Created**: 2026-06-29

***

Legend: `[x]` completed; `[ ]` pending; `[P]` parallelizable; `[SNNMM]` session ref; `TNNN` task ID.

***

## Progress Summary

| Metric              | Value     |
| ------------------- | --------- |
| Tasks Completed     | 21 / 21   |
| Estimated Remaining | 0 minutes |
| Blockers            | 0         |

***

## Setup (3 tasks)

* [x] T001 \[S2104] Verify Session 03 completion evidence and current Session 04 stub scope (`.spec_system/PRD/phase_21/session_04_shortcut_and_overlay_layering.md`)
* [x] T002 \[S2104] \[P] Audit current shortcut metadata, route mapping, and shortcut modal expectations (`apps/web/src/lib/commandCenterShortcuts.ts`, `apps/web/src/lib/useKeyboardShortcuts.ts`, `apps/web/tests/keyboardShortcuts.test.ts`)
* [x] T003 \[S2104] \[P] Audit current Escape, backdrop, and portal behavior for expanded Orchestration and nested drawers (`apps/web/src/components/BottomRailExpansionHost.tsx`, `apps/web/src/components/orchestration/OrchestrationShell.tsx`, `apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`)

***

## Foundation (5 tasks)

* [x] T004 \[S2104] Create shared overlay-layer constants and query helpers with deterministic ordering (`apps/web/src/lib/overlayLayers.ts`)
* [x] T005 \[S2104] Add bottom-rail overlay-layer semantics and higher-layer Escape guard with cleanup on scope exit for the host listener (`apps/web/src/components/BottomRailExpansionHost.tsx`)
* [x] T006 \[S2104] Mark the retained orchestration state summary portal as a higher overlay layer (`apps/web/src/components/orchestration/OrchestrationCurrentState.tsx`)
* [x] T007 \[S2104] Mark command-center record drawers as higher overlay layers with existing close behavior preserved (`apps/web/src/components/orchestration/OrchestrationDrawer.tsx`, `apps/web/src/components/orchestration/ExecutorRunHistoryDrawer.tsx`)
* [x] T008 \[S2104] Mark the terminal runtime drawer as a higher overlay layer with existing close behavior preserved (`apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx`)

***

## Implementation (8 tasks)

* [x] T009 \[S2104] Rename or replace the primary details shortcut action with a Command Center working-surface action (`apps/web/src/lib/commandCenterShortcuts.ts`)
* [x] T010 \[S2104] Repoint the `o d` command-center sequence to the primary Command Center open action (`apps/web/src/lib/commandCenterShortcuts.ts`)
* [x] T011 \[S2104] Update shortcut resolver labels, reasons, target kinds, and ARIA label generation for product-facing Command Center copy (`apps/web/src/lib/commandCenterShortcuts.ts`)
* [x] T012 \[S2104] Update global shortcut action union and dispatch cases for the renamed Command Center action (`apps/web/src/lib/useKeyboardShortcuts.ts`)
* [x] T013 \[S2104] Route the primary Command Center shortcut event to the existing focused surface opener with state reset or revalidation on re-entry (`apps/web/src/components/orchestration/OrchestrationShell.tsx`)
* [x] T014 \[S2104] Keep retained state-summary behavior secondary without a details-primary shortcut path (`apps/web/src/components/orchestration/OrchestrationHeader.tsx`, `apps/web/src/components/orchestration/OrchestrationShell.tsx`)
* [x] T015 \[S2104] Verify expanded Orchestration inner clicks, tab clicks, and form controls do not close the focused surface with platform-appropriate accessibility labels, focus management, and input support (`apps/web/src/components/BottomRailExpansionHost.tsx`, `apps/web/src/components/orchestration/OrchestrationShell.tsx`)
* [x] T016 \[S2104] Update keyboard shortcut modal copy only where shared metadata changes require component-level adjustment (`apps/web/src/components/KeyboardShortcutsModal.tsx`)

***

## Testing (5 tasks)

* [x] T017 \[S2104] Update pure Command Center shortcut tests for `o d`, action naming, resolver copy, uniqueness, and accessible labels (`apps/web/tests/commandCenterShortcuts.test.ts`)
* [x] T018 \[S2104] Update global route and hook integration tests for the primary Command Center shortcut event (`apps/web/tests/keyboardShortcuts.test.ts`)
* [x] T019 \[S2104] Update shortcut modal tests for Orchestration section copy, ARIA labels, and registered shortcut count (`apps/web/tests/KeyboardShortcutsModal.test.tsx`)
* [x] T020 \[S2104] Add host and Orchestration regressions for higher-layer Escape order, backdrop close, and inner-panel containment (`apps/web/tests/BottomRailExpansionHost.test.tsx`, `apps/web/tests/OrchestrationPanel.test.tsx`)
* [x] T021 \[S2104] Run focused automated checks and ASCII/LF validation (`npm test -- apps/web/tests/commandCenterShortcuts.test.ts apps/web/tests/keyboardShortcuts.test.ts apps/web/tests/KeyboardShortcutsModal.test.tsx apps/web/tests/BottomRailExpansionHost.test.tsx apps/web/tests/OrchestrationPanel.test.tsx`, `npm run typecheck --workspace @factionos/web`, `git diff --check`)

***

## Completion Checklist

* [x] All tasks marked `[x]`
* [x] All tests and checks passing
* [x] All files ASCII-encoded with LF line endings
* [x] implementation-notes.md updated
* [x] Ready for `creview` to continue the implement -> creview -> validate sequence

***

## Next Steps

Run the `creview` workflow step.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase21-session04-shortcut-and-overlay-layering/tasks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.