# Nexus Phase 16 — Cleanup Pass

> **Sequential, not parallel.** This phase touches everything. Use `superpowers:test-driven-development` only for any non-trivial logic change; most of Phase 16 is deletion and find-replace.

**Goal:** Delete the dead chrome code that Phase 8 unmounted, sweep the UI copy for "company" → "workspace" (or deletion), fix accumulated minor issues surfaced by review cycles across Phases 8–15, and perform a final visual QA pass.

**Source of truth:** spec §2 "Killed list" and the list of known minor issues logged across Phase 8–15 reviews.

**Branch:** `nexus/design-system-migration`. This is the LAST phase of the structural overhaul.

---

## Ownership boundaries

**Phase 16 is intentionally broad.** You may touch any file in `ui/src/` that contains dead chrome code, legacy vocabulary, or accumulated cruft. However:

- Do NOT touch `server/`, `packages/`, or `cli/` — the backend vocabulary stays per PROJECT.md's upstream-sync constraint
- Do NOT touch any test file unless its assertions reference dead code you're deleting
- Do NOT introduce new features — this is strictly subtraction
- Do NOT touch the `.planning/` directory

If in doubt whether a file is dead, run `grep -r "<SymbolName>" ui/src/` — if there are zero remaining consumers, it's dead. If there's any consumer, escalate before deleting.

---

## Scope

### 1. Delete dead chrome files (spec §2 "Killed list")

Files Phase 8 unmounted but didn't delete. Verify each has zero consumers, then delete:

- `ui/src/components/ChatPanel.tsx` — the old 380px slide-in chat panel
  - **HAZARD:** `ChatMessageList` is hard-bound to `ChatPanelContext` (Phase 9 note). Before deleting `ChatPanelContext.tsx`, migrate `ChatMessageList` off it. See "ChatMessageList migration" below.
- `ui/src/context/ChatPanelContext.tsx` — only after `ChatMessageList` migration
- `ui/src/components/PropertiesPanel.tsx` — unless a page-level usage still exists (grep first)
- `ui/src/components/Sidebar.tsx` — the 280px left sidebar
- `ui/src/components/InstanceSidebar.tsx` — already slated by Phase 13; confirm deleted
- `ui/src/components/BreadcrumbBar.tsx` — replaced by ModeBreadcrumb
- `ui/src/components/MobileBottomNav.tsx` — replaced by MobileTabBar (Phase 15)

For each deletion, also delete the corresponding `.test.tsx` / `.stories.tsx` file and search the codebase for any remaining imports. If any import survives, fix it in the same commit.

### 2. ChatMessageList migration

Phase 9 flagged: `ChatMessageList.tsx` reads `activeConversationId` / `scrollToMessageId` from `ChatPanelContext`. Phase 16 must migrate these reads OFF the legacy context before deleting it.

**Migration strategy:** introduce `AssistantChatContext` in `ui/src/context/AssistantChatContext.tsx` that owns `activeConversationId` and `scrollToMessageId`. Update `ChatMessageList` to consume it. Update `PersonalAssistant` and any other consumers to provide the new context. Delete `ChatPanelContext` only AFTER all consumers moved.

Alternative: if the state is better owned by URL params (`/:conversationId` + a query param for scroll target), refactor that way. Cleaner but more invasive.

### 3. Vocabulary sweep — "company" → "workspace"

Per spec §2: "Any text containing 'company', 'companies', 'workspace member', 'tenant' → vocabulary cleanup."

Scope: **display-only strings** in `ui/src/`. Do NOT rename code symbols. The UI says "workspace" while the backend keeps `company` / `companyId` identifiers forever (upstream sync constraint from PROJECT.md).

- Find all UI strings with "company" / "Company" / "companies" / "Companies" / "Tenant" / "tenant"
- Replace with "workspace" / "Workspace" / "workspaces" / "Workspaces"
- Exception: if `@paperclipai/branding` already has a `VOCAB.company` token that resolves to "Workspace", just use that — don't hand-type the replacement
- Exception: error messages from the backend that include "company" — leave alone, they come from the server

### 4. Minor issues accumulated across Phase 8–15 reviews

These were flagged during reviews but deferred to Phase 16. Fix each in a clearly-labelled commit:

