# Feature Spec: AOP Dashboard Command Center Redesign

> Purpose: redefine the root AOP dashboard (`/`) as a triage-first, client-grade command center that surfaces what needs attention now, reduces operational noise, and cleanly hands off deep review to Focus view and Analytics.

**Version:** 1.0
**Date:** 2026-03-14
**Status:** Draft
**Roadmap Mapping:** M47-A (Command Center Core), M47-B (Dashboard Governance + Configuration), M47-C (Insight Layer)
**Depends On:** M44 (dashboard component baseline), M45 (route architecture and advanced dashboard UX), M46 (focus-review and diff/agent-console direction)

---

## 0. Scope and Standards

### 0.1 Primary User Jobs

This redesign optimizes `/` for three jobs in strict priority order:

1. **Client triage job:** understand what requires attention, what is blocked, and what is ready for decision in under 10 seconds.
2. **Operator control job:** detect unhealthy orchestration, lock/dependency contention, and budget risk before throughput degrades.
3. **Navigation job:** move quickly from system-level triage into feature-level Focus view or Analytics without losing context.

The root dashboard is **not** the primary deep-review surface after this redesign. Deep code review, rich diff inspection, agent transcript inspection, and long-form evidence reading belong in `/feature/:id` and `/analytics`.

### 0.2 Current Problems This Spec Corrects

The current root dashboard over-serves system internals and under-serves client decision flow:

- The page mixes board triage and deep feature review into one route, creating excessive cognitive load.
- The right-side detail panel performs too much work and fetch fanout for a triage surface.
- The information hierarchy is system-centric (`phase`, `activity_state`, internal gate labels) instead of client-centric (`Needs Me`, `At Risk`, `Ready`, `Stalled`).
- Cost is still surfaced as the primary usage metric in several places, even though token usage is the better operational baseline.
- The current policy/config surface for the dashboard is too limited for a real client-facing control plane.
- Mutating actions are not governed consistently enough for a client-grade dashboard.
- The layout creates too many independent scroll regions and too much below-the-fold interaction cost.

### 0.3 Non-Negotiable Principles

1. **Triage first:** the first screen must answer what needs attention now.
2. **Client language over system language:** derived labels should map internal state into actionable client meaning.
3. **Progressive disclosure:** rich diagnostics remain available, but not at the expense of board scanability.
4. **Token-first usage truth:** token usage is the primary budget/usage metric; USD is optional derived context.
5. **Safe by default:** mutating actions and sensitive data exposure must be explicitly governed.
6. **Route clarity:** `/` is command center, `/feature/:id` is deep feature focus, `/analytics` is trend analysis.

### 0.4 Required Quality Standards

All implementation for this spec MUST satisfy:

- TypeScript strict mode passes.
- ESLint zero warnings.
- `npm run build`, `npm run typecheck`, `npm run lint`, and `npm test` pass.
- Coverage remains >= 90% lines/branches/functions/statements.
- Accessibility baseline is WCAG 2.2 AA for all new interactive UI.
- Primary triage workflows remain usable at 360px CSS width without page-level horizontal scrolling.

### 0.5 Visual System Contract

The root dashboard redesign MUST use the current shared Aequitas-inspired light visual system already established in the dashboard codebase:

- Light surfaces and elevated white/light-blue panels.
- Teal primary action styling.
- Gold/orange warning emphasis.
- Slate primary and secondary text.
- Red reserved for destructive/blocked/critical states.
- Soft borders and shadows rather than dark-console framing.

This spec explicitly rejects reintroducing the earlier dark operations-console palette for `/`.

### 0.6 Out-of-Scope Clarification

This redesign does **not** make `/` a replacement for:

- reviewer-grade diff workspace
- full agent console
- raw log investigation
- full checkpoint comparison
- rich evidence reading

Those remain in Focus view and related M46 work.

---

## 1. Experience Architecture

### 1.1 Route Roles

The product surface is intentionally split:

1. **Board / Command Center (`/`)**
   - triage
   - queue management
   - lightweight feature preview
   - operator health
   - fast navigation
2. **Focus View (`/feature/:id`)**
   - deep review
   - review actions
   - transcript/runtime/diff/evidence
3. **Analytics (`/analytics`)**
   - trends
   - provider and throughput analysis
   - portfolio-level reporting

### 1.2 Root Dashboard Information Hierarchy

The root page MUST render in this order:

1. Command Center Header
2. Attention Strip
3. Task-First Filter Bar
4. Main Triage Layout
5. Secondary Diagnostics Rail

This is a hierarchy requirement, not a mere layout preference.

