agentic-orchestrator 0.1.28 → 0.2.0

package/spec-files/completed/agentic_orchestrator_dashboard_command_center_redesign_spec.md

@@ -0,0 +1,1147 @@
+# 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.