1. **`useKeyboardShortcuts.ts:12-17` destructure bug** — the type declares `onSearch?: () => void` but the destructure omits it, so the call at line 25 always resolves to undefined. If Phase 14 hasn't already fixed this, fix it here.
2. **`GlobalMicButton.test.tsx` double-render warning** — the test's `render(state)` helper is called 3 times in one test without unmounting between. Cosmetic but noisy. Refactor to unmount between renders or split into 3 separate tests.
3. **`IconRail.tsx` Projects umbrella regex repetition** — 10 regexes with `||`. Extract to a constant list + `.some()` helper. Coordinate with Phase 11's note about duplicated-umbrella-list-drift.
4. **`PersonalAssistant.tsx` message-thread fixed height** `calc(100vh - 320px)` — brittle. Investigate replacing with a flex layout that derives height from flex parent, now that the surrounding chrome is stable.
5. **`Projects.tsx` phase / costBurnedCents / activeAgentsCount gaps** — still rendering as null. Phase 16 doesn't fix the data gaps (that's Phase 11.5), but it removes the `// TODO` comments that were added by Wave 2.5 IF Phase 11.5 has already landed.
6. **Spec drift from Phase 10 commit 5 missing body** — optional: amend the commit or just leave it. Low priority.
7. **Phase 10 `PresentationPanel` fold-in** — Wave 2.5 already handled this. If Phase 16 finds `PresentationPanel` is dead code for any reason (e.g. spec changed), delete it.

### 5. Top-level route deletion decisions

Phase 11 demoted several routes to per-project tabs but kept them at the top level for backwards compat:

- `/issues` → now a per-project tab. Delete?
- `/agents` → now a per-project tab. Delete?
- `/approvals` → now a per-project `/gates` tab. Delete?
- `/costs` → now a per-project tab. Delete?
- `/activity` → now a per-project tab. Delete?
- `/inbox` → replaced by Assistant dot + ⌘K. Delete?
- `/goals` → folded into Overview milestone checklist. Delete?
- `/routines` → moved to Settings in Phase 13. Delete?
- `/org` → now a per-project tab. Delete?
- `/dashboard` → replaced by Assistant home greeting. Delete?
- `/convert` → folded into Studio. Delete?

**Decision rule:** delete IF the corresponding Phase 11 / 13 / 15 replacement fully covers the use case AND there are no external bookmarks / docs pointing at the route. If in doubt, keep and flag for user decision.

**Safer default:** keep all of them for now as backwards-compat redirects. If Phase 16 finds clear dead code (component exists but its route is already a `<Navigate>` to a new home), delete. If the page still renders real UI, keep.

### 6. Visual QA pass

Walk every top-level route in the dev server, compare against DESIGN.md principles and the layout spec. Capture issues as a short list and either fix inline or file follow-up tickets. No code changes unless issues found.

Routes to walk:
- `/assistant` (with and without active conversation)
- `/content-studio` + each workshop
- `/projects` (populated and empty states)
- `/projects/<slug>/overview` + each tab
- `/instance/settings/general`
- `/convert` (legacy)
- `/approvals` (legacy)

---

## Sequential commits (suggested)

This phase is naturally sequential. Each commit is reviewable independently.

1. `refactor(nexus): migrate ChatMessageList off ChatPanelContext (phase 16)`
2. `refactor(nexus): delete legacy chrome files (phase 16)` — Sidebar, InstanceSidebar, ChatPanel, ChatPanelContext, PropertiesPanel, BreadcrumbBar, MobileBottomNav
3. `refactor(nexus): vocabulary sweep company -> workspace (phase 16)`
4. `fix(nexus): useKeyboardShortcuts destructure bug (phase 16)`
5. `refactor(nexus): fix GlobalMicButton test double-render warning (phase 16)`
6. `refactor(nexus): extract shared PROJECTS_UMBRELLA constant (phase 16)`
7. `refactor(nexus): PersonalAssistant message-thread flex layout (phase 16)`
8. `refactor(nexus): delete dead top-level routes (phase 16)` — only routes whose components are pure redirects
9. `docs(nexus): visual QA findings (phase 16)` — any issues found during QA, either fixed inline or filed

Group commits together only when they touch the same file for the same reason.

---

## Acceptance criteria

1. All files listed in §1 are deleted or clearly documented as intentionally kept
2. `ChatMessageList` no longer consumes `ChatPanelContext`
3. Zero UI strings say "company" or "Company" (except via `VOCAB.company` token)
4. Known minor issues from §4 are fixed or tickets filed
5. Full test suite passes: `npx vitest run src/components/frame/ src/components/assistant/ src/components/studio/ src/components/projects/ src/components/settings/ src/hooks/`
6. Typecheck clean on all Wave 1–3 files
7. Visual QA pass findings logged (either fixed inline or filed)
8. The commit chain on `nexus/design-system-migration` is complete and ready for merge / PR review

---

## Non-scope

- Backend vocabulary changes (`company` identifiers stay — upstream sync)
- Phase 11.5 per-project-scoping work (separate plan)
- Phase 4–7 visual migration polish (can run before or after Phase 16, independent)
- New features
- Performance optimization
- Test coverage expansion beyond what's needed to protect deletions

---

## Report format

- Status (DONE / DONE_WITH_CONCERNS / BLOCKED)
- Commit SHAs with one-line summaries
- Files deleted (with confirmation of zero consumers)
- Files moved / refactored (e.g. ChatMessageList migration)
- Vocabulary sweep count (how many strings changed)
- Minor issues fixed vs deferred
- Visual QA findings
- Final typecheck + test suite result
- Concerns