### 1.3 Main Triage Layout

Desktop:

- Left: prioritized work queues and board/list switchable portfolio view
- Right: lightweight triage drawer for selected feature

Tablet/mobile:

- Attention Strip and task filters remain above the fold
- Board/list becomes primary content
- Selecting a feature opens an overlay or anchored drawer optimized for quick inspection
- Full review should route to Focus view rather than trying to replicate full detail inline

### 1.4 Triage Drawer Rule

The root dashboard selection panel is renamed conceptually from a **detail panel** to a **triage drawer**.

It MUST answer:

- Why is this feature relevant right now?
- What is the current status and substate?
- What changed recently?
- What is blocking it?
- What actions are valid here?
- Should I stay here or open Focus view?

It MUST NOT try to be a full review workspace.

---

## 2. Delivery Tracks

### 2.1 Track A - Command Center Core

Track A is the required root-dashboard redesign:

- triage-first page hierarchy
- attention strip
- task-first filters
- lighter triage drawer
- richer board cards
- merged/archive demotion
- reduced scroll complexity
- token-first usage presentation on `/`

### 2.2 Track B - Governance + Configuration

Track B productizes the dashboard for external-facing/client-safe usage:

- dashboard policy schema expansion
- action authorization hardening
- module visibility configuration
- redaction controls
- project metadata improvements
- token-to-USD optional conversion contract

### 2.3 Track C - Insight Layer

Track C adds higher-order insight and recency intelligence:

- “what changed since last visit”
- client-facing attention ranking
- staleness and SLA signals
- derived portfolio summaries
- queue trend and workload signals

Track C must not block Track A.

---

## 3. Revised Improvements (UX-50 to UX-62)

### UX-50 - Command Center Header

**Intent:** establish a stronger top-of-page control surface and orient the user immediately.

**Requirements:**

- Header shows:
  - page title
  - live connection state
  - current project/environment
  - last snapshot freshness
  - quick link to Analytics
- Board/List toggle remains, but it is secondary to task filters.
- Project switcher should display client-facing project labels when configured, not only raw internal names.
- Header copy should be client-comprehensible, not only system-observability language.

### UX-51 - Attention Strip

**Intent:** replace generic aggregate-first scanning with ranked urgency.

**Requirements:**

- Render a first-class strip above the general summary tiles.
- Attention cards must include, at minimum:
  - `Needs Your Input`
  - `Blocked`
  - `Ready To Merge`
  - `Stalled`
  - `Budget Risk`
  - `Run Health`
- Each card must include count, severity, and a short reason label.
- Clicking an attention card applies a task filter preset.
- Attention ranking must prioritize human-blocking states over passive metrics.

### UX-52 - Task-First Filter Bar

**Intent:** let clients filter by job-to-be-done instead of raw internal state.

**Requirements:**

- Default presets:
  - `Needs Me`
  - `At Risk`
  - `Ready`
  - `Stalled`
  - `Waiting On Dependencies`
  - `Waiting On CI`
  - `Recently Changed`
- Existing phase/activity filters move under an `Advanced Filters` disclosure section.
- Filter state remains URL-synced.
- Search must match feature id and, when available, user-facing goal/intent summary.
- The board must show explicit empty states for active task filters.

### UX-53 - Prioritized Work Queues

**Intent:** give clients a ranked operational queue before showing the full portfolio board.

**Requirements:**

- Render compact queue modules above the board:
  - `Action Required`
  - `Ready For Review`
  - `Blocked Critical Path`
  - `Recently Changed`
- Each queue entry includes:
  - feature id
  - short reason
  - recency
  - one-click select
  - one-click open in Focus view
- Queue ordering must be deterministic.
- Queue modules may collapse when empty.

### UX-54 - Richer Board Cards for Client Decisions

**Intent:** make the board useful without forcing frequent drawer opens.

**Requirements:**

- Each card MUST support:
  - feature id
  - phase chip
  - client-facing substate label
  - last meaningful update age
  - waiting-input indicator
  - dependency/lock indicator
  - CI/review readiness indicator
  - usage/budget state
- The card should answer “what is happening here” in one glance.
- Internal raw labels such as `activity_state` may remain in tooltips or advanced metadata, but should not be the primary visible label.
- `Merged` cards should not consume equal prominence with active work.

### UX-55 - Merged Archive Demotion

**Intent:** prevent completed work from diluting active triage.

**Requirements:**

- `Merged` moves out of the primary active board layout.
- Acceptable implementations:
  - collapsed archive section
  - dedicated `Merged` tab
  - compact summary list
