mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nexus/docs/plans/2026-04-11-nexus-phase-16-cleanup.md
Nexus Dev 87b45c730c docs(nexus): wave 3 plans (phases 12-16) + phase 11.5 backlog 
Six plans drafted after Wave 2 completed:

Phase 11.5 — per-project scoping follow-up (BACKLOG)
  The 5 BLOCKED tabs from Phase 11 (Agents, Gates, Costs, Activity,
  Org) each need projectId scoping in the corresponding backend types
  and list components. Not time-critical — shipped as TabPlaceholder
  components in Phase 11 with honest data-gap badges. Each of the 5
  tickets is self-contained and can run independently when the
  placeholder UX hurts or when Wave 3 completes. Recommends dropping
  the Org tab entirely rather than building per-project scoping for it.

Phase 12 — Promote-to-project transition (WAVE 3)
  Replaces Phase 9's synchronous assistantHandoff() with the animated
  700ms compress-and-rise from spec 5.6. New files: PromoteTransition,
  BrainstormerPanel, usePromoteToProject state machine. CSS-first
  animation, not Motion library. Respects prefers-reduced-motion.
  Depends on Phase 9 (Assistant) and Phase 11 (Projects).

Phase 13 — Settings consolidation (WAVE 3)
  Collapses the nested instance-settings tree into a single-column
  scroll with 8 section cards (Workspace, LocalAI, Cloud, Skills,
  Routines, Telegram, About, Danger). Phase 13 is the one phase
  where routing changes ARE phase-owned: it strips nested
  /instance/settings sub-routes and replaces with Navigate redirects.

Phase 14 — Voice + CmdK globalization (WAVE 3)
  Lifts voice state out of ChatInput's internal VoiceMicButton into
  a shared VoiceContext so the top-strip GlobalMicButton becomes
  functional from any route, with speech queued to the Assistant
  inbox per spec 5.5. Replaces the CmdKButton synthetic-keydown shim
  with a real CommandPaletteContext. Extends CommandPalette search
  to cover conversations, projects, issues, agents, settings,
  workshops. Also fixes the pre-existing useKeyboardShortcuts.ts
  destructure bug caught during Phase 6/11 reviews.

Phase 15 — Mobile parity (WAVE 3)
  4-destination MobileTabBar replacing MobileBottomNav. History +
  Memory sheets become full-screen on mobile. Promote transition
  uses a full-screen takeover instead of split layout. BuilderTabStrip
  scrolls horizontally with edge fades. Single 768px breakpoint.

Phase 16 — Cleanup pass (WAVE 4, sequential)
  Deletes dead chrome files (ChatPanel, ChatPanelContext, Sidebar,
  InstanceSidebar, BreadcrumbBar, PropertiesPanel, MobileBottomNav).
  Migrates ChatMessageList off ChatPanelContext first (flagged
  hazard from Phase 9). Vocabulary sweep company to workspace in
  UI strings only (backend keeps company identifiers per upstream
  sync constraint). Fixes the minor issues accumulated across
  Phase 8-15 reviews (useKeyboardShortcuts destructure bug,
  GlobalMicButton test double-render, Projects umbrella regex
  duplication, PersonalAssistant brittle fixed height). Visual
  QA pass.

Wave structure for Wave 3 dispatch:
  Wave 3A: Phase 12, Phase 13, Phase 14, Phase 15 in parallel
           (4 subagents, disjoint file ownership)
  Wave 3B: Phase 16 sequential (intentionally touches everything)

Phase 11.5 stays in backlog — not in any wave. It activates when
the TabPlaceholder UX becomes a friction point or when a milestone
explicitly pulls one of its tickets into scope.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-11 13:11:12 +00:00

9.5 KiB
Raw Blame History

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