nexus/docs/plans/2026-04-11-nexus-phase-11-5-per-project-scoping.md

Nexus Phase 11.5 — Per-Project Scoping Follow-Up

Status: Drafted 2026-04-11. Not yet started. Queued after Wave 3 completes, unless the TabPlaceholder UX pain surfaces earlier.

Why this exists: Phase 11's subagent discovered that 5 of the 6 new Project Detail "Builder" tabs have no existing projectId-aware list component to reuse, and the underlying type system doesn't carry project association on the relevant entities. Rather than halt Phase 11, the subagent shipped visible TabPlaceholder components that render a "PHASE 11 DATA GAP" badge with a precise description of what each tab needs. Those placeholders work as honest diagnostic UI but are not the final product.

Source of truth: docs/plans/2026-04-11-nexus-phase-11-projects-builder.md (original phase 11 plan), Phase 11's final subagent report, and docs/specs/2026-04-11-nexus-layout-overhaul.md §7.2 for the target UX.

---

1. The five gaps

Each gap is a self-contained ticket that can be worked independently. Ordering is flexible but the agents/gates/costs trio share some backend patterns and are best done together; activity and org are their own work.

1.1 AGENTS tab — per-project agent list

Goal: Render the agents assigned to or actively working on a specific project, in the AgentsTab component currently showing a TabPlaceholder.

Current state:

• ui/src/pages/Agents.tsx — 100+ lines of inline list + filter UI, not extracted as a reusable component
• Agent type in @paperclipai/shared has no projectId field and no reverse index to projects
• agentsApi.list(companyId) returns all agents for a company, no filter options

Scope:

1. Define the agent ↔ project relationship. Two options:
   • (a) Add projectId: string | null to the Agent type + DB column, backfilled by looking at the agents' currently-assigned issues. Simplest, requires a migration.
   • (b) Derive the relationship from assigned issues: an agent is "on project X" if it has any open issue in X. No schema change; frontend join; more expensive to query.
   • (c) Add a project_agents join table for explicit assignment; requires migration and a separate assignment UI.
2. Extract AgentList as a reusable component from Agents.tsx, with a projectId?: string | null prop.
3. Wire into AgentsTab — replace the TabPlaceholder.

Recommendation: start with (b) — pure frontend derivation from the issue query already in memory (Phase 11.5 already fetches all issues for ProjectCard derivatives; piggyback on that cache). If the UX turns out to need explicit assignment semantics (e.g., "assign this agent to project X even though they have no issues yet"), escalate to (a) or (c) later.

Files to touch:

• ui/src/components/agents/AgentList.tsx (new — extract from Agents.tsx)
• ui/src/components/projects/tabs/AgentsTab.tsx (update — remove TabPlaceholder, render <AgentList projectId={projectId} />)
• ui/src/pages/Agents.tsx (small refactor — consume the new AgentList for the unscoped case)

Acceptance: AgentsTab renders the subset of company agents that have any open issue whose projectId matches the current project. Hover/click behavior matches the existing Agents page.

---

1.2 GATES tab — per-project pending approvals

Goal: Render the approvals (display: "gates") for a specific project in the GatesTab.

Current state:

• Approval.payload is Record<string, unknown>. Some approval types carry payload.projectId by convention; most don't.
• ApprovalsList or equivalent doesn't exist as a standalone component; ui/src/pages/Approvals.tsx is inline.
• approvalsApi.list(companyId, status) returns all approvals scoped by status, no project filter.

Scope:

1. Audit approval types for projectId coverage. Grep the server and UI for approval payload shapes; list which types carry projectId and which don't. Types that don't need either:
   • (a) have a projectId added to their payload going forward (backward-compat default: null)
   • (b) be filtered out of the per-project view and only surfaced in the global /approvals route
2. Lift the frontend filter already used by Projects.tsx (buildProjectDerivatives probes payload.projectId) into a shared filterApprovalsByProject(approvals, projectId) helper.
3. Extract ApprovalsList as a reusable component with a projectId?: string | null prop and a display-mode toggle for "Gates" vs "Approvals" copy.
4. Wire into GatesTab — replace TabPlaceholder, use "Gates" copy.

Files to touch:

• ui/src/lib/approval-filters.ts (new — shared filter helper)
• ui/src/components/approvals/ApprovalsList.tsx (new — extract from Approvals.tsx)
• ui/src/components/projects/tabs/GatesTab.tsx (update)
• ui/src/pages/Approvals.tsx (refactor — consume new component)

Acceptance: GatesTab renders pending+historical approvals whose payload.projectId matches. Copy uses "Gate" / "Gates" everywhere. Underlying API calls remain on /api/approvals.

---

1.3 COSTS tab — per-project cost burn

Goal: Render cost breakdown for a specific project in CostsTab.

Current state:

• ui/src/pages/Costs.tsx is ~1100 lines of inline content — aggregation, charting, filters, and layout all in one file
• No CostsBreakdown standalone component
• costsApi probably has per-company totals; per-project breakdown depends on the cost event records carrying projectId (likely yes because costs roll up to projects in the existing UI somewhere)

Scope:

1. Read Costs.tsx and identify the breakdown section (the chart/table that shows costs by project or by agent). If it exists, extract to CostsBreakdown.tsx with a projectId?: string | null prop.
2. If the existing costs API doesn't support per-project filtering, add a server-side filter to the endpoint (small backend change) or filter on the client (acceptable if cost events are bounded).
3. Wire into CostsTab — replace TabPlaceholder.