- Active triage views must prioritize non-terminal work.
- Merged items remain discoverable and searchable.

### UX-56 - Lightweight Triage Drawer

**Intent:** replace the heavy root detail panel with a fast, job-oriented preview surface.

**Requirements:**

- Drawer sections:
  - overview
  - why this needs attention
  - blockers/dependencies
  - review/PR snapshot
  - usage snapshot
  - next valid actions
  - open Focus view CTA
- The drawer MUST NOT eagerly load all deep-review data currently fetched by the full `DetailPanel`.
- Deep sections such as full diff, raw evidence, checkpoint comparison, and runtime internals must not be first-class content on `/`.
- The drawer may include small previews, but full workflows route to Focus view.

### UX-57 - Token-First Usage and Budgeting

**Intent:** make usage reporting operationally truthful and consistent across the product.

**Requirements:**

- Root dashboard usage displays are token-first.
- Replace `Cost Today` language on `/` with `Usage Today` or equivalent token-first wording.
- Primary board metrics:
  - total tokens today
  - per-feature tokens used
  - per-feature token budget state
- USD may be shown only as optional secondary context when conversion is configured.
- If conversion is absent, no derived USD should be shown.

### UX-58 - Action Governance Model

**Intent:** make client-visible mutating actions safe and explicitly governed.

**Requirements:**

- Dashboard actions requiring governance:
  - approve
  - deny
  - request changes
  - retry
  - send message
  - quick launch
- Authorization checks must not be limited to quick launch only.
- Disabled actions must render explanatory UI states, not silent disappearance unless policy explicitly requests hiding.
- Each action should declare:
  - enabled/disabled
  - authorized/unauthorized
  - reason

### UX-59 - Redaction-Safe Client Mode

**Intent:** allow the same dashboard to serve both internal operators and external/client stakeholders safely.

**Requirements:**

- Sensitive surfaces requiring explicit policy control:
  - raw logs
  - raw evidence
  - exact file paths
  - provider/model internals
  - low-level runtime/session wiring
- The root dashboard must support redacted display modes.
- Redaction should affect presentation and route availability where required.
- Redacted states must be clear and non-broken.

### UX-60 - Project Metadata and Portfolio Switching

**Intent:** make multi-project usage feel productized rather than filesystem-driven.

**Requirements:**

- Multi-project switcher should support:
  - display label
  - environment
  - owner/team
  - sort order
  - pinned/default project
  - archived/hidden state
- Raw path information must not be required in UI.
- The active project context should be obvious in the header and URL.

### UX-61 - Change Detection and “Since You Last Looked”

**Intent:** reduce repeat scanning cost for returning users.

**Requirements:**

- The dashboard should support change markers for:
  - newly blocked
  - newly ready to merge
  - new human-input request
  - CI regression
  - budget threshold crossed
- Track C may use local persisted client state or server-side cursors, but implementation must clearly define which.
- Change markers should be subtle but prominent enough to support fast rescanning.

### UX-62 - Scroll, Density, and Mobile Corrections

**Intent:** remove avoidable friction from the board interaction model.

**Requirements:**

- Reduce nested scrolling where possible.
- On narrow screens, selected-feature preview must not require a long scroll below the full board.
- The root page must avoid stacking a full deep-review panel below the board on mobile.
- Dense modules such as live feed, locks, dependencies, and collisions should collapse or move to a secondary diagnostics rail when not urgent.

---

## 4. Data and Loading Contracts

### 4.1 First-Paint Contract for `/`

The root page first paint MUST rely primarily on the status snapshot and not depend on multi-request feature-detail hydration.

Required at first paint:

- portfolio feature summaries
- run health summary
- lock/dependency/collision summaries
- token-usage aggregates
- attention-ranking inputs
- project context

### 4.2 Drawer-Lazy Contract

Selecting a feature in `/` may lazily fetch drawer-only data, but the drawer payload should be materially smaller than Focus view.

Allowed drawer-lazy content:

- compact review snapshot
- short blocker explanation
- brief usage snapshot
- compact PR/review context

Not allowed as required root-route drawer fetches:

- full diff payload
- raw logs
- full evidence bodies
- checkpoint diff comparison
- long transcript streams

### 4.3 Focus Escalation Rule

If a user needs:

- full review actions context
- code diff inspection
- evidence reading
- runtime investigation
- transcript or console workflows

the page should guide them into `/feature/:id` rather than growing `/` into a second deep-review route.

---

## 5. Type and Payload Changes

### 5.1 Dashboard Status Payload Additions

`DashboardStatusPayload.metrics` should evolve to support token-first triage:

```typescript
metrics?: {
  total_tokens_today?: number;
  total_cost_today_usd?: number | null;
  merge_histogram_14d?: number[];
}
```

### 5.2 Feature Summary Additions

`FeatureSummary` should support richer client-facing triage signals:

```typescript
attention_reasons?: string[];
waiting_input_count?: number;
last_meaningful_change_at?: string;
usage_tokens?: number | null;
budget_state?: 'normal' | 'warning' | 'critical' | 'exceeded' | 'unknown';
client_status_label?: string;
```

The server should prefer deriving these once rather than forcing the client to repeatedly reconstruct them from low-level fields.

### 5.3 Triage Drawer Payload

If a separate route is introduced for drawer hydration, it should be explicitly smaller than `FeatureDetail` and optimized for `/`.

Suggested shape:

```typescript
interface FeatureTriageDetail {
  feature: FeatureSummary;
  why_attention: string[];
  blocker_summary?: string | null;
  dependency_summary?: string[];
  review_snapshot?: {
    pr_url?: string | null;
    ci_status?: string | null;
    review_decision?: string | null;
    merge_ready?: boolean | null;
  };
  usage?: {
    tokens_used?: number | null;
    budget_limit_tokens?: number | null;
    derived_cost_usd?: number | null;
  };
}
```

---

## 6. Component Delivery Contract

This section is normative. An implementation agent should not infer the component plan from prose alone. The root dashboard redesign includes explicit component additions, refactors, and removals from `/`.

### 6.1 New Components To Deliver

The following new components are expected as part of Track A unless the implementer can show an equivalent decomposition with equal or better separation of concerns:

#### Root Composition Components

- `components/dashboard/command-center-header.tsx`
  - owns root header presentation
  - includes project context, connection/freshness state, and top-level navigation actions
- `components/dashboard/attention-strip.tsx`
  - owns ranked attention cards
  - applies task-filter presets
- `components/dashboard/task-filter-bar.tsx`
  - owns task-first filters and advanced filter disclosure
- `components/dashboard/prioritized-queues.tsx`
  - owns compact queue modules above the main board/list area
- `components/dashboard/secondary-diagnostics-rail.tsx`
  - owns lower-priority diagnostic modules promoted or collapsed based on urgency

#### Board and Selection Components

- `components/dashboard/triage-drawer.tsx`
  - replaces the current root use of the heavy `DetailPanel`
  - root-route only
- `components/dashboard/merged-archive.tsx`
  - owns merged-item demotion behavior
  - collapsed archive, tab, or compact summary implementation
- `components/dashboard/board-toolbar.tsx`
  - optional but recommended
  - owns board/list mode toggle and any local portfolio view controls separated from the page header

#### Optional Supporting Components

- `components/dashboard/attention-card.tsx`
- `components/dashboard/task-filter-chip-group.tsx`
- `components/dashboard/queue-module.tsx`
- `components/dashboard/triage-overview.tsx`
- `components/dashboard/triage-actions.tsx`
- `components/dashboard/usage-summary-tile.tsx`

These supporting components are not individually mandatory, but the responsibilities they represent should exist somewhere in the new composition.

### 6.2 Existing Components To Refactor

The following existing components are expected to be refactored rather than left unchanged:

- `components/summary-bar.tsx`
  - refactor from aggregate-summary-first toward token-first usage and compatibility with the new attention hierarchy
  - likely reduced in prominence or split internally
- `components/filter-bar.tsx`
  - refactor into a task-first filter surface
  - raw phase/activity controls move behind advanced disclosure
- `components/feature-card.tsx`
  - refactor to support client-facing substate labels, usage state, richer risk/readiness signals, and merged de-emphasis
- `components/kanban-board.tsx`
  - refactor to support merged demotion and integration with prioritized triage model
- `components/feature-list-view.tsx`
  - refactor so list view reflects the same task-first information hierarchy as board view
- `components/run-health-panel.tsx`
  - refactor or wrap so run health can participate in the Attention Strip and secondary diagnostics rail
- `components/dependency-chains.tsx`
  - refactor or wrap for use inside prioritized queues and/or diagnostics rail
- `components/lock-resource-map.tsx`
  - refactor or wrap for diagnostics rail placement and urgency-aware visibility
- `components/collision-queue.tsx`
  - refactor or wrap for diagnostics rail placement and urgency-aware visibility
- `components/quick-launch-panel.tsx`
  - refactor under Track B governance rules so it supports explicit enabled/authorized/reason semantics
- `components/live-event-feed.tsx`
  - refactor for demotion from primary root flow into secondary diagnostics or collapsed affordance

