agentic-orchestrator 0.1.28 → 0.2.0

package/spec-files/completed/agentic_orchestrator_feature_focus_view_track_a_spec.md

@@ -0,0 +1,672 @@
+# Feature Spec: Feature Focus View UX Redesign — Track A: Core Focus View Redesign
+
+> Purpose: Redesign the `/feature/{feature_id}` page to make live feature development status immediately scannable, drill-down accessible, and phase-aware — replacing the current single-column scroll with a structured two-pane, tabbed layout.
+
+**Version:** 1.3
+**Date:** 2026-03-14
+**Status:** Outstanding
+**Roadmap Mapping:** M46-A (Focus View Core Redesign)
+**Depends On:** M45 (dashboard advanced UX, complete)
+**Track B Spec:** `spec-files/outstanding/agentic_orchestrator_feature_focus_view_track_b_spec.md`
+
+---
+
+## 0. Problem Statement
+
+The current feature focus view (`/feature/{feature_id}`) has the following structural deficiencies:
+
+| Problem                                         | Root Cause                                                                    | Impact                                                                       |
+| ----------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Single long vertical scroll                     | All sections stacked in one `<aside>` without layout separation               | Users cannot scan at a glance — must scroll to understand state              |
+| Diff viewer embedded in same column as metadata | `DiffViewer` rendered inside the narrow `detailPanel` column                  | Wide diffs are squeezed; side-by-side diffs unusable                         |
+| No visual hierarchy between sections            | Every section is equal weight (same `.section` class)                         | Users cannot tell what is urgent vs. informational                           |
+| Phase-agnostic layout                           | Layout does not change based on current phase                                 | A `building` view and `ready_to_merge` view look identical in structure      |
+| Review actions buried at the bottom             | `stickyReviewFooter` only sticky within the panel scroll                      | For long-diff features, reviewer must scroll past diff to reach approve/deny |
+| Metadata repetition                             | Feature ID, phase, status appear in header AND panel header                   | Cognitive redundancy, wasted vertical space                                  |
+| `DetailPanel` component is 1130+ lines          | All rendering logic collapsed into one component                              | Difficult to maintain, test, and extend                                      |
+| No "what is happening right now" signal         | Activity state, current agent role, time-in-phase all buried in metadata list | Operators cannot triage at a glance                                          |
+
+---
+
+## 1. Design Goals
+
+### 1.1 Primary Jobs
+
+This redesign optimizes for three ordered jobs:
+
+1. **Operator job:** Understand the current state of a feature run in under 5 seconds without scrolling.
+2. **Reviewer job:** Make an approve/deny/request-changes decision with full context visible, without hunting for the action buttons.
+3. **Diagnostics job:** Drill down into plan, diff, gates, QA, runtime, and history in focused dedicated panels — not a scroll maze.
+
+### 1.2 UX Principles
+
+1. **Status first:** The hero block answers "what is this, what phase is it in, is it healthy?" before any detail is visible.
+2. **Phase-aware defaults:** The active tab defaults to the most relevant content for the current phase (e.g., Gates for `blocked`, Changes for `building`, Review for `ready_to_merge`).
+3. **Actions always reachable:** Review actions (approve / deny / request changes) are pinned — never buried below content.
+4. **Progressive disclosure:** Deep diagnostics (runtime inspector, history log, checkpoint comparison) are accessible but not in the primary viewport.
+5. **Content width matches content type:** Diffs, plan trees, and QA maps get the full viewport width. Metadata and actions stay in a fixed sidebar.
+
+### 1.3 Non-Goals
+
+- Redesigning the Board view (`/`) — out of scope (except the Merge Queue card, which surfaces queue position on the focus view only).
+- Changing any existing backend API response shape (additive new endpoints are in scope for Track B features, and additive metadata is allowed when required for Track A lazy-loading or tab visibility).
+- Implementing drag-and-drop or resizable panes.
+
+### 1.4 Visual System Contract
+
+The focus view must align with the current Aequitas-inspired dashboard styling already established in `packages/web-dashboard/src/app/globals.css` and `packages/web-dashboard/src/styles/dashboard.module.css`.
+
+- Use the shared light-surface visual system: white and light-blue panels, slate text, soft borders, and the existing page background gradient.
+- Use the existing semantic palette: teal as the primary brand/action color, gold/orange for emphasis and warnings, red for destructive or blocked states.
+- Do not reintroduce the older dark "ops console" palette for new focus-view components unless a specific embedded tool requires it.
+- Embedded tooling must visually match the page: Monaco diff/editor instances use the light theme; diff containers and overlays use the shared surface tokens.
+- New focus-view CSS must consume shared dashboard tokens rather than defining page-local colors.
+
+### 1.5 Delivery Tracks
+
+This spec covers **Track A: Core Focus View Redesign** only.
+
+**Track A (this spec):**
+
+- Two-pane layout, hero block, diagnosis panel, tabbed content, pinned actions
+- Review/runtime/history/transcript capability preservation from the current `review-workspace.tsx`
+- Lazy-load cleanup, responsive behavior, accessibility, and decomposition of `detail-panel.tsx`
+
+**Track B** (see `spec-files/outstanding/agentic_orchestrator_feature_focus_view_track_b_spec.md`):
+
+- Transcript polish, code evolution scrubber, collision radar, token-usage burn analytics, genealogy, merge queue, role performance, flakiness summaries, annotations, and command palette
+- New additive API endpoints required by those advanced features
+
+Track A is the required deliverable for M46-A. Track B is a follow-on deliverable for M46-B.
+
+---
+
+## 2. Layout Architecture
+
+### 2.1 Top-Level Structure
+
+The page uses a **two-zone layout**:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  FOCUS HEADER  (back nav, feature ID, breadcrumb)               │
+├──────────────┬──────────────────────────────────────────────────┤
+│              │  TAB BAR                                         │
+│  CONTEXT     │──────────────────────────────────────────────────┤
+│  SIDEBAR     │                                                  │
+│  (fixed      │  TAB CONTENT PANEL                               │
+│   width,     │  (scrollable, full remaining width)              │
+│   scrollable)│                                                  │
+│              │                                                  │
+│  ─────────── │                                                  │
+│  REVIEW      │                                                  │
+│  ACTIONS     │                                                  │
+│  (pinned     │                                                  │
+│   bottom)    │                                                  │
+└──────────────┴──────────────────────────────────────────────────┘
+```
+
+**Context Sidebar** — 280px fixed width, `position: sticky`, full viewport height. Contains:
+
+- Hero status block
+- Agent pipeline stepper
+- Phase metadata (branch, time-in-phase, activity state)
+- Usage panel (collapsed by default)
+- Unresolved dependencies list (if any)
+- PR status card (if PR exists)
+- Review actions (pinned to sidebar bottom for `ready_to_merge`, `building`, `qa` phases)
+
+The sidebar is priority-ordered. The first viewport must fit, in order: hero block, diagnosis panel (if present), pinned actions or human input, and pipeline stepper. Lower-priority content such as usage, dependencies, and PR status may collapse behind summaries if vertical space is constrained.
+
+**Tab Content Panel** — fills remaining width. Contains all deep-detail sections behind tabs.
+
+### 2.2 Hero Status Block
+
+The top of the sidebar shows a compact, always-visible hero block:
+
+```
+┌────────────────────────────┐
+│  feature-id-slug           │  ← feature_id (truncated with tooltip)
+│  ● BUILDING  [active]      │  ← phase badge + activity_state badge
+│  In phase: 4m 32s          │  ← time-in-phase, live updating
+│  Builder running           │  ← current active role (if deterministic)
+│  Branch: feat/my-feature   │  ← branch name
+└────────────────────────────┘
+```
+
+- Phase badge uses the existing phase color variables (`--color-building`, etc.)
+- Activity state badge (`active`, `waiting_input`, `blocked`, `idle`) uses existing badge classes
+- Time-in-phase updates every 30 seconds (not every second — avoids unnecessary re-renders)
+- "Live activity" pulse indicator (`.inlinePulse`) shown when `activity_state === 'active'`
+- If `phase === 'blocked'`, the hero block renders in `--color-blocked` accent and shows `status_reason` inline
+
+### 2.3 Tab Definitions
+
+| Tab Key      | Label      | Icon | Visible When             | Default For Phases |
+| ------------ | ---------- | ---- | ------------------------ | ------------------ |
+| `overview`   | Overview   | `◎`  | Always                   | `planning`         |
+| `plan`       | Plan       | `📋` | `plan !== null`          | —                  |
+| `changes`    | Changes    | `⌥`  | `shouldShowDiff`         | `building`         |
+| `gates`      | Gates & QA | `✓`  | `shouldShowGates`        | `qa`, `blocked`    |
+| `review`     | Review     | `◈`  | `ready_to_merge`, `qa`   | `ready_to_merge`   |
+| `runtime`    | Runtime    | `⚡` | Always                   | —                  |
+| `history`    | History    | `↺`  | Always                   | `merged`           |
+| `transcript` | Transcript | `💬` | `log_entries.length > 0` | —                  |
+
+Tab visibility is computed from the same conditions already used in `DetailPanel` (`shouldShowPlan`, `shouldShowDiff`, `shouldShowGates`). No new logic is required.
+
+The active tab at page load is determined by the feature's current phase (see "Default For Phases" column). If a phase maps to no tab (e.g., `paused_budget`), fall back to `overview`.
+
+---
+
+## 3. Tab Content Specifications
+
+### 3.1 Overview Tab
+
+Replaces the current fragmented metadata sections. Consolidates into scannable cards:
+
+**Sections (stacked, no scroll needed for most features):**
+
+1. **Verification Signals** — `VerificationSignals` component, unchanged.
+2. **Plan Revision Timeline** — `PlanRevisionTimeline`, collapsed by default if no revisions.
+3. **Risk Annotations** — `PlanRiskAnnotations`, collapsed by default unless `ready_to_merge`.
+4. **Blocked State Banner** — visible only when `phase === 'blocked'`; shows `status_reason` and retry button inline.
+5. **Merged State Summary** — visible only when `phase === 'merged'`; shows PR link and merge commit.
+6. **Budget Banner** — visible only when `status === 'paused_budget'`.
+
+### 3.2 Plan Tab
+
+Dedicated full-width view:
+
+1. **Plan Scope Tree** — `PlanScopeTree` at full content width.
+2. **Plan Viewer** — `PlanViewer` below the tree.
+
+No other content competes for horizontal space. This is important because plan trees benefit from wide rendering.
+
+### 3.3 Changes Tab
+
+Dedicated full-width diff view:
+
+1. **DiffViewer** — `DiffViewer` rendered at full content panel width.
+2. No sidebar competition. Wide diffs render correctly.
+
+For `ready_to_merge` and `qa` phases, if the `ReviewWorkspace` is currently shown, the Changes tab hosts the Monaco diff editor component from `review-workspace.tsx` rather than the `diff2html` viewer. The tab-based layout replaces the current `showReviewWorkspace` boolean branch.
+
+### 3.4 Gates & QA Tab
+
+1. **Review Brief Panel** — `ReviewBriefPanel` at top (for `qa`, `ready_to_merge`).
+2. **Gate Results** — `GateResults`.
+3. **Gate Step Drilldown** — `GateStepDrilldown`.
+4. **QA Coverage Map** — `QaCoverageMap`.
+5. **Evidence Viewer** — `EvidenceViewer`.
+
+All components already exist. Tab simply groups them.
+
+### 3.5 Review Tab
+
+Visible only for `ready_to_merge` and `qa` phases. Consolidates the review actions form:
+
+1. **Review Brief Panel** (repeated from Gates & QA for convenient co-location with action form).
+2. **Review actions form** — review message textarea, approval token input, merge strategy select.
+3. **Action buttons** — Approve (green), Deny (red), Request Changes.
+
+This tab is the default for `ready_to_merge`. The review actions are no longer buried at the bottom of a long scroll.
+
+**Note:** The review actions are also pinned in the sidebar bottom for quick access without navigating to the Review tab. The sidebar version is a compact form (just the three action buttons); the full form with textarea/token/strategy is on the Review tab.
+
+The compact sidebar actions and the full Review tab form share one source of truth for `reviewMessage`, `approvalToken`, and `mergeStrategy`. Navigating between the compact actions and the full form must not reset draft state.
+
+### 3.6 Runtime Tab
+
+Replaces the runtime-oriented sections currently split across `DetailPanel` and `review-workspace.tsx`:
+
+1. **Execution Mode Badge** — deterministic or interactive pill.
+2. **Runtime Inspector Panel** — `RuntimeInspectorPanel` component (existing, unchanged).
+3. **Agent Session Status** — current role, per-role session IDs, active marker, copy affordances.
+4. **Directed Agent Console** — preserved from `review-workspace.tsx`; allows sending a message to the active runtime session when available.
+5. **Activity Timeline** — existing runtime/activity view and role/validity filtering preserved.
+6. **Checkpoints Section** — visible only when `showCheckpointTimeline`. Contains the tab-within-tab UI (Timeline / Snapshot Diff / Compare) from the current `DetailPanel`. This sub-navigation is preserved exactly.
+
+By moving to a dedicated tab, the checkpoint compare grid (which uses a two-column layout) can render at full content width rather than being crammed into the detail panel.
+
+### 3.7 History Tab
+
+1. **Log List** — lazy-loaded, same as current `<details>` section.
+2. **Raw Agent Output** — preserved from `review-workspace.tsx`, including policy-disabled states and file selection.
+3. Default for `merged` phase so merge summary is the first thing visible.
+
+### 3.8 Transcript Tab
+
+The transcript tab is part of Track A in its base form, because the current review workspace already exposes live role-tagged activity that would otherwise be lost in the redesign.
+
+1. **Role-grouped transcript view** — live or loaded entries grouped by consecutive role turns.
+2. **Follow / pause behavior** — preserve the current "Pause Follow / Resume Follow" interaction for actively streaming runs.
+3. **Actor and role identity** — preserve actor labels and timestamps.
+4. **Advanced markdown rendering, raw-log shortcuts, and enhanced syntax highlighting** are Track B polish, not Track A requirements.
+
+---
+
+## 4. Sidebar Review Actions (Pinned)
+
+For phases `ready_to_merge`, `building`, and `qa`, the sidebar renders a pinned action strip at its bottom:
+
+```
+┌────────────────────────────┐
+│  [Approve]  [Deny]  [⋯]   │  ← ready_to_merge
+└────────────────────────────┘
+
+┌────────────────────────────┐
+│  [Request Changes]         │  ← building / qa
+└────────────────────────────┘
+```
+
+- **`ready_to_merge`:** Three buttons: Approve (primary green), Deny (danger red), and an overflow menu (⋯) for Request Changes. Clicking Approve or Deny opens the existing `ConfirmationModal`.
+- **`building` / `qa`:** Single "Request Changes" button that opens the same modal.
+- Clicking any action button that requires the full form navigates to the Review tab and scrolls to the form.
+- For `waiting_input`, the pinned strip shows the `HumanInputPanel` widget instead.
+- For all other phases, the pinned strip is absent.
+
+This ensures the most important action is always one click away regardless of which tab is active.
+
+If an action requires inputs that are not currently satisfied in compact mode:
+
+- `Approve` without an approval token navigates to the Review tab and focuses the approval-token input.
+- `Deny` without a reason navigates to the Review tab and focuses the review-message textarea.
+- `Request Changes` may execute from compact mode using the shared draft state or a default message, but its behavior must be defined consistently across phases.
+
+---
+
+## 5. Health Diagnosis System
+
+A feature is not always simply "healthy" or "blocked." There is a spectrum: hard blocks, degraded runs, stalled activity, human-input waits, CI failures, and dependency blocks. The current page surfaces none of this proactively — `status_reason` is buried in the metadata list, gate failures require navigating to the Gates tab, and lock contention is invisible.
+
+This section specifies a client-side health diagnosis layer that derives a structured diagnosis from available `FeatureDetail` and `FeaturesIndex` data, and surfaces it in a `DiagnosisPanel` placed in the sidebar immediately below the hero block.
+
+### 5.1 Taxonomy of Unhealthy States
+
+| Severity   | Label    | Definition                                                                               |
+| ---------- | -------- | ---------------------------------------------------------------------------------------- |
+| `blocked`  | BLOCKED  | Hard stop — feature cannot progress without intervention                                 |
+| `degraded` | DEGRADED | Feature is running but has active failures or warnings that may prevent phase completion |
+| `stalled`  | STALLED  | Feature is not progressing; no recent activity detected                                  |
+| `waiting`  | WAITING  | Feature is paused pending human input (not an error, but requires action)                |
+| `healthy`  | —        | No diagnosis panel rendered                                                              |
+
+Severity is exclusive and priority-ordered. If multiple signals apply, the highest-severity wins for the `primary_cause`. All other signals are `secondary_causes`.
+
+### 5.2 Signal-to-Diagnosis Mapping
+
+The following signals from `FeatureSummary`, `GateRunEvidence`, `FeaturesIndex`, and `FeatureCheckpoint[]` drive the diagnosis:
+
+| Signal                                                                | Severity   | Cause Code               | Human Label                            | Suggested Action                                           | Links To                  |
+| --------------------------------------------------------------------- | ---------- | ------------------------ | -------------------------------------- | ---------------------------------------------------------- | ------------------------- |
+| `phase === 'blocked'`                                                 | `blocked`  | `PHASE_BLOCKED`          | "Feature is blocked"                   | Review the block reason below; use Retry or send a message | Overview tab              |
+| `activity_state === 'blocked'`                                        | `blocked`  | `ACTIVITY_BLOCKED`       | "Agent process blocked"                | Check runtime logs for deadlock or error                   | Runtime tab               |
+| `activity_state === 'exited'` AND phase not `merged`                  | `blocked`  | `AGENT_EXITED`           | "Agent exited unexpectedly"            | Review history for last known state; consider retry        | History tab               |
+| `status === 'paused_budget'`                                          | `blocked`  | `BUDGET_EXHAUSTED`       | "Token budget exhausted"               | Increase budget in policy or request manual continuation   | Overview tab              |
+| `FeaturesIndex.dep_blocked` contains this feature_id                  | `blocked`  | `DEPENDENCY_BLOCK`       | "Blocked on unresolved dependencies"   | List shown inline; navigate to dependent feature           | Overview tab              |
+| `gate_evidence.overall !== 'pass'`                                    | `degraded` | `GATE_FAILURE`           | "Gate checks failing"                  | Review failing steps below                                 | Gates & QA tab            |
+| `gate_retry_count >= 2`                                               | `degraded` | `REPEATED_GATE_FAILURES` | "Gates failing repeatedly (N retries)" | Check for flaky tests or systemic issue                    | Gates & QA tab            |
+| `pr.ci_status === 'failed'`                                           | `degraded` | `CI_FAILURE`             | "CI pipeline failing"                  | Review CI logs on PR                                       | Review tab                |
+| `pr.has_conflicts === true`                                           | `degraded` | `MERGE_CONFLICTS`        | "PR has merge conflicts"               | Manual conflict resolution required                        | Review tab                |
+| `pr.pending_review_threads > 0`                                       | `degraded` | `OPEN_REVIEW_THREADS`    | "N unresolved review threads"          | Address reviewer comments                                  | Review tab                |
+| `review_brief.unresolved_questions.length > 0`                        | `degraded` | `UNRESOLVED_QUESTIONS`   | "N open questions identified by QA"    | Review questions in Gates & QA                             | Gates & QA tab            |
+| `checkpoints` contains entries where `validation_status !== 'valid'`  | `degraded` | `CHECKPOINT_VIOLATIONS`  | "Checkpoint validation failures"       | Review violations in Runtime tab                           | Runtime tab               |
+| `activity_state === 'idle'` AND `activity_last_event_at` > 10 min ago | `stalled`  | `ACTIVITY_STALLED`       | "No activity detected for N minutes"   | Check if agent is still running; consider retry            | Runtime tab               |
+| `FeaturesIndex.lock_leases` has stale lease for this feature          | `stalled`  | `STALE_LOCK`             | "Stale lock detected"                  | Lock may be preventing progress; may auto-expire           | Overview tab              |
+| `activity_state === 'waiting_input'`                                  | `waiting`  | `WAITING_INPUT`          | "Waiting for human input"              | Respond to the agent prompt below                          | Sidebar (HumanInputPanel) |
+
+### 5.3 `deriveHealthDiagnosis()` Function
+
+A pure function, no side effects, no async. Lives in `lib/health-diagnosis.ts`.
+
+```typescript
+export type DiagnosisSeverity = 'blocked' | 'degraded' | 'stalled' | 'waiting' | 'healthy';
+
+export interface DiagnosisCause {
+  code: string;
+  label: string;
+  detail?: string; // e.g. status_reason text, retry count, dep list
+  link_tab?: TabKey; // tab to navigate to for details
+  action_hint?: string; // one-sentence suggested action
+}
+
+export interface HealthDiagnosis {
+  severity: DiagnosisSeverity;
+  primary: DiagnosisCause;
+  secondary: DiagnosisCause[];
+}
+
+export function deriveHealthDiagnosis(
+  feature: FeatureSummary,
+  gateEvidence: GateRunEvidence | null | undefined,
+  featuresIndex: FeaturesIndex | null,
+  checkpoints: FeatureCheckpoint[],
+): HealthDiagnosis | null; // returns null when healthy
+```
+
+**Evaluation order** (first match wins for `primary`):
+
+1. `BUDGET_EXHAUSTED` — `feature.status === 'paused_budget'`
+2. `PHASE_BLOCKED` — `feature.phase === 'blocked'`
+3. `AGENT_EXITED` — `feature.activity_state === 'exited'` AND phase not `merged`
+4. `ACTIVITY_BLOCKED` — `feature.activity_state === 'blocked'`
+5. `DEPENDENCY_BLOCK` — `featuresIndex.dep_blocked` contains this feature_id
+6. `GATE_FAILURE` — `gateEvidence?.overall` is not `'pass'` and not null
+7. `CI_FAILURE` — `feature.pr?.ci_status === 'failed'`
+8. `MERGE_CONFLICTS` — `feature.pr?.has_conflicts === true`
+9. `REPEATED_GATE_FAILURES` — `feature.gate_retry_count >= 2`
+10. `CHECKPOINT_VIOLATIONS` — any checkpoint has `validation_status !== 'valid'`
+11. `OPEN_REVIEW_THREADS` — `feature.pr?.pending_review_threads > 0`
+12. `UNRESOLVED_QUESTIONS` — checked only if `review_brief` is passed; treated as secondary unless it is the only signal
+13. `ACTIVITY_STALLED` — `activity_state === 'idle'` AND `activity_last_event_at` is > 10 minutes ago (configurable constant)
+14. `STALE_LOCK` — `featuresIndex.lock_leases` has entry for this feature with `stale: true`
+15. `WAITING_INPUT` — `feature.activity_state === 'waiting_input'`
+
+All matching signals below the first are collected as `secondary`. The function returns `null` (healthy) if no signals match.
+
+The 10-minute idle threshold is a named constant `STALL_THRESHOLD_MS = 10 * 60 * 1000` in the same file.
+
+### 5.4 `DiagnosisPanel` Component
+
+**Location in layout:** Sidebar, between `HeroBlock` and `AgentPipelineStepper`. Rendered only when `deriveHealthDiagnosis()` returns non-null.
+
+```
+┌────────────────────────────────────────┐
+│  ⛔ BLOCKED                             │  ← severity icon + label, phase-severity color
+│                                        │
+│  Feature is blocked                    │  ← primary.label
+│  "Planner rejected: schema mismatch    │  ← primary.detail (status_reason, truncated)
+│   in plan step 3"                      │     with expand toggle for long text
+│                                        │
+│  → See Overview                        │  ← link_tab navigation (tab switch, not href)
+│                                        │
+│  Also:                                 │  ← secondary causes (collapsed by default,
+│    · Gates failing (2 retries)         │     expandable with "Also: N more" toggle)
+│    · CI pipeline failing               │
+└────────────────────────────────────────┘
+```
+
+**Visual design:**
+
+- Border-left 3px in severity color (`--color-blocked` for blocked, `--color-building` orange for degraded, muted yellow for stalled, muted blue for waiting)
+- Background: subtle tint of severity color at 8% opacity
+- Icon: `⛔` blocked, `⚠` degraded, `⏸` stalled, `⏳` waiting
+- `primary.detail` is truncated at 120 characters with an inline expand toggle ("show more / show less")
+- `link_tab` renders as a small text link that calls `setActiveTab(link_tab)` — no page navigation
+- Secondary causes are collapsed by default behind a "Also: N more issues" toggle; expanded as a bullet list
+
+**Gate failure detail enrichment:**
+When `code === 'GATE_FAILURE'`, the panel additionally renders the first failing gate step inline:
+
+```
+Gates failing (1 of 3 steps failed)
+Step: "npm run test:coverage"
+  Last output: "Error: Coverage threshold not met…"  ← output_tail[last]
+  → See Gates & QA
+```
+
+This is the most critical diagnostic data for a blocked build — surfacing the actual error output from `GateStepResult.output_tail` in the sidebar means the operator does not have to navigate to the Gates tab just to see why the gate failed.
+
+**Dependency block detail:**
+When `code === 'DEPENDENCY_BLOCK'`, the panel lists the unresolved dependency feature IDs inline as links:
+
+```
+Blocked on unresolved dependencies:
+  · feat/auth-tokens  →  (link to /feature/feat/auth-tokens)
+  · feat/db-schema    →  (link to /feature/feat/db-schema)
+```
+
+### 5.5 Hero Block Integration
+
+When `diagnosis.severity` is not `healthy`, the hero block's phase badge gains a secondary indicator:
+
+```
+● BUILDING  ⚠          ← phase badge + severity icon inline
+```
+
+This is a single character addition to the existing badge — no layout change. The severity color applies to the warning icon, not the phase badge (phase badge color is always phase-based, not health-based, to preserve the existing color-coding convention).
+
+### 5.6 Data Availability and Lazy Loading
+
+`deriveHealthDiagnosis()` is called whenever `FeatureDetail` loads. It does not require any additional API calls beyond what is already fetched on page load. The `FeaturesIndex` data comes from the existing `/api/status` call. `GateRunEvidence` is part of `FeatureDetail.gate_evidence`.
+
+`review_brief.unresolved_questions` is a lazy-loaded field (fetched on Gates & QA tab activation). If not yet loaded, the `UNRESOLVED_QUESTIONS` signal is simply absent from the diagnosis — the panel re-evaluates when the field becomes available.
+
+The diagnosis panel must degrade gracefully when optional fields are unavailable. "Healthy" must never be inferred from missing lazy data; it means "no active signals from currently-available data."
+
+---
+
+## 6. Component Decomposition
+
+The current `detail-panel.tsx` (~1130 lines) must be split. The new Track A component structure:
+
+| New File                                  | Responsibility                                                                       | Approx. Lines |
+| ----------------------------------------- | ------------------------------------------------------------------------------------ | ------------- |
+| `components/focus/FocusLayout.tsx`        | Two-zone layout shell, tab state management                                          | ~120          |
+| `components/focus/FocusHeader.tsx`        | Back nav + feature ID breadcrumb                                                     | ~40           |
+| `components/focus/ContextSidebar.tsx`     | Hero block + pipeline stepper + metadata + pinned actions                            | ~220          |
+| `components/focus/HeroBlock.tsx`          | Feature ID, phase badge, activity state, time-in-phase                               | ~80           |
+| `components/focus/TabBar.tsx`             | Tab definitions, active tab, visibility logic                                        | ~90           |
+| `components/focus/tabs/OverviewTab.tsx`   | Verification signals, timeline, risk, blocked/merged banners                         | ~100          |
+| `components/focus/tabs/PlanTab.tsx`       | Scope tree + plan viewer                                                             | ~40           |
+| `components/focus/tabs/ChangesTab.tsx`    | DiffViewer or Monaco diff by phase                                                   | ~60           |
+| `components/focus/tabs/GatesQaTab.tsx`    | Review brief + gate results + coverage + evidence                                    | ~80           |
+| `components/focus/tabs/ReviewTab.tsx`     | Full review form + actions                                                           | ~120          |
+| `components/focus/tabs/RuntimeTab.tsx`    | Runtime inspector + session status + directed console + checkpoints section          | ~140          |
+| `components/focus/tabs/HistoryTab.tsx`    | Log list + raw provider output                                                       | ~90           |
+| `components/focus/PinnedActions.tsx`      | Phase-aware pinned action strip                                                      | ~100          |
+| `components/focus/DiagnosisPanel.tsx`     | Health diagnosis panel with primary/secondary causes and gate step detail            | ~150          |
+| `lib/health-diagnosis.ts`                 | `deriveHealthDiagnosis()` pure function + all types                                  | ~120          |
+| `components/focus/tabs/TranscriptTab.tsx` | Agent transcript preserving live role-tagged activity; advanced rendering is Track B | ~120          |
+
+Track B components (`CheckpointScrubber.tsx`, `CollisionRadar.tsx`, `UsageBurnChart.tsx`, `GenealogyTree.tsx`, `GateFlakinessSummary.tsx`, `AnnotatableDiffViewer.tsx`, `CommandPalette.tsx`, `AgentRolePerformanceCard.tsx`, `MergeQueueCard.tsx`, `lib/collision-radar.ts`, `lib/usage-burn.ts`) are specified in the Track B spec.
+
+The existing component files (`plan-viewer.tsx`, `diff-viewer.tsx`, `gate-results.tsx`, etc.) are **not changed** where practical — they are consumed by the new tab components. `detail-panel.tsx` is retired and replaced by `FocusLayout.tsx`.
+
+`review-workspace.tsx` is retired only after all of its operator-critical capabilities are preserved:
+
+- Monaco diff inspector
+- Review action form
+- Live agent log stream / transcript
+- Directed agent console
+- Session status panel
+- Runtime activity timeline filters
+- Raw provider output access
+- Mobile inspector flow
+
+The `showReviewWorkspace` boolean branch in `page.tsx` is eliminated only after feature parity is achieved.
+
+---
+
+## 7. Page Route Changes (`app/feature/[id]/page.tsx`)
+
+The page component currently renders either `<ReviewWorkspace>` or `<aside className={styles.detailPanel}>` based on a boolean. This branch is replaced:
+
+```tsx
+// Before (two separate rendering paths)
+{showReviewWorkspace ? <ReviewWorkspace ... /> : <aside><DetailPanel .../></aside>}
+
+// After (single path, phase-aware via tab defaults)
+<FocusLayout
+  detail={detail}
+  project={project}
+  statusPayload={payload}
+  hasActiveRuntimeSession={hasActiveRuntimeSession}
+/>
+```
+
+`FocusLayout` reads the phase and selects the correct default tab internally. No branching at the page level.
+
+---
+
+## 8. CSS Changes
+
+New CSS classes needed in `dashboard.module.css`:
+
+| Class                     | Purpose                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------ |
+| `.focusTwoPane`           | Two-zone grid layout: `grid-template-columns: 280px 1fr`                                   |
+| `.contextSidebar`         | Fixed-width sidebar: `position: sticky; top: 0; height: 100vh; overflow-y: auto`           |
+| `.heroBlock`              | Hero status container: padding, border-bottom                                              |
+| `.heroPhaseBadge`         | Large phase badge in hero: 0.85rem, phase color variable                                   |
+| `.heroFeatureId`          | Feature ID in hero: 1rem bold, truncation with tooltip                                     |
+| `.heroMeta`               | Secondary metadata lines in hero: 0.75rem muted                                            |
+| `.sidebarDivider`         | Horizontal rule between sidebar sections                                                   |
+| `.pinnedActions`          | Sticky bottom strip in sidebar: `position: sticky; bottom: 0; background: var(--bg-panel)` |
+| `.tabBar`                 | Horizontal tab row: flex, border-bottom                                                    |
+| `.tabItem`                | Individual tab button: 0.78rem, uppercase, padding                                         |
+| `.tabItemActive`          | Active tab: bottom border 2px phase-colored, primary text color                            |
+| `.tabContent`             | Tab content area: `overflow-y: auto; padding: 1rem 1.5rem`                                 |
+| `.diagnosisPanel`         | Diagnosis container: border-left 3px severity color, 8% tint background, padding           |
+| `.diagnosisSeverityLabel` | "BLOCKED / DEGRADED / STALLED / WAITING" label: 0.7rem uppercase, severity color           |
+| `.diagnosisPrimary`       | Primary cause text: 0.82rem, primary text color                                            |
+| `.diagnosisDetail`        | Detail/reason text: 0.78rem muted, truncated with expand toggle                            |
+| `.diagnosisLink`          | Tab-switch link: 0.75rem, underline, phase-accent color                                    |
+| `.diagnosisSecondary`     | Secondary causes list: 0.75rem muted, bullet list                                          |
+| `.diagnosisGateStep`      | Gate step failure inline block: monospace, 0.72rem, slightly indented                      |
+
+Responsive behavior:
+
+- At viewports < 900px: sidebar collapses to a horizontal strip above the tab bar (phase badge, activity state, and pinned actions only). Metadata moves into the Overview tab.
+- At viewports < 600px: sidebar strip becomes a single-line status bar. Tab bar becomes horizontally scrollable.
+
+Visual token requirements:
+
+- New focus-view classes must use the shared dashboard light-theme tokens already defined in `globals.css` and `dashboard.module.css`.
+- `--bg-panel`, `--bg-card`, `--bg-elevated`, `--text-primary`, `--text-muted`, `--border-weak`, `--border-strong`, and the phase color variables are the default inputs for new components.
+- Primary action buttons use the shared teal CTA treatment. Destructive actions use the shared red semantic styling. Warning/attention surfaces use the shared gold treatment.
+- New diagnosis and phase badges must pass contrast checks against light surfaces.
+- Monaco and diff containers must remain on the light theme to match the page.
+
+This section supersedes the earlier assumption that "existing CSS variables and component-level classes are unchanged." The visual system has already moved to the Aequitas-aligned light palette and the focus view must follow it.
+
+---
+
+## 9. Data Fetching
+
+No required backend contract changes for Track A beyond additive support where noted. The loading model is clarified to separate first-paint data from tab-lazy data.
+
+### 9.1 First-Paint vs Lazy-Load Contract
+
+**Required for first paint:**
+
+- `FeatureDetail`
+- `DashboardStatusPayload`
+- Phase/status/activity/role metadata needed for hero + diagnosis
+
+**Sidebar-lazy or expansion-lazy:**
+
+- Usage details and budget/conversion policy, unless usage is promoted into the hero summary
+- PR details beyond a compact summary
+
+**Tab-lazy:**
+
+- Review brief
+- QA test index
+- History log
+- Raw provider output
+- Checkpoint diff/compare payloads
+- Runtime event timeline details
+
+The focus view must not eagerly fetch every optional dataset on mount.
+
+Specifically:
+
+- `OverviewTab` triggers no additional fetches (all data available in `FeatureDetail`).
+- `GatesQaTab` triggers the `review-brief` fetch on first activation.
+- `HistoryTab` triggers the `log` fetch on first activation.
+- `RuntimeTab` triggers the runtime/activity fetch on first activation; SSE stream for checkpoints starts only when Runtime tab is active and `execution_mode === 'interactive'`.
+- `HistoryTab` and `TranscriptTab` may share a common underlying log source, but must not double-fetch it.
+- If transcript visibility requires a cheap presence signal, an additive `has_transcript` or equivalent metadata field may be introduced.
+
+This is a behavioral improvement over the current implementation where all lazy fetches fire simultaneously on mount.
+
+New endpoints required by Track B features are listed in the Track B spec (`§9.2 New API Endpoints`).
+
+---
+
+## 10. Accessibility Requirements
+
+- All tabs are keyboard navigable: arrow keys move between tabs, Enter activates.
+- Tab panels have `role="tabpanel"` and `aria-labelledby` pointing to the corresponding tab.
+- The pinned action strip buttons have descriptive `aria-label` attributes (e.g., `aria-label="Approve feature for merge"`).
+- Phase badges use `role="status"` and `aria-label="Phase: building"` (text, not color alone).
+- Hero time-in-phase uses `aria-live="polite"` for 30-second updates.
+- All interactive elements are reachable and operable with keyboard alone.
+- Sticky sidebars, sticky action regions, and mobile overlays must not create keyboard traps or hidden focus targets.
+- Long transcript/log content, diagnosis expanders, and command surfaces must preserve visible focus treatment in the light theme.
+
+---
+
+## 11. Risks, Side Effects, and Tradeoffs
+
+### 11.1 Known Side Effects To Manage
+
+- Tabs improve scanability but reduce "single-scroll discoverability." Default-tab selection and in-page cross-links matter more.
+- Lazy loading reduces first-paint cost but introduces first-open latency and asynchronous content pop-in.
+- A sticky sidebar plus sticky pinned actions plus mobile inspector overlays can create nested-scroll and viewport-height bugs on small screens.
+- Moving from the old dark ops-console look to the shared light Aequitas styling improves consistency but reduces some of the ambient severity/high-contrast feel of the previous interface.
+- Advanced transcript rendering increases trust and security risk if raw agent content is treated as safe HTML or safe Markdown without sanitization.
+
+### 11.2 Tradeoffs To Call Out Explicitly
+
+- Full replacement of `detail-panel.tsx` and `review-workspace.tsx` is cleaner architecturally, but higher risk than incremental extraction unless parity is tested aggressively.
+- "Existing components unchanged" is aspirational. Several existing panels were designed for the old narrow-column layout and may need adaptation once placed into full-width tabs.
+- A fixed 280px sidebar is simple, but information density must be managed with explicit collapse rules or the "5 second scan" goal will fail.
+- Track B features are valuable, but must not be allowed to delay Track A completion.
+
+---
+
+## 12. Success Criteria
+
+| Criterion                                                                              | How Verified                                                                                                                    |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Operator can determine phase, activity state, and current agent role without scrolling | Manual review of `building` phase screenshot at 1440px                                                                          |
+| Reviewer can reach Approve/Deny buttons without scrolling for any diff length          | Manual review with a 500-line diff feature at 1440px                                                                            |
+| Wide diff renders without horizontal scrollbar at > 900px viewport                     | Automated: render DiffViewer in ChangesTab with 120-char lines, assert no overflow                                              |
+| Default tab matches current phase                                                      | Unit test: `getDefaultTab(phase)` for all 7 phases                                                                              |
+| All existing components unchanged (no regressions)                                     | `npm run test` passes at ≥90% thresholds                                                                                        |
+| Lazy fetches fire on tab activation, not page mount                                    | Unit test: mock API calls, assert call counts per tab activation sequence                                                       |
+| Responsive: primary flow usable at 360px                                               | Manual check + Vitest snapshot at 360px breakpoint                                                                              |
+| `deriveHealthDiagnosis()` returns correct severity for all 15 signal types             | Unit tests: one test per signal, plus priority-ordering tests (higher severity wins)                                            |
+| `DiagnosisPanel` hidden when feature is healthy                                        | Unit test: render with healthy feature, assert panel absent from DOM                                                            |
+| `DiagnosisPanel` shows `output_tail` for GATE_FAILURE primary                          | Unit test: render with failed gate evidence, assert step name and last output line visible                                      |
+| `DiagnosisPanel` link_tab calls `setActiveTab`, not page navigation                    | Unit test: click "See Gates & QA", assert tab state updated, no `window.location` change                                        |
+| Secondary causes collapsed by default, expandable                                      | Unit test: render with 3 signals, assert secondary list hidden; click toggle, assert visible                                    |
+| Hero badge severity icon present when diagnosis non-null                               | Unit test: render blocked feature, assert warning icon in hero badge                                                            |
+| STALL_THRESHOLD_MS constant exported and used in diagnosis                             | Static: import check ensures threshold is not hardcoded inline                                                                  |
+| Focus view uses shared Aequitas light-theme tokens                                     | Visual regression / snapshot: no dark-panel fallback classes used in new focus components                                       |
+| Track A preserves current review workspace capabilities before retirement              | Regression tests cover live log stream, send-message flow, session status, raw output access, and mobile inspector availability |
+| Zero ESLint warnings                                                                   | `npm run lint`                                                                                                                  |
+| TypeScript strict mode passes                                                          | `npm run typecheck`                                                                                                             |
+
+---
+
+## 13. Migration Path
+
+1. Create `lib/health-diagnosis.ts` with `deriveHealthDiagnosis()` and all types. Write unit tests first.
+2. Create `components/focus/` directory with the Track A component files.
+3. Build `DiagnosisPanel` consuming `deriveHealthDiagnosis()`.
+4. Build `FocusLayout`, `ContextSidebar`, `HeroBlock`, `TabBar`, and the core tab components.
+5. Preserve current `review-workspace.tsx` capabilities inside the new tab model before deleting anything.
+6. Add new CSS classes to `dashboard.module.css` using the shared Aequitas-aligned tokens.
+7. Update `app/feature/[id]/page.tsx` to render `<FocusLayout>` instead of the current branch.
+8. Add unit tests for tab logic, pinned action rendering, capability preservation, and lazy fetch gating.
+9. Delete `detail-panel.tsx` and `review-workspace.tsx` only after parity tests pass.
+10. Run `npm run build`, `npm run test`, and visual checks at desktop/mobile breakpoints.
+
+Do **not** modify `detail-panel.tsx` incrementally. The decomposition is a full replacement. Incremental edits to a 1130-line component introduce more risk than a clean cut.
+
+Track B migration steps (implementing new API endpoints, building Track B components, wiring into tabs) are listed in the Track B spec.
+
+---
+
+## 14. Out of Scope
+
+- Animated tab transitions.
+- Persisting the user's active tab across navigation (could be added later via localStorage).
+- Redesigning the Board (`/`) view (Merge Queue card appears on focus view only).
+- Changes to the control-plane backend or MCP tool contracts — new endpoints are in the Next.js API layer only.
+- Real-time multi-user collaboration beyond presence indicators.
+- All Track B features: transcript polish, code evolution scrubber, collision radar, token-usage burn analytics, genealogy, merge queue, role performance, flakiness summaries, diff annotations, and command palette.