Files to touch:

• ui/src/components/costs/CostsBreakdown.tsx (new — extract)
• ui/src/components/projects/tabs/CostsTab.tsx (update)
• ui/src/pages/Costs.tsx (refactor)
• Possibly server/src/routes/costs.ts (add projectId filter param)

Acceptance: CostsTab renders cost events for the current project with an agent-by-agent breakdown. The global /costs page still works.

---

1.4 ACTIVITY tab — per-project activity feed

Goal: Render an activity feed scoped to a single project in ActivityTab.

Current state:

• activityApi.list(entityType, entityId) already supports filtering by entity — this is the easiest of the five gaps
• ui/src/pages/Activity.tsx renders the unscoped feed inline, no standalone component

Scope:

1. Extract ActivityFeed as a reusable component from Activity.tsx with a { entityType: string; entityId: string | null; companyId: string } prop shape.
2. Wire into ActivityTab — call <ActivityFeed entityType="project" entityId={projectId} companyId={companyId} />.

Files to touch:

• ui/src/components/activity/ActivityFeed.tsx (new — extract)
• ui/src/components/projects/tabs/ActivityTab.tsx (update)
• ui/src/pages/Activity.tsx (refactor)

Acceptance: ActivityTab renders a filtered feed for the current project. Global /activity still works. The proxy in Wave 2.5's ProjectCard (newest issue updatedAt) can optionally be replaced with this feed's latest event.

This is the lowest-effort ticket of the five. Start here if you want a quick win.

---

1.5 ORG tab — per-project org chart

Goal: Render the subset of the org chart relevant to a specific project in OrgTab, hidden entirely for single-agent projects.

Current state:

• agentsApi.org(companyId) returns a company-wide tree
• ui/src/pages/Org.tsx (or similarly named) renders the full tree inline
• No way to query "which agents and what reporting structure are relevant to project X"

Scope:

1. Define what "project-scoped org chart" means. Options:
   • (a) Show the subset of agents assigned to the project (from ticket 1.1) with their existing reporting relationships preserved.
   • (b) Show the full company org with non-project agents visually dimmed.
   • (c) Drop the tab entirely for Phase 11.5 — the ORG tab is already hidden for single-agent projects, and multi-agent projects might be better served by the global /org page than a per-project subview.
2. If (a) or (b), extract OrgChart as a standalone component with a highlightAgentIds?: string[] or agentIdFilter?: string[] prop.

Recommendation: (c) — drop the ORG tab entirely for Phase 11.5 unless you actively miss it. The single-agent auto-hide already reduces the surface; multi-agent projects are rare enough that the global org page suffices. If the tab is dropped, delete OrgTab.tsx and update BuilderTabStrip.tsx to unconditionally hide it.

Files to touch (if not dropped):

• ui/src/components/agents/OrgChart.tsx (new — extract)
• ui/src/components/projects/tabs/OrgTab.tsx (update)
• ui/src/pages/Org.tsx (refactor)

Acceptance (if not dropped): OrgTab renders a subtree of agents relevant to the project. Still hidden for single-agent projects.

---

2. Dependency order and parallelism

Ticket 1.4 (Activity)    ←  lowest effort, start here
Ticket 1.1 (Agents)      ←  unblocks Ticket 1.5 if we keep Org
Ticket 1.2 (Gates)       ←  independent
Ticket 1.3 (Costs)       ←  independent, backend work TBD
Ticket 1.5 (Org)         ←  drop it, or wait on Ticket 1.1

Tickets 1.2, 1.3, 1.4 are pure-frontend extractions and can run in parallel. Ticket 1.1 may involve a schema decision that blocks parallelization. Ticket 1.5 is suggested to drop.

3. Non-scope (things Phase 11.5 does NOT do)

• Adding real milestoneProgress, phasesCompleted, phasesTotal fields to the Project record. That's a Phase 11.6 backend phase if wanted, or accepted as permanent client-side proxy.
• Adding originConversationId to the Project record. Same disposition.
• Adding costBurnedCents aggregate to the Project record. Same.
• Adding explicit project_agents join table. That's (c) in Ticket 1.1 and deferred unless issue-derivation proves insufficient.
• Phase 14's ⌘K globalization (that's its own phase in Wave 3).
• Phase 16 cleanup of dead top-level routes like /approvals, /agents, /activity, /org, /costs. Those pages stay for backwards compat until Phase 16 decides their fate.

4. Triggering condition

This plan sits in the backlog until either:

1. The TabPlaceholder UX hurts — user hits one of the 5 blocked tabs frequently and the "data gap" badge becomes a friction point. At that moment, promote whichever tab is hurting most to active work.
2. Wave 3 completes and the team has bandwidth for backend-adjacent tickets.
3. A v1.8+ milestone explicitly pulls one of these scoping stories into scope (e.g., "project-level cost budgeting" would pull in Ticket 1.3).

None of these tickets is time-critical. The placeholders are honest and diagnosable — users can see "PHASE 11 DATA GAP: project-scoped costs not yet implemented" and navigate to the global /costs page if they need the data.

5. Execution

When ready to start, write a narrow implementation plan per ticket (one plan per ticket), using the same format as Phase 8's task-by-task TDD plan. Dispatch via subagent-driven-development for tickets 1.2–1.5 and in-session for ticket 1.1 (because it requires an architectural decision).

Do not dispatch all five tickets as one subagent — they touch disjoint subsystems and deserve independent review cycles.