### 6.3 Existing Components To Remove From Root Route

The following components or responsibilities should no longer be primary root-route content once Track A is complete:

- `components/detail-panel.tsx`
  - removed from `/`
  - replaced by `components/dashboard/triage-drawer.tsx`
  - remains available for Focus view or may be further split there

The following deep-review responsibilities must be removed from the root route even if some remain implemented elsewhere:

- full diff viewer rendering
- full evidence viewer rendering
- checkpoint timeline and checkpoint comparison UI
- runtime inspector deep-dive UI
- full review action form as the dominant root selection experience
- long history/log sections

### 6.4 Existing Components That Remain Focus-View Or Deep-Review Concerns

These components are not root command-center primitives after this redesign and should remain attached to Focus-view or deep-review contexts:

- `components/diff-viewer.tsx`
- `components/evidence-viewer.tsx`
- `components/gate-step-drilldown.tsx`
- `components/review-brief-panel.tsx`
- `components/qa-coverage-map.tsx`
- `components/features/runtime-inspector/RuntimeInspectorPanel.tsx`
- deep checkpoint comparison and timeline UI currently hosted inside `DetailPanel`

An implementation agent should avoid re-importing these as first-class sections on `/` unless the spec is amended.

### 6.5 Root Route Component Mapping

The intended end-state mapping is:

| Current Root Usage                                                                                                                  | End-State                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `page.tsx` orchestrates nearly all dashboard concerns directly                                                                      | `page.tsx` becomes a thin route composer using command-center components                          |
| `SummaryBar` is the first scan surface                                                                                              | `AttentionStrip` is first; `SummaryBar` becomes secondary or partially absorbed                   |
| `FilterBar` exposes raw internal filter taxonomy                                                                                    | `TaskFilterBar` exposes task-first filters with advanced disclosure                               |
| `DetailPanel` provides deep review in `/`                                                                                           | `TriageDrawer` provides lightweight preview in `/`; deep review moves to Focus                    |
| `CollisionQueue`, `LockResourceMap`, `DependencyChains`, `LiveEventFeed`, `QuickLaunchPanel` all compete in the same primary region | these move into `PrioritizedQueues` and/or `SecondaryDiagnosticsRail` with clearer priority rules |
| `Merged` is a full board column                                                                                                     | `MergedArchive` or equivalent demoted archive experience                                          |

### 6.6 Implementation Rule

Track A should not be considered complete until:

- the new root command-center components exist
- the old root-route dependency on `DetailPanel` is removed
- the component ownership of primary triage responsibilities is explicit in code, not only in page-level JSX

---

## 7. Configuration Contracts

### 7.1 `policy.yaml` Dashboard Section Expansion

The dashboard policy surface should expand beyond `enabled`, `port`, and `quick_launch`.

Recommended shape:

```yaml
dashboard:
  enabled: true
  port: 3000
  quick_launch: false
  default_view: board
  modules:
    run_health: true
    locks: true
    dependencies: true
    collision_queue: true
    live_feed: false
  attention_thresholds:
    stale_feature_minutes: 20
    blocked_age_minutes: 15
    waiting_input_age_minutes: 10
    run_heartbeat_degraded_seconds: 30
    run_heartbeat_critical_seconds: 120
  usage_display:
    primary_metric: tokens
    token_cost_conversion:
      usd_per_1k_tokens: 0.35
  redaction:
    hide_raw_logs: true
    hide_raw_evidence: true
    hide_provider_details: false
    hide_file_paths: false
  actions:
    approve: true
    deny: true
    request_changes: true
    retry: true
    send_message: true
    quick_launch: false
```

### 7.2 Budget Configuration Evolution

Budget policy should align with token-first usage:

```yaml
budget:
  per_feature_limit_tokens: 250000
  alert_threshold: 0.8
  token_cost_conversion:
    usd_per_1k_tokens: 0.35
```

Rules:

- `per_feature_limit_tokens` is the primary threshold for dashboard usage states.
- `token_cost_conversion` is optional.
- If conversion is absent, derived USD must be omitted.
- Existing USD-only budget settings may be preserved temporarily for backward compatibility, but the root dashboard must prefer token limits when both exist.

### 7.3 Multi-Project Config Metadata

`multi-project.yaml` should support richer UI metadata:

```yaml
defaults:
  default_project: aequitas-prod
projects:
  - name: aequitas-prod
    label: Aequitas Production
    environment: production
    owner: Platform
    sort_order: 10
    pinned: true
    hidden: false
    path: ~/workspace/Aequitas/projects/AequitasWebUI
```

