> 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-session07-final-regression-and-documentation/spec.md). # Session Specification **Session ID**: `phase21-session07-final-regression-and-documentation` **Phase**: 21 - Bottom Rail Focused Surface Expansion **Status**: Not Started **Created**: 2026-06-29 **Package**: apps/web **Package Stack**: TypeScript *** ## 1. Session Overview This session closes Phase 21 by rerunning the focused web regression gates for the bottom-rail focused surfaces, repairing any Phase 21 regressions found by those gates, and updating stable documentation so the Command Center entry path matches the shipped product. The prior six sessions already added transient expansion state, the shared bottom-rail host, Command Center expansion, shortcut layering, Quest Board and War Room parity, responsive sizing, accessibility checks, and browser evidence. Session 07 is next because the analyzer shows it is the only unfinished Phase 21 session, and Sessions 01 through 06 are complete. The closeout bar is user-visible proof. The final artifacts must show that a user can open, use, close, and recover the Quest Board, Orchestration, and War Room focused surfaces without state forks, inaccessible controls, stale docs, or unsupported hosted/execution claims. *** ## 2. Objectives 1. Re-run the Phase 21 focused shell, panel, shortcut, accessibility, browser, and web typecheck targets and record exact results. 2. Repair any focused-surface regression introduced by Phase 21 without adding new feature scope. 3. Update stable docs so Campaigns and Command Center workbenches are described as Orchestration bottom-rail and focused-surface workflows, not primary summary/details popups. 4. Produce final handoff evidence that preserves no-claim boundaries and identifies any remaining limitations or pre-existing failures. *** ## 3. Prerequisites ### Required Sessions * [x] `phase21-session01-expansion-state-foundation` - Provides transient focused bottom-rail surface state. * [x] `phase21-session02-shared-expansion-host` - Provides the shared host, stable test ids, focus behavior, and one-instance panel mounting. * [x] `phase21-session03-orchestration-command-center-expansion` - Routes the primary Orchestration path to the Command Center workbench. * [x] `phase21-session04-shortcut-and-overlay-layering` - Routes shortcuts and Escape ordering through the focused surface contract. * [x] `phase21-session05-quest-board-and-war-room-parity` - Applies the same focused-surface contract to Quest Board and War Room. * [x] `phase21-session06-responsive-layout-and-accessibility-pass` - Provides responsive sizing, accessibility, and browser evidence baselines. ### Required Tools Or Knowledge * npm workspace commands from `.spec_system/CONVENTIONS.md`. * Vitest, TypeScript package typecheck, and Playwright app projects. * Current Command Center documentation routing from `docs/README_docs.md`. ### Environment Requirements * Node and npm compatible with the workspace baseline in `package.json`. * Local Playwright browser dependencies available for `npm run test:e2e`. * No hosted credentials are required; hosted production validation is out of scope. *** ## 4. Scope ### In Scope (MVP) * Operators can rely on focused regression evidence for Quest Board, Orchestration, War Room, shortcuts, accessibility, and browser framing - record exact command results and classify any failures. * Operators can use the Command Center through the Orchestration surface and focused Command Center path - update docs that describe Campaigns, Queue, File/Git, terminal runtime controls, and other workbenches. * Maintainers can tell whether Phase 21 introduced regressions - repair only focused-surface regressions found during this session and document any pre-existing failures separately. * Maintainers can close the phase without overclaiming unsupported boundaries - preserve hosted production, formal certification, hosted identity, trusted erasure, remote execution, and broad executor no-claim language. ### Out Of Scope (Deferred) * New bottom-rail features - Reason: Phase 21 implementation sessions are complete; this session is final regression and docs closeout. * Backend execution semantics - Reason: Phase 20 owns truthful local execution claims, and Phase 21 is an `apps/web` presentation/accessibility phase. * Hosted production validation - Reason: the session stub explicitly excludes it and no safe credentials are required. * Formal legal/privacy approval or certification language - Reason: cumulative findings remain open until a future owner-backed review closes them. *** ## 5. Technical Approach ### Architecture Keep the existing Phase 21 architecture intact: one mounted implementation per bottom-rail panel, transient focused-surface state in `apps/web/src/store/useSettingsStore.ts`, shared dialog/focus/scroll behavior in `apps/web/src/components/BottomRailExpansionHost.tsx`, and Command Center workbench content inside the existing Orchestration panel. Repairs should be limited to the failing surface and should preserve same-instance promotion, overlay-layer ordering, accessibility labels, product-facing copy, and compact privacy-safe broad rows. Documentation updates should land in stable docs that already route Command Center usage: `docs/orchestration-quickstart.md`, `apps/web/README_web.md`, `docs/README_docs.md`, `docs/ARCHITECTURE.md`, and the root `README.md`. Session-local evidence should live beside this spec so `validate` and `updateprd` can cite it directly. ### Design Patterns * Evidence-first closeout: record commands, outputs, repairs, and limitations before declaring the phase ready. * Same-instance focused surface: compact and focused modes remain two presentations of one working panel implementation. * Product-facing docs: describe the operator path and no-claim boundaries without internal diagnostics or scaffold language. * Regression-only repair: fix failures exposed by the required targets without expanding feature scope. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase21-session07-final-regression-and-documentation/regression-evidence.md` | Focused test, typecheck, browser, docs grep, and repair evidence ledger | \~160 | | `.spec_system/specs/phase21-session07-final-regression-and-documentation/documentation-audit.md` | Stable docs audit for Command Center entry-path and no-claim language | \~90 | | `.spec_system/specs/phase21-session07-final-regression-and-documentation/browser-verification.md` | Final desktop/mobile focused-surface browser pass evidence | \~110 | | `.spec_system/specs/phase21-session07-final-regression-and-documentation/phase-handoff.md` | Final Phase 21 handoff summary, limitations, and updateprd inputs | \~120 | ### Files To Modify | File | Changes | Est. Lines | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------- | | `docs/orchestration-quickstart.md` | Clarify the Orchestration bottom-rail and focused Command Center entry path for Campaigns and other workbenches | \~25 | | `apps/web/README_web.md` | Add or refresh the bottom-rail compact/focused surface contract and secondary summary inspector wording | \~35 | | `docs/README_docs.md` | Update Command Center routing guidance with the Phase 21 focused-surface documentation source | \~12 | | `docs/ARCHITECTURE.md` | Reflect that the web cockpit exposes Command Center workbenches through compact and focused Orchestration surfaces | \~18 | | `README.md` | Add a concise product-surface note for focused bottom-rail access to Quest Board, Command Center, and War Room | \~8 | | `apps/web/src/components/BottomRailExpansionHost.tsx` | Regression repair target if focused shell, sizing, Escape, scroll, or focus behavior fails | \~0-60 | | `apps/web/src/App.tsx` | Regression repair target if compact/focused bottom-rail shell wiring fails | \~0-40 | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Regression repair target if Command Center focused state, nested overlays, or workbench preservation fails | \~0-60 | | `apps/web/src/components/QuestBoard.tsx` | Regression repair target if Quest Board focused state or actions regress | \~0-40 | | `apps/web/src/components/WarRoomPanel.tsx` | Regression repair target if War Room focused state or actions regress | \~0-40 | | `apps/web/tests/CockpitShell.test.tsx` | Regression test updates only when source-backed behavior changes during repair | \~0-80 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Regression test updates only when source-backed behavior changes during repair | \~0-80 | | `apps/web/tests/QuestBoard.test.tsx` | Regression test updates only when source-backed behavior changes during repair | \~0-50 | | `apps/web/tests/WarRoomPanel.test.tsx` | Regression test updates only when source-backed behavior changes during repair | \~0-50 | | `tests/e2e/app.e2e.ts` | Browser evidence updates only if final focused-surface checks need a selector or assertion repair | \~0-80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Focused shell and mobile accessibility targets pass or failures are documented as pre-existing with proof. * [ ] Orchestration, Quest Board, and War Room panel parity targets pass or Phase 21 regressions are repaired. * [ ] Primary Orchestration docs point to the focused Command Center workbench, including Campaigns, Queue, File/Git, terminal runtime controls, and other Command Center tabs. * [ ] Retained summary/state popups are documented only as secondary inspectors or not documented at all. * [ ] Final handoff records any remaining no-claim limitations without changing unsupported hosted, certification, identity, erasure, or remote execution posture. ### Testing Requirements * [ ] Focused Vitest targets run and pass or have source-backed failure notes. * [ ] `npm run typecheck --workspace @factionos/web` passes or any failure is proven pre-existing. * [ ] Desktop and mobile Playwright app pass records the focused bottom-rail browser behavior. * [ ] Docs grep proves no stable docs route Campaigns or Command Center primary work to a summary/details popup. ### Non-Functional Requirements * [ ] Focused surfaces remain accessible by keyboard, touch, and screen-reader labels across desktop and small viewport evidence. * [ ] Documentation preserves local-first privacy and no-claim boundaries. * [ ] User-facing product surfaces and docs contain product-facing copy only; diagnostics and command output stay in session evidence. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary user-facing surfaces contain product-facing copy only * [ ] No new database, migration, dependency, hosted, or external-transfer scope is introduced *** ## 8. Implementation Notes ### Working Assumptions * Session 07 is an `apps/web` session: the analyzer candidate has `package: "apps/web"`, Phase 21 targets `apps/web` cockpit surfaces and web tests, and the only expected cross-root work is documentation and repo-level Playwright evidence. * Stable docs to audit are `docs/orchestration-quickstart.md`, `apps/web/README_web.md`, `docs/README_docs.md`, `docs/ARCHITECTURE.md`, and `README.md`: `rg` found current Command Center routing and product-surface claims in those files, and planning can proceed because the implementation task includes a docs audit before edits. * Session 06 browser evidence is a baseline, not final closeout evidence: its `browser-verification.md` proves the responsive pass, while the Session 07 stub requires final regression proof after the phase work is complete. ### Key Considerations * Keep `OrchestrationDetailPortal`, Quest Board summary, and War Room summary as secondary inspectors only if retained. * Do not promote unsupported executor, remote, hosted, certification, identity, production, or erasure claims. * Any test failure must be classified as Phase 21 regression, pre-existing failure, or environment issue with command evidence. ### Potential Challenges * Broad focused suites may uncover unrelated failures: record exact evidence and repair only failures tied to Phase 21 scope. * Browser automation can be sensitive to concurrent dev-server state: rerun the exact focused command by itself before declaring a blocker. * Docs may use different labels for the same entry path: update the operator path without duplicating detailed Command Center contracts. ### Relevant Considerations * \[P20] **Release evidence is the execution claim source**: final Phase 21 claims must cite tests and browser-visible proof before closeout. * \[P20] **Do not add action verbs before evidence**: docs must not add execute, dispatch, apply, recover, or hosted wording beyond shipped behavior. * \[P20] **Broad privacy gates are release-critical**: evidence and docs must keep raw commands, output, diffs, file contents, tokens, provider payloads, Worker authority, and broad paths out of broad product surfaces. * \[P03] **Stable docs are the current contract**: stable docs must match the implemented Command Center and bottom-rail focused-surface entry path. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Closeout evidence passes while docs still route users to a secondary summary inspector instead of the working Command Center. * Repair work accidentally forks panel state or duplicates mounted panel trees. * Browser and docs evidence overclaim formal accessibility, hosted production, identity, erasure, or remote execution boundaries. *** ## 9. Testing Strategy ### Unit Tests * Run focused shell/accessibility tests: `npm test -- apps/web/tests/CockpitShell.test.tsx apps/web/tests/MobileAccessibility.test.tsx` * Run panel parity tests: `npm test -- apps/web/tests/OrchestrationPanel.test.tsx apps/web/tests/QuestBoard.test.tsx apps/web/tests/WarRoomPanel.test.tsx` * Run shortcut tests: `npm test -- apps/web/tests/keyboardShortcuts.test.ts apps/web/tests/commandCenterShortcuts.test.ts apps/web/tests/KeyboardShortcutsModal.test.tsx` ### Integration Tests * Run `npm run typecheck --workspace @factionos/web`. * If focused source repairs occur, rerun the directly affected focused test file before the broader target. ### Runtime Verification * Run desktop/mobile browser coverage: `npm run test:e2e -- --project=app-desktop --project=app-mobile tests/e2e/app.e2e.ts` * Record focused-surface browser results in the session browser evidence file. ### Edge Cases * Small viewport focused Orchestration with Campaigns tab visible and no grid clipping. * Escape closes nested summary/drawer layers before the parent focused surface. * Docs mention summary/state popups only as secondary inspectors. * Any pre-existing or environment failure is separated from Phase 21 regression repairs. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase21-session01-expansion-state-foundation`, `phase21-session02-shared-expansion-host`, `phase21-session03-orchestration-command-center-expansion`, `phase21-session04-shortcut-and-overlay-layering`, `phase21-session05-quest-board-and-war-room-parity`, `phase21-session06-responsive-layout-and-accessibility-pass` * Depended by: Phase 21 `updateprd`, then `audit` if all Phase 21 sessions are complete *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # 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-session07-final-regression-and-documentation/spec.md?ask=&goal= ``` `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.