These fields are for presentation and triage quality, not orchestration logic.

---

## 8. Risks, Side Effects, and Tradeoffs

### 8.1 Side Effects to Address

- A lighter root drawer means some existing power-user workflows move out of `/`.
- Task-first filters require stronger derived server-side semantics; weak derivation will create misleading triage states.
- Token-first usage may confuse users accustomed to dollar-only reporting unless copy is explicit.
- Redaction and authorization layers can make internal debugging slower if they are too coarse or too aggressive.
- Demoting merged work improves triage but may reduce visibility for audit-oriented users unless search/archive affordances stay strong.

### 8.2 Tradeoffs to Call Out Explicitly

- **Breadth vs clarity:** the command center becomes less of an everything-console and more of a decision surface.
- **Derived labels vs raw transparency:** client-facing statuses are more usable but require disciplined mapping from raw orchestrator state.
- **Safety vs speed:** stronger action governance adds implementation work and may reduce “frictionless” internal use.
- **Consistency vs flexibility:** a more opinionated module hierarchy will improve UX but reduce ad hoc layout freedom.

---

## 9. Acceptance Criteria

M47 is accepted when all are true:

1. `/` clearly answers what needs attention now without requiring drawer open or board-wide scanning.
2. The root dashboard no longer functions as a full deep-review workspace; Focus view is the intentional escalation path.
3. Task-first filters exist and are more prominent than raw phase/activity filters.
4. Root usage displays are token-first, with optional derived USD only when configured.
5. Mutating dashboard actions have explicit enabled/authorized/reason semantics, not quick-launch-only governance.
6. Multi-project switching supports client-facing metadata rather than only raw project names and paths.
7. Mobile triage no longer relies on a long below-the-board detail panel workflow.
8. The redesign uses the shared Aequitas-aligned light visual system and does not regress back to the dark ops-console style.

---

## 10. Implementation Sequence

This section is normative for agent execution. An implementation agent should treat these slices as the default rollout order unless a user explicitly requests a different sequence.

### 10.1 Delivery Strategy

Implementation should proceed in small, testable slices with visible product checkpoints:

1. establish root-dashboard architecture changes without changing governance
2. migrate `/` to token-first, triage-first UI
3. shrink root-route detail loading and move deep workflows behind Focus navigation
4. add governance/configuration contracts
5. add higher-order insight features only after the core command-center flow is stable

The implementation should avoid a single giant rewrite of `src/app/page.tsx`. Extract composition first, then replace behavior incrementally.

### 10.2 Target Files and Ownership

The likely primary implementation surface is:

- `packages/web-dashboard/src/app/page.tsx`
- `packages/web-dashboard/src/styles/dashboard.module.css`
- `packages/web-dashboard/src/lib/dashboard-utils.ts`
- `packages/web-dashboard/src/lib/types.ts`
- `packages/web-dashboard/src/components/summary-bar.tsx`
- `packages/web-dashboard/src/components/filter-bar.tsx`
- `packages/web-dashboard/src/components/feature-card.tsx`
- `packages/web-dashboard/src/components/kanban-board.tsx`
- `packages/web-dashboard/src/components/feature-list-view.tsx`
- `packages/web-dashboard/src/components/detail-panel.tsx`

New components are expected. Recommended additions:

- `packages/web-dashboard/src/components/dashboard/command-center-header.tsx`
- `packages/web-dashboard/src/components/dashboard/attention-strip.tsx`
- `packages/web-dashboard/src/components/dashboard/task-filter-bar.tsx`
- `packages/web-dashboard/src/components/dashboard/prioritized-queues.tsx`
- `packages/web-dashboard/src/components/dashboard/triage-drawer.tsx`
- `packages/web-dashboard/src/components/dashboard/merged-archive.tsx`
- `packages/web-dashboard/src/components/dashboard/secondary-diagnostics-rail.tsx`

Potential new or expanded server surfaces:

- `packages/web-dashboard/src/app/api/status/route.ts`
- `packages/web-dashboard/src/app/api/policy/budget/route.ts`
- `packages/web-dashboard/src/app/api/projects/route.ts`
- optional new drawer-focused route if a reduced payload is introduced

Potential orchestrator/config surfaces:

- `agentic/orchestrator/defaults/policy.defaults.yaml`
- `agentic/orchestrator/policy.yaml`
- `agentic/orchestrator/schemas/policy.schema.json`
- `agentic/orchestrator/schemas/policy.user.schema.json`
- `packages/web-dashboard/src/lib/multi-project-config.ts`

### 10.3 Track A - Command Center Core

#### Slice A1 - Component Extraction and Layout Skeleton

**Goal:** make the root dashboard composable before changing behavior.

**Required work:**

- Extract current header, summary, filters, board/list switcher, and root selection panel orchestration out of monolithic `page.tsx`.
- Introduce a dedicated root layout structure for:
  - header
  - attention area
  - filter area
  - main triage area
  - secondary diagnostics rail
- Preserve current functionality during extraction.

**Implementation notes:**

- Do not change API contracts in this slice.
- Do not remove current detail functionality yet; only isolate it behind a wrapper.
- Keep route/query synchronization behavior intact.

**Verification gate:**

- `/` still renders board and list modes correctly.
- selected feature sync in URL still works.
- keyboard navigation still works.

#### Slice A2 - Attention Strip and Task-First Filter Model

**Goal:** change the top-of-page decision model from aggregate-first to task-first.

**Required work:**

- Add a new attention-strip component above the existing summary area.
- Add task-first presets:
  - `Needs Me`
  - `At Risk`
  - `Ready`
  - `Stalled`
  - `Waiting On Dependencies`
  - `Waiting On CI`
  - `Recently Changed`
- Move raw phase/activity filtering under an advanced disclosure section.
- Extend filter state typing and URL serialization in `dashboard-utils.ts`.

**Implementation notes:**

- Reuse current summary counts where possible, but add derived selectors for new task filters.
- Derived filters must be deterministic and documented inline in utility code.
- Do not remove legacy quick filters until the new task filters are wired and tested.

**Verification gate:**

- URL round-trip preserves task filters.
- task filters produce stable filtered sets in both board and list view.
- empty-state messaging remains clear when filters reduce a column to zero features.

#### Slice A3 - Richer Board Cards and Merged Demotion

**Goal:** improve scanability without opening the drawer.

**Required work:**

- Add client-facing substate labels and richer status affordances to `FeatureCard`.
- Add usage/budget indicators to cards when data is available.
- Demote merged work out of the primary active board layout.
- Ensure list view reflects the same information hierarchy, not just board view.

**Implementation notes:**

- Avoid adding heavy per-card fetches.
- Prefer deriving card-level fields from the status payload.
- If the payload lacks necessary data, expand the status payload instead of fetching per card.

**Verification gate:**

- Board is still readable at mobile breakpoints.
- merged items remain discoverable.
- no new nested hover-only information is required to understand card state.

#### Slice A4 - Triage Drawer Replacement

**Goal:** replace the current heavy root detail panel with a lightweight triage drawer.

**Required work:**

- Introduce `TriageDrawer` as a distinct component from the current `DetailPanel`.
- Restrict root-route drawer content to:
  - overview
  - why attention
  - blockers/dependencies
  - compact PR/review snapshot
  - compact usage snapshot
  - valid next actions
  - Focus CTA
- Remove deep-review-first sections from `/`:
  - full diff
  - full evidence body viewers
  - checkpoint comparison
  - deep runtime investigation
  - full history/log sections

**Implementation notes:**

- It is acceptable to temporarily wrap or reuse small portions of `DetailPanel`, but the end state should not import the full deep-review stack into `/`.
- If a reduced drawer payload route is introduced, implement it here.
- The drawer should open quickly and should not trigger the full current feature detail fetch fanout.

**Verification gate:**

- feature selection latency on `/` is materially lower than current full detail load behavior.
- the user can still navigate to Focus view for deep review in one click.
- mobile no longer relies on a long below-the-board detail workflow.

#### Slice A5 - Token-First Usage on Root Dashboard

**Goal:** align `/` with token-first usage reporting.

**Required work:**

- Replace `Cost Today` presentation with token-first `Usage Today` wording.
- Expand root metrics and card/drawer display to use tokens as primary usage/budget measure.
- Support optional derived USD only when configured.
- Update any root-route budget messaging and copy accordingly.

**Implementation notes:**

- This may require parallel changes to status payload and policy budget route contracts.
- Preserve backward compatibility where possible, but the UI contract should become token-first immediately.

**Verification gate:**

- when token conversion is absent, no USD appears on `/`
- when conversion is present, USD renders only as secondary context
- budget states are driven by token thresholds, not USD thresholds, when both exist

### 10.4 Track B - Governance + Configuration

#### Slice B1 - Policy Schema and Defaults Expansion

**Goal:** create a first-class dashboard configuration model.

**Required work:**

- Expand `policy.schema.json` and `policy.user.schema.json` to include:
  - `default_view`
  - `modules`
  - `attention_thresholds`
  - `usage_display`
  - `redaction`
  - `actions`
- Update defaults in `policy.defaults.yaml`.
- Ensure lean-policy behavior remains sane when fields are omitted.

**Implementation notes:**

- Backward compatibility matters here.
- Omitted configuration must continue to produce a usable dashboard.
- Defaults should remain safe, not maximally permissive.

**Verification gate:**

- schema validation passes
- default policy boot still works
- omitted fields produce stable defaults

#### Slice B2 - Budget Contract Evolution

**Goal:** move budget APIs and UI contracts from USD-first to token-first.

**Required work:**

- Expand `/api/policy/budget` to return token-first fields.
- Support optional token-to-USD conversion.
- Update root and Focus consumers to handle mixed old/new config safely.

**Verification gate:**

- token-first config works
- legacy USD-only config still degrades gracefully
- no root-route component assumes USD is always present

#### Slice B3 - Action Governance Hardening

**Goal:** enforce consistent authorization and action-state semantics.

**Required work:**

- Introduce explicit action governance for:
  - approve
  - deny
  - request changes
  - retry
  - send message
  - quick launch
- Apply authz checks consistently, not only to quick launch.
- Expose enablement/authorization/reason state to the UI.

**Implementation notes:**

- The current allow-all adapter is acceptable as a fallback implementation, but the contract must no longer assume “all actions allowed” as the only behavior.
- Avoid silent failures; disabled states must be explainable.

**Verification gate:**

- unauthorized actions are blocked server-side
- UI reflects disabled/unauthorized states without broken buttons or hidden surprises

#### Slice B4 - Multi-Project Metadata Productization

**Goal:** make project switching usable for clients and non-authors.

**Required work:**

- Extend `multi-project-config.ts` parsing for display metadata.
- Update `/api/projects` to expose UI-safe metadata.
- Update the root project switcher/header to use labels/environment/owner where configured.

**Verification gate:**

- existing simple configs still parse
- richer configs render correctly
- root UI no longer relies on raw filesystem-oriented project presentation

#### Slice B5 - Redaction-Safe Client Mode

**Goal:** support safer external-facing dashboard usage.

**Required work:**

- Add config-driven redaction behavior for sensitive dashboard surfaces.
- Apply redaction to root dashboard presentation first.
- Ensure hidden content produces explanatory, non-broken UI states.

**Verification gate:**

- redacted mode hides configured sensitive fields
- non-redacted mode preserves internal operator fidelity

### 10.5 Track C - Insight Layer

#### Slice C1 - Attention Ranking and Staleness Derivation

**Goal:** make attention cards and queues smarter and more trustworthy.

**Required work:**

- Add deterministic attention ranking logic to shared dashboard utilities or server derivation.
- Derive:
  - stalled features
  - aging blocked items
  - aging waiting-input items
  - newly risky items

**Verification gate:**

- ranking order is stable
- severity labels map to documented thresholds

#### Slice C2 - “Since You Last Looked” Markers

**Goal:** reduce rescanning cost for repeat users.

**Required work:**

- choose and document one persistence model:
  - local browser persisted timestamp/cursor
  - server cursor
- add visual markers for newly changed risky states

**Verification gate:**

- markers clear predictably
- markers do not flicker or falsely persist after refresh

#### Slice C3 - Queue and Portfolio Insight Refinement

**Goal:** improve workload understanding without clutter.

**Required work:**

- refine prioritized work queues
- add compact trend or workload signals only if they materially improve triage
- keep analytics-grade charts out of `/`

**Verification gate:**

- root dashboard remains triage-first
- insight widgets do not displace attention and queue surfaces above the fold

### 10.6 Migration and Rollout Rules

- Do not delete the current root detail behavior until `TriageDrawer` reaches feature parity for the reduced root-route job.
- Prefer additive rollout behind local component boundaries rather than a flag day rewrite.
- If a temporary compatibility layer is needed, keep it shallow and remove it before closing Track A.
- Track B and C must be layered onto the new root hierarchy, not built against the pre-redesign structure.

### 10.7 Required Verification Per Track

For each completed slice, the implementing agent should run at least:

- `npm run typecheck`
- `npm run lint`
- targeted tests for touched dashboard logic/components

Before declaring Track A complete, the implementing agent should also verify:

- root route still supports URL-synced selection and filters
- board and list view both work
- mobile triage is usable
- Focus navigation remains intact

Before declaring Track B complete:

- schema/default/config parsing tests pass
- action governance behaviors are covered

Before declaring Track C complete:

- change-detection and attention derivation tests pass
- root information hierarchy remains intact

---

## 11. Open Questions

None for this revision.
