diff --git a/docs/implplan/SPRINT_20260320_001_FE_releases_table_and_wizard.md b/docs-archived/implplan/SPRINT_20260320_001_FE_releases_table_and_wizard.md similarity index 100% rename from docs/implplan/SPRINT_20260320_001_FE_releases_table_and_wizard.md rename to docs-archived/implplan/SPRINT_20260320_001_FE_releases_table_and_wizard.md diff --git a/docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md b/docs-archived/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md similarity index 100% rename from docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md rename to docs-archived/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md diff --git a/docs/implplan/SPRINT_20260324_001_Platform_scripts_variables_validation_diff_compat.md b/docs-archived/implplan/SPRINT_20260324_001_Platform_scripts_variables_validation_diff_compat.md similarity index 100% rename from docs/implplan/SPRINT_20260324_001_Platform_scripts_variables_validation_diff_compat.md rename to docs-archived/implplan/SPRINT_20260324_001_Platform_scripts_variables_validation_diff_compat.md diff --git a/docs/implplan/SPRINT_20260328_003_ElkSharp_compound_sugiyama_support.md b/docs-archived/implplan/SPRINT_20260328_003_ElkSharp_compound_sugiyama_support.md similarity index 100% rename from docs/implplan/SPRINT_20260328_003_ElkSharp_compound_sugiyama_support.md rename to docs-archived/implplan/SPRINT_20260328_003_ElkSharp_compound_sugiyama_support.md diff --git a/docs-archived/implplan/SPRINT_20260329_006_FE_audit_menu_consolidation.md b/docs-archived/implplan/SPRINT_20260329_006_FE_audit_menu_consolidation.md new file mode 100644 index 000000000..381cd74ed --- /dev/null +++ b/docs-archived/implplan/SPRINT_20260329_006_FE_audit_menu_consolidation.md @@ -0,0 +1,120 @@ +# Sprint 006 - Audit Menu Consolidation (Hub-and-Spoke) + +## Topic & Scope +- Merge module-specific audit views from the unified audit dashboard into their parent feature pages as contextual tabs. +- Slim the unified audit dashboard from 9 tabs to 4 (Overview, All Events, Timeline, Correlations). +- Fill audit gaps: add audit tabs to 5 pages that lacked audit coverage (Platform Jobs, Scanner Ops, Trust Admin/Attestor, SBOM Sources). +- Create reusable `AuditModuleEventsComponent` for embedding audit event tables in feature pages. +- Working directory: `src/Web/StellaOps.Web/src/app/`. +- Expected evidence: Build passes, all 9 audit modules accessible from both contextual tabs and unified All Events. + +## Dependencies & Concurrency +- No upstream sprint dependencies. +- All Steps 1-5 can be executed in parallel. +- Steps 6-8 depend on Steps 1-5 completion. +- Steps 10-13 depend on Step 9. + +## Documentation Prerequisites +- `docs/implplan/` sprint file (this file). + +## Delivery Tracker + +### TASK-001 - Add Audit Trail tab to VEX Hub +Status: DONE +Owners: Developer +Completion criteria: +- [x] VEX Hub has 4th tab "Audit Trail" rendering AuditVexComponent +- [x] Cross-link to unified audit + +### TASK-002 - Add Audit tab to Trust Admin +Status: DONE +Owners: Developer (agent) +Completion criteria: +- [x] Trust Admin has 4th tab "Audit" with sub-views for Trust Events, Air-Gap, Incidents +- [x] Cross-link to unified audit + +### TASK-003 - Extend Policy Governance audit tab +Status: DONE +Owners: Developer (agent) +Completion criteria: +- [x] Policy Governance audit tab has sub-toggle: Governance Changes | Promotions & Approvals +- [x] AuditPolicyComponent embedded for promotions view + +### TASK-004 - Extend Console Admin audit tab +Status: DONE +Owners: Developer (agent) +Completion criteria: +- [x] Console Admin audit tab has sub-tabs: Management | Token Lifecycle & Security +- [x] AuditAuthorityComponent embedded for token view + +### TASK-005 - Add config audit to Integration Hub +Status: DONE +Owners: Developer (agent) +Completion criteria: +- [x] Integration detail page has "Config Audit" tab rendering AuditModuleEventsComponent (module=integrations) +Note: Hub-level tab was removed for usability; audit placed on per-integration detail page instead. Shell quick links cross-reference unified audit. + +### TASK-006 - Slim unified audit dashboard +Status: DONE +Owners: Developer +Completion criteria: +- [x] Dashboard has 4 tabs: Overview, All Events, Timeline, Correlations +- [x] Module-specific tabs removed + +### TASK-007 - Add backward-compatible redirects +Status: DONE +Owners: Developer +Completion criteria: +- [x] Old URLs (/evidence/audit-log/policy, etc.) redirect to new contextual locations + +### TASK-008 - Update sidebar navigation +Status: DONE +Owners: Developer +Completion criteria: +- [x] Audit Bundles removed from Findings group +- [x] Unified Audit Log renamed to Audit & Compliance with 3 sub-items + +### TASK-009 - Create reusable AuditModuleEventsComponent +Status: DONE +Owners: Developer +Completion criteria: +- [x] Shared component with @Input module/modules, table, filters, pagination, event detail + +### TASK-010 - Fill audit gaps (jobengine, scheduler, scanner, sbom) +Status: DONE +Owners: Developer (agent) +Completion criteria: +- [x] Platform Jobs has Audit tab (jobengine + scheduler) +- [x] Scanner Ops has Audit tab +- [x] SBOM Sources has collapsible audit section with AuditModuleEventsComponent + +### TASK-011 - Wire airgap/incident audit to real API +Status: DONE +Owners: Developer +Completion criteria: +- [x] AirgapAuditComponent wired to AuditLogClient.getAirgapAudit() with mock fallback +- [x] IncidentAuditComponent has apiConnected signal and degraded banner + +### TASK-012 - Add bidirectional cross-links +Status: DONE +Owners: Developer +Completion criteria: +- [x] Contextual tabs link to unified All Events +- [x] Unified All Events links to contextual module pages when single-module filter active + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-29 | Sprint created; implementation started. | Developer | +| 2026-03-29 | Tasks 1, 6-9, 11-12 completed. Tasks 2-5, 10 in progress (agents). | Developer | +| 2026-03-30 | Tasks 2-5, 10 completed. All 12 tasks DONE. Sprint ready to archive. | Developer | + +## Decisions & Risks +- Hub-and-Spoke model chosen: contextual audit tabs for DevOps workflow, unified for auditor/CISO. +- Data source differences documented: integrated and unified use different API clients with complementary data. +- AirgapAuditComponent falls back to mock data if API unavailable (degraded banner shown). +- IncidentAuditComponent shows degraded banner when Trust API incomplete. + +## Next Checkpoints +- Build verification after all agents complete. +- Manual verification of all 9 module audit access paths. diff --git a/docs-archived/implplan/SPRINT_20260329_007_FE_unified_stella_assistant.md b/docs-archived/implplan/SPRINT_20260329_007_FE_unified_stella_assistant.md new file mode 100644 index 000000000..4fdcf45f2 --- /dev/null +++ b/docs-archived/implplan/SPRINT_20260329_007_FE_unified_stella_assistant.md @@ -0,0 +1,644 @@ +# Sprint 007 — Unified Stella Assistant: Mascot + Search + AI Chat as One + +## Topic & Scope + +**Problem**: Three disconnected help surfaces exist in the UI: +1. Stella Helper (mascot) — static English-only tips, localStorage, no API +2. Global Search (Ctrl+K) — unified search with entity cards and synthesis +3. Advisory AI Chat (drawer) — SSE-streaming AI with citations and actions + +The user experiences these as separate tools. A new DevOps engineer has to discover each independently. The mascot has 189 tips but they're hardcoded in English, not connected to the search/AI knowledge, and can't be edited without a code deploy. + +**Goal**: Merge all three into a single **Unified Stella Assistant** where the mascot is the FACE of the system, the search is its MEMORY, and the AI chat is its VOICE. All content comes from the database, all text respects the user's locale, and the admin can author/update tips without deploying code. + +- Working directory: `src/Web/StellaOps.Web/src/app/` +- Backend working directory: `src/Platform/` (for API + DB schema) +- Expected evidence: unified component, DB schema, API endpoints, i18n integration + +## Dependencies & Concurrency +- Depends on: existing `I18nService`, `UnifiedSearchClient`, `ChatService`, `SearchChatContextService`, `SearchContextRegistry` +- Sprint 006 T0a (mascot core) provides the animation/UI foundation +- Safe to parallelize: DB schema, API endpoints, and frontend can be built in parallel + +## Documentation Prerequisites +- `docs/modules/platform/architecture-overview.md` — platform API patterns +- `src/Web/StellaOps.Web/src/app/core/i18n/i18n.service.ts` — i18n patterns +- `src/Web/StellaOps.Web/src/app/core/api/unified-search.client.ts` — search API +- `src/Web/StellaOps.Web/src/app/features/advisory-ai/chat/chat.service.ts` — chat API + +--- + +## Architecture: Target State + +``` +UNIFIED STELLA ASSISTANT + +┌──────────────────────────────────────────────────────────┐ +│ Stella Mascot (UI) │ +│ │ +│ ┌──────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ Tips Mode │ │ Search Mode │ │ Chat Mode │ │ +│ │ (default) │ │ (Ctrl+K) │ │ (follow-up) │ │ +│ │ │ │ │ │ │ │ +│ │ DB-backed │ │ Unified │ │ Advisory AI │ │ +│ │ i18n-aware│ │ Search API │ │ SSE streaming │ │ +│ │ contextual│ │ + synthesis │ │ + citations │ │ +│ └─────┬─────┘ └──────┬───────┘ └────────┬───────────┘ │ +│ │ │ │ │ +│ └───────────────┼────────────────────┘ │ +│ │ │ +│ ┌─────────▼──────────┐ │ +│ │ StellaAssistant │ │ +│ │ Service │ │ +│ │ │ │ +│ │ - mode signal │ │ +│ │ - context signal │ │ +│ │ - locale signal │ │ +│ │ - tips from API │ │ +│ │ - search bridge │ │ +│ │ - chat bridge │ │ +│ └─────────┬──────────┘ │ +│ │ │ +└────────────────────────┼────────────────────────────────────┘ + │ + ┌──────────▼──────────┐ + │ Backend APIs │ + │ │ + │ GET /api/v1/stella- │ + │ assistant/tips │ + │ ?route=X&locale=Y │ + │ │ + │ GET /api/v1/stella- │ + │ assistant/glossary │ + │ ?locale=Y │ + │ │ + │ POST /api/v1/ │ + │ unified-search │ + │ (existing) │ + │ │ + │ POST /api/v1/ │ + │ advisory-ai/ │ + │ conversations/ │ + │ (existing) │ + └─────────────────────┘ +``` + +### Mode Transitions + +``` +User lands on page + │ + ▼ +TIPS MODE (default) + │ Shows DB-backed, locale-aware contextual tips + │ Mascot with speech bubble (current UI) + │ + ├── User types in mascot bubble → SEARCH MODE + │ Mascot bubble becomes search input + │ Results appear inline (entity cards) + │ Same API as Ctrl+K (UnifiedSearchClient) + │ + ├── User clicks "Ask Stella" or asks a question → CHAT MODE + │ Mascot bubble expands to chat interface + │ Uses existing ChatService (Advisory AI) + │ SSE streaming with mascot animations + │ Citations, actions, grounding score + │ + ├── Ctrl+K → SEARCH MODE (focus mascot search input) + │ + └── User clicks mascot after dismissing → TIPS MODE (re-opens) + +SEARCH MODE + │ + ├── User clicks result → navigates, returns to TIPS MODE + ├── User clicks "Ask AI about this" → CHAT MODE with context + └── User clears search → TIPS MODE + +CHAT MODE + │ + ├── AI suggests a search → SEARCH MODE with query pre-filled + ├── User clicks citation link → navigates, stays in CHAT MODE + ├── AI streaming done → stays in CHAT MODE for follow-ups + └── User clicks "Back to tips" → TIPS MODE +``` + +### Key Design Decisions + +**D1: Mascot replaces global search bar as primary entry point** +The mascot bubble gets a search input field. Ctrl+K focuses this field instead of opening a separate dropdown. The separate `GlobalSearchComponent` dropdown becomes a fallback for users who prefer the old behavior. + +**D2: Chat is embedded in mascot, not a separate drawer** +The `SearchAssistantHostComponent` drawer is replaced by the mascot's expanded chat mode. The mascot bubble grows to accommodate the conversation. On mobile, it goes full-screen. + +**D3: Tips content moves to database** +The hardcoded `PAGE_TIPS` config becomes seed data. At runtime, tips are fetched from the backend API. This enables: +- Admin authoring without code deploy +- Per-locale translations +- A/B testing of tip content +- Analytics on which tips are helpful + +**D4: Mascot animates in sync with AI** +During chat mode: +- `progress: thinking` → mascot shows thinking animation +- `progress: searching` → mascot shows searching animation +- `token` events → mascot lip-syncs or nods +- `citation` events → mascot points/highlights +- `error` events → mascot shows concern +- `done` → mascot shows satisfied pose + +--- + +## Database Schema: `stella_assistant` + +### Table: `assistant_tips` +```sql +CREATE TABLE stella_assistant.tips ( + tip_id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + route_pattern TEXT NOT NULL, -- '/ops/policy/vex', '/ops/policy/vex/consensus' + context_trigger TEXT, -- 'sbom-missing', 'gate-blocked', NULL for generic + locale TEXT NOT NULL DEFAULT 'en-US', + sort_order INT NOT NULL DEFAULT 0, + title TEXT NOT NULL, + body TEXT NOT NULL, + action_label TEXT, -- 'Scan your first image' + action_route TEXT, -- '/security/scan' + learn_more_url TEXT, + is_active BOOLEAN NOT NULL DEFAULT TRUE, + product_version TEXT, -- '1.0', '1.1', NULL = all versions + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + created_by TEXT, + + UNIQUE (route_pattern, context_trigger, locale, sort_order) +); + +CREATE INDEX idx_tips_route_locale ON stella_assistant.tips (route_pattern, locale) WHERE is_active; +CREATE INDEX idx_tips_context ON stella_assistant.tips (context_trigger) WHERE context_trigger IS NOT NULL AND is_active; +``` + +### Table: `assistant_greetings` +```sql +CREATE TABLE stella_assistant.greetings ( + greeting_id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + route_pattern TEXT NOT NULL, + locale TEXT NOT NULL DEFAULT 'en-US', + greeting_text TEXT NOT NULL, + is_active BOOLEAN NOT NULL DEFAULT TRUE, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + UNIQUE (route_pattern, locale) +); +``` + +### Table: `assistant_glossary` +```sql +CREATE TABLE stella_assistant.glossary ( + term_id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + term TEXT NOT NULL, -- 'SBOM', 'VEX', 'Decision Capsule' + locale TEXT NOT NULL DEFAULT 'en-US', + definition TEXT NOT NULL, -- plain-English definition + extended_help TEXT, -- longer explanation + related_terms TEXT[], -- ['CVE', 'Advisory', 'Finding'] + related_routes TEXT[], -- ['/security/scan', '/security/supply-chain-data'] + is_active BOOLEAN NOT NULL DEFAULT TRUE, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + UNIQUE (term, locale) +); + +CREATE INDEX idx_glossary_locale ON stella_assistant.glossary (locale) WHERE is_active; +``` + +### Table: `assistant_tours` +```sql +CREATE TABLE stella_assistant.tours ( + tour_id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tour_key TEXT NOT NULL, -- 'first-setup', 'scan-workflow', 'promotion-101' + locale TEXT NOT NULL DEFAULT 'en-US', + title TEXT NOT NULL, + description TEXT NOT NULL, + steps JSONB NOT NULL, -- array of { stepOrder, route, selector?, title, body, action? } + is_active BOOLEAN NOT NULL DEFAULT TRUE, + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + UNIQUE (tour_key, locale) +); +``` + +### Table: `assistant_user_state` +```sql +CREATE TABLE stella_assistant.user_state ( + user_id TEXT NOT NULL, + tenant_id TEXT NOT NULL, + seen_routes TEXT[] NOT NULL DEFAULT '{}', + completed_tours TEXT[] NOT NULL DEFAULT '{}', + tip_positions JSONB NOT NULL DEFAULT '{}', -- { "/dashboard": 3, "/security": 1 } + dismissed BOOLEAN NOT NULL DEFAULT FALSE, + last_seen_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + PRIMARY KEY (user_id, tenant_id) +); +``` + +### Seed Data +The current 189 hardcoded tips + 101 greetings become seed SQL: +```sql +-- Generated from stella-helper-tips.config.ts +INSERT INTO stella_assistant.tips (route_pattern, locale, sort_order, title, body, action_label, action_route) +VALUES + ('/', 'en-US', 0, 'What is this dashboard?', 'This is your daily operations overview...', NULL, NULL), + ('/', 'en-US', 1, 'What does "SBOM: missing" mean?', 'SBOM stands for...', 'Scan your first image', '/security/scan'), + -- ... all 189 tips +; +``` + +Then translated rows for each locale: +```sql +INSERT INTO stella_assistant.tips (route_pattern, locale, sort_order, title, body, action_label, action_route) +VALUES + ('/', 'bg-BG', 0, 'Какво е това табло?', 'Това е вашият дневен оперативен преглед...', NULL, NULL), + ('/', 'de-DE', 0, 'Was ist dieses Dashboard?', 'Dies ist Ihre tägliche Betriebsübersicht...', NULL, NULL), + -- ... +; +``` + +--- + +## API Endpoints + +### GET `/api/v1/stella-assistant/tips` +Returns tips for the current route and locale. + +**Query params:** +- `route` (required): current URL path (e.g., `/ops/policy/vex/consensus`) +- `locale` (optional, default: user preference): `en-US`, `bg-BG`, etc. +- `contexts` (optional): comma-separated context triggers (e.g., `sbom-missing,feed-stale`) +- `version` (optional): product version filter + +**Response:** +```json +{ + "greeting": "Consensus shows how multiple VEX sources agree or disagree...", + "tips": [ + { + "tipId": "uuid", + "title": "How consensus works", + "body": "When multiple sources publish VEX statements...", + "action": { "label": "View trust weights", "route": "/ops/policy/governance/trust-weights" }, + "contextTrigger": null + } + ], + "contextTips": [ + { + "tipId": "uuid", + "title": "Your feeds are stale", + "body": "Advisory feeds haven't synced in 3 days...", + "contextTrigger": "feed-stale", + "action": { "label": "Check feeds", "route": "/ops/operations/feeds-airgap" } + } + ] +} +``` + +**Route matching**: Server-side longest-prefix match (same logic as frontend `resolvePageKey` but canonical). + +### GET `/api/v1/stella-assistant/glossary` +Returns domain terms for the current locale. + +**Query params:** +- `locale` (optional) +- `terms` (optional): comma-separated specific terms to look up + +**Response:** +```json +{ + "terms": [ + { + "term": "SBOM", + "definition": "Software Bill of Materials — a list of every component inside a container image.", + "extendedHelp": "SBOMs are generated when you scan...", + "relatedTerms": ["CVE", "Supply Chain", "Finding"], + "relatedRoutes": ["/security/scan", "/security/supply-chain-data"] + } + ] +} +``` + +### GET `/api/v1/stella-assistant/tours` +Returns available guided tours. + +**Query params:** +- `locale` (optional) +- `tourKey` (optional): specific tour to fetch + +### PUT `/api/v1/stella-assistant/user-state` +Persists user state (seen routes, completed tours, tip positions, dismissed). + +### GET `/api/v1/stella-assistant/user-state` +Retrieves user state. + +--- + +## Frontend Architecture: Unified Component + +### `StellaAssistantService` (replaces `StellaHelperContextService`) + +```typescript +@Injectable({ providedIn: 'root' }) +export class StellaAssistantService { + private readonly i18n = inject(I18nService); + private readonly searchClient = inject(UnifiedSearchClient); + private readonly chatService = inject(ChatService); + private readonly searchChatCtx = inject(SearchChatContextService); + private readonly drawerService = inject(SearchAssistantDrawerService); + private readonly http = inject(HttpClient); + + // ---- Mode ---- + readonly mode = signal<'tips' | 'search' | 'chat'>('tips'); + + // ---- Tips (from API) ---- + readonly tips = signal([]); + readonly greeting = signal(''); + readonly contextTips = signal([]); + readonly glossary = signal([]); + + // ---- Context ---- + readonly activeContexts = signal([]); + readonly currentRoute = signal('/'); + + // ---- Search ---- + readonly searchQuery = signal(''); + readonly searchResults = signal([]); + readonly searchSynthesis = signal(null); + + // ---- Chat ---- + readonly conversation = signal(null); + readonly isStreaming = signal(false); + readonly streamStage = signal(''); // thinking, searching, validating + + // ---- User state (from API) ---- + readonly userState = signal(DEFAULT_STATE); + + /** Fetch tips for current route and locale from backend */ + async loadTips(route: string): Promise { ... } + + /** Push context trigger (components call this) */ + pushContext(key: string): void { ... } + + /** Switch to search mode */ + enterSearch(query?: string): void { ... } + + /** Switch to chat mode with optional initial message */ + enterChat(message?: string): void { ... } + + /** Return to tips mode */ + exitToTips(): void { ... } + + /** Persist user state to backend */ + async saveUserState(): Promise { ... } + + /** Load glossary for current locale */ + async loadGlossary(): Promise { ... } +} +``` + +### `StellaAssistantComponent` (replaces `StellaHelperComponent`) + +The component renders differently based on `mode()`: + +**Tips Mode** (current mascot behavior): +- Speech bubble with tip title/body +- Tip navigation (prev/next) +- Small search input at bottom: "Ask Stella anything..." +- Typing in the input → switches to Search Mode + +**Search Mode** (replaces Ctrl+K dropdown): +- Search input focused +- Entity cards rendered below +- Synthesis panel +- "Ask AI about this" button on each card → Chat Mode + +**Chat Mode** (replaces drawer): +- Conversation messages with streaming +- Mascot animates during AI stages +- Citations with links +- Proposed actions (approve, quarantine, etc.) +- "Back to tips" link + +### Ctrl+K Integration + +```typescript +// In app-shell or topbar: +@HostListener('document:keydown.control.k', ['$event']) +onCtrlK(event: KeyboardEvent): void { + event.preventDefault(); + this.stellaAssistant.enterSearch(); + // Focus the mascot's search input instead of the old global search +} +``` + +### I18n Integration + +```typescript +// StellaAssistantService: +async loadTips(route: string): Promise { + const locale = this.i18n.locale(); // 'en-US', 'bg-BG', etc. + const contexts = this.activeContexts().join(','); + const resp = await firstValueFrom( + this.http.get( + `/api/v1/stella-assistant/tips?route=${route}&locale=${locale}&contexts=${contexts}` + ) + ); + this.tips.set(resp.tips); + this.greeting.set(resp.greeting); + this.contextTips.set(resp.contextTips); +} +``` + +### Chat Animation Sync + +```typescript +// In StellaAssistantComponent, during chat mode: +// Listen to ChatService SSE events and animate mascot accordingly: + +this.chatService.streamEvents$.subscribe(event => { + switch (event.type) { + case 'progress': + this.streamStage.set(event.data.stage); + if (event.data.stage === 'thinking') this.mascotAnim.set('thinking'); + if (event.data.stage === 'searching') this.mascotAnim.set('searching'); + break; + case 'token': + this.mascotAnim.set('talking'); + break; + case 'citation': + this.mascotAnim.set('pointing'); + break; + case 'done': + this.mascotAnim.set('satisfied'); + break; + case 'error': + this.mascotAnim.set('concerned'); + break; + } +}); +``` + +--- + +## Delivery Tracker + +### T1 - Database Schema + Seed Migration +Status: DONE +Dependency: none +Owners: Backend Developer + +Create `stella_assistant` schema with tables: tips, greetings, glossary, tours, user_state. Write seed migration from current 189 hardcoded tips. Generate translations for supported locales. + +Completion criteria: +- [x] Schema DDL in platform migration (060_StellaAssistant.sql — 5 tables) +- [x] Seed data: 189 tips + 101 greetings in en-US (061_StellaAssistantSeedData.sql — 1,784 lines) +- [x] Seed data: translations for bg-BG, de-DE, ru-RU, es-ES, fr-FR (at minimum) +- [x] Seed data: 25+ glossary terms (SBOM, VEX, CVE, etc.) in en-US + 5 locales +- [x] Seed data: 3 guided tours (first-setup, scan-workflow, triage-101) in en-US +- [x] Auto-migration wired in platform startup + +### T2 - Assistant API Endpoints +Status: DONE +Dependency: T1 +Owners: Backend Developer + +Implement REST endpoints for tips, glossary, tours, and user state. + +Completion criteria: +- [x] `GET /api/v1/stella-assistant/tips?route=X&locale=Y&contexts=Z` +- [x] `GET /api/v1/stella-assistant/glossary?locale=Y` +- [x] `GET /api/v1/stella-assistant/tours?locale=Y` +- [x] `GET/PUT /api/v1/stella-assistant/user-state` +- [x] Route matching: longest-prefix match for tip resolution +- [x] Fallback: if no tips for locale, fall back to en-US +- [x] Caching: tips cached per route+locale, invalidated on update +- [x] Admin endpoints: POST/DELETE /admin/tips, POST /admin/glossary, GET/POST /admin/tours (SetupAdmin policy) + +### T3 - StellaAssistantService (unified frontend service) +Status: DONE +Dependency: T2 +Owners: Frontend Developer + +Create `StellaAssistantService` that unifies tips (from API), search (from `UnifiedSearchClient`), and chat (from `ChatService`). Replaces `StellaHelperContextService`. + +Completion criteria: +- [x] Mode management: tips / search / chat with signal-based state +- [x] Tips loaded from API on route change (with locale from `I18nService`) +- [x] Context injection (components push context keys) +- [x] Search delegation to `UnifiedSearchClient` +- [x] Chat delegation to `ChatService` with context passing via `SearchChatContextService` +- [x] User state persistence to backend API +- [x] Glossary loaded and available for tooltip directive + +### T4 - Unified Mascot Component (tips + search + chat) +Status: DONE +Dependency: T3 +Owners: Frontend Developer + +Rewrite `StellaHelperComponent` → `StellaAssistantComponent` with three-mode UI (tips, search, chat). Replaces both the mascot and the search assistant drawer. + +Completion criteria: +- [x] Tips mode: speech bubble with API-backed tips, tip navigation, greeting +- [x] Search mode: inline search input, entity cards, synthesis panel +- [x] Chat mode: conversation messages, streaming animation, citations, actions +- [x] Mode transitions: type in search → search mode, "Ask AI" → chat mode, clear → tips mode +- [x] Ctrl+K opens search mode (replaces or enhances old global search) +- [x] Mascot animations synced to chat SSE events (thinking, searching, talking, concerned) +- [x] Responsive: expanded panel on desktop, full-screen on mobile +- [x] All text from `I18nService` or API (zero hardcoded strings) + +### T5 - Glossary Tooltip Directive (DB-backed, i18n) +Status: DONE +Dependency: T3 +Owners: Frontend Developer + +Replace the planned Sprint 006 T4 (static glossary) with a DB-backed, i18n-aware version. Directive uses `StellaAssistantService.glossary()` signal. + +Completion criteria: +- [x] `[stellaGlossary]` directive that wraps first occurrence of domain terms +- [x] Tooltip shows definition from API (locale-aware) +- [x] "Learn more" link navigates to related route +- [x] Related terms shown for deeper exploration +- [x] Glossary terms loaded once per page, cached in service + +### T6 - Admin Tip Editor +Status: DONE +Dependency: T2 +Owners: Frontend Developer + +Add a UI for admins to create/edit/translate tips, glossary, and tours without code deploys. Accessible from Console Admin. + +Completion criteria: +- [x] CRUD for tips (create, edit, deactivate, reorder) +- [x] Locale selector for translating tips +- [x] Preview mode (see how tip looks in the mascot bubble) +- [x] CRUD for glossary terms (create, edit inline) +- [x] Tour step editor with route + selector targeting (create/edit tours with step list) +- [x] Role-gated: requires `SetupAdmin` policy (ui.admin scope) + +### T7 - Guided Tour Engine +Status: DONE +Dependency: T3, T4 +Owners: Frontend Developer + +Build the tour execution engine that steps through DB-defined tours, highlighting elements and showing the mascot at each step. + +Completion criteria: +- [x] Tour player component (step indicator, prev/next, skip, finish) +- [x] Element highlighting with backdrop dimming and glow effect +- [x] Mascot positioned near highlighted element with speech bubble +- [x] Tour progress persisted to user state (completedTours[]) +- [x] Pre-defined tours: first-setup (6 steps), scan-workflow (5 steps), triage-101 (4 steps) — in DB seed data + +--- + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-29 | Sprint created. Architecture analyzed: search, AI chat, i18n, and platform config systems mapped. Unification plan designed with DB schema, API, and three-mode mascot component. | Planning | +| 2026-03-29 | T1 DONE: DB migration 060_StellaAssistant.sql (6 tables: tips, greetings, glossary, tours, user_state). | Developer | +| 2026-03-29 | T2 DONE: API endpoints (AssistantEndpoints.cs: GET /tips, /glossary, GET+PUT /user-state), Store (PostgresAssistantStore.cs with longest-prefix route matching, locale fallback), Contracts (AssistantModels.cs). Registered in Program.cs. Build passes. | Developer | +| 2026-03-29 | T3 PARTIAL: StellaAssistantService created (mode management, tips from API with static fallback, i18n integration, search/chat bridges, glossary loading). | Developer | +| 2026-03-29 | T4 PARTIAL: StellaHelperComponent upgraded to three-mode UI (tips + search input + chat mode), "Ask Stella" button, input bar with send button, chat streaming stage display. Build passes, visually verified. | Developer | +| 2026-03-29 | T3 DONE: StellaAssistantService fully wired — search delegates to UnifiedSearchClient (entity cards + synthesis), chat delegates to ChatService (create conversation + sendMessage + SSE streaming), i18n locale passed on all API calls. | Developer | +| 2026-03-29 | T4 DONE: Component updated — search mode shows entity cards with type/title/snippet, "no results" state, synthesis summary. Chat mode shows conversation turns, streaming stage labels (Thinking/Searching/Validating/Formatting), citations count, error state. Question detection auto-routes to chat. | Developer | +| 2026-03-29 | T5 DONE: StellaGlossaryDirective created — `[stellaGlossary]` directive auto-annotates domain terms with dotted underline + hover tooltip. Global CSS for tooltip styling. Uses StellaAssistantService.glossary() signal (DB-backed via API). | Developer | +| 2026-03-30 | T6 DONE: Admin tip editor completed — Tours tab with CRUD + step editor, glossary terms now editable with create/edit forms. Backend admin endpoints for tours added (GET/POST /admin/tours). | Developer | +| 2026-03-30 | T7 DONE: Tour player component verified — stella-tour.component.ts with backdrop, step navigation, element highlighting, progress persistence. All 7 tasks complete. Sprint ready to archive. | Developer | + +## Decisions & Risks +- **Decision**: Mascot becomes THE unified entry point for help, search, and AI chat. Three separate UIs → one. +- **Decision**: Ctrl+K triggers the mascot's search mode (not a separate dropdown). Old global search remains as fallback for power users. +- **Decision**: All tip content moves to PostgreSQL with per-locale rows. Frontend static config becomes seed data only. +- **Decision**: Chat is embedded in the mascot bubble (expanded), NOT in a separate drawer. The `SearchAssistantHostComponent` drawer is deprecated in favor of the mascot's chat mode. +- **Risk**: Backend API latency for tip loading. Mitigate: aggressive client-side caching, preload tips for common routes, fallback to hardcoded config if API fails. +- **Risk**: Translation quality for 9 locales. Mitigate: start with en-US + bg-BG (primary users), add other locales incrementally. +- **Risk**: Unified mascot component complexity. Mitigate: keep three modes as separate child components (TipsPanelComponent, SearchPanelComponent, ChatPanelComponent) composed by the parent. + +## Relationship to Sprint 006 + +Sprint 006 tasks that are **superseded** by this sprint: +- T0b (deep context) → superseded by T3 (StellaAssistantService with API-backed context) +- T4 (glossary tooltips) → superseded by T5 (DB-backed glossary) +- T10 (Ctrl+K help) → superseded by T4 (unified search in mascot) + +Sprint 006 tasks that **remain independent**: +- T1 (setup wizard) → becomes a guided tour in T7 +- T2 (dashboard hints) → inline hints complement mascot tips +- T3 (empty states) → empty state improvements stand alone +- T5 (page help panels) → collapsible panels complement mascot +- T6 (status bar tooltips) → status bar improvements stand alone +- T7 (VEX/reachability education) → inline education panels stand alone +- T8 (integrations setup) → setup guidance stands alone +- T9 (sidebar context) → sidebar tooltips stand alone + +## Next Checkpoints +- Phase 1: T1 + T2 (backend: schema + API) — enables everything else +- Phase 2: T3 + T4 (frontend: unified service + component) — the core UX change +- Phase 3: T5 + T6 + T7 (glossary directive, admin editor, tour engine) — polish and admin tools diff --git a/docs/implplan/SPRINT_20260328_004_ElkSharp_document_rendering_cleanup.md b/docs/implplan/SPRINT_20260328_004_ElkSharp_document_rendering_cleanup.md new file mode 100644 index 000000000..16dd792a7 --- /dev/null +++ b/docs/implplan/SPRINT_20260328_004_ElkSharp_document_rendering_cleanup.md @@ -0,0 +1,50 @@ +# Sprint 20260328-004 - ElkSharp Document Rendering Cleanup + +## Topic & Scope +- Tighten the ElkSharp document-processing render so the generated artifact is visually clean and satisfies the current hard and soft geometry rules. +- Focus on the remaining document-specific finish defects: gateway source-exit scoring opportunities, awkward default/end finish-ups, and residual fork/join shared-lane collapse. +- Working directory: `src/__Libraries/StellaOps.ElkSharp/`. +- Expected evidence: focused document renderer tests, regenerated artifact outputs, and visual review of the latest `elksharp.png`. + +## Dependencies & Concurrency +- Depends on the current ElkSharp routing/post-processing pipeline in `src/__Libraries/StellaOps.ElkSharp/`. +- Safe cross-module edits for this sprint are limited to: + - `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/` + - `docs/workflow/` + +## Documentation Prerequisites +- `docs/code-of-conduct/CODE_OF_CONDUCT.md` +- `docs/code-of-conduct/TESTING_PRACTICES.md` +- `docs/workflow/ENGINE.md` +- `src/__Libraries/StellaOps.ElkSharp/AGENTS.md` +- `src/__Libraries/StellaOps.ElkSharp/ElkEdgePostProcessor.GatewayBoundary.cs` +- `src/__Libraries/StellaOps.ElkSharp/ElkEdgeRouterIterative.WinnerRefinement.cs` +- `src/__Libraries/StellaOps.ElkSharp/ElkEdgeRoutingScoring.cs` + +## Delivery Tracker + +### TASK-001 - Clean the document-processing ElkSharp artifact +Status: DOING +Dependency: none +Owners: Implementer +Task description: +- Use the document-processing artifact test as the primary target surface and iterate on ElkSharp routing/post-processing until the remaining source-exit finish defects are removed. +- Keep changes scoped to the Elk tree and Elk-specific renderer tests, preserving deterministic routing and existing flat/compound contracts outside the document cleanup slice. + +Completion criteria: +- [ ] The document-processing artifact passes the current hard and soft geometry assertions, including gateway-source scoring and shared-lane checks +- [ ] The regenerated `elksharp.png` is visually reviewed and no obvious new curl/finish-up regression is present +- [ ] Sprint execution log records the focused commands and outcomes + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-28 | Sprint created and work started for document-processing artifact cleanup in ElkSharp. | Implementer | + +## Decisions & Risks +- The cleanup remains scoped to the Elk tree and Elk-specific renderer tests; unrelated Platform/Web changes in the worktree are explicitly out of scope. +- The artifact test is the authoritative quality gate for this slice because the user request is about the generated document rendering, not generic score improvement in abstract. + +## Next Checkpoints +- After the first routing/post-processing patch: rerun the artifact inspection test and compare the remaining offender list +- Before closing the sprint: rerun the document artifact generation path, open the resulting PNG, and record the visual review diff --git a/docs/implplan/SPRINT_20260328_005_ElkSharp_source_decomposition.md b/docs/implplan/SPRINT_20260328_005_ElkSharp_source_decomposition.md new file mode 100644 index 000000000..d0ff7c525 --- /dev/null +++ b/docs/implplan/SPRINT_20260328_005_ElkSharp_source_decomposition.md @@ -0,0 +1,104 @@ +# Sprint 20260328-005 - ElkSharp Source Decomposition + +## Topic & Scope +- Reduce the size and coupling of the largest active ElkSharp source files before any further document-render tuning. +- Split implementation and Elk-specific renderer tests by rule family so routing, scoring, and finalization behavior are easier to reason about and regressions are easier to localize. +- Working directory: `src/__Libraries/StellaOps.ElkSharp/`. +- Expected evidence: smaller partial source files, Elk-specific test-file splits, and focused regression test results proving no behavior drift from the refactor. + +## Dependencies & Concurrency +- Depends on the current ElkSharp routing and post-processing implementation already present in `src/__Libraries/StellaOps.ElkSharp/`. +- Safe cross-module edits for this sprint are limited to: + - `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/` + - `docs/workflow/` + +## Documentation Prerequisites +- `docs/code-of-conduct/CODE_OF_CONDUCT.md` +- `docs/code-of-conduct/TESTING_PRACTICES.md` +- `docs/workflow/ENGINE.md` +- `src/__Libraries/StellaOps.ElkSharp/AGENTS.md` +- `docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md` +- `docs/implplan/SPRINT_20260328_003_ElkSharp_compound_sugiyama_support.md` + +## Delivery Tracker + +### TASK-001 - Split oversized Elk implementation files into partial modules +Status: DOING +Dependency: none +Owners: Implementer +Task description: +- Decompose the largest active ElkSharp implementation files into smaller partial files grouped by coherent routing/scoring concerns. +- Preserve behavior and signatures; the goal is structural readability and maintenance, not algorithm changes. + +Completion criteria: +- [x] `ElkNodePlacement.cs` is reduced into `ElkNodePlacement.Refinement.cs` and `ElkNodePlacement.Grid.cs` +- [x] `ElkEdgePostProcessorSimplify.cs` is reduced into `ElkEdgePostProcessorSimplify.Shortcuts.cs` and `ElkEdgePostProcessorSimplify.OuterCorridors.cs` +- [x] `ElkEdgeRouterHighway.cs` is reduced into `ElkEdgeRouterHighway.Groups.cs` and `ElkEdgeRouterHighway.Paths.cs` +- [x] `ElkRepeatCollectorCorridors.cs` is reduced into `ElkRepeatCollectorCorridors.Candidates.cs` and `ElkRepeatCollectorCorridors.Rewrite.cs` +- [x] Compile baseline is restored after removing incomplete half-split artifacts in other Elk families +- [ ] Remaining large Elk families are decomposed in stable batches that keep the tree buildable after each batch +- [ ] No public contract or deterministic behavior changes are introduced by the split + +### TASK-002 - Split oversized Elk-specific renderer test files +Status: TODO +Dependency: TASK-001 +Owners: Implementer +Task description: +- Break the largest Elk-specific test files into partial classes organized by rule family and scenario family. +- Keep existing test names unchanged so failure signatures remain stable. + +Completion criteria: +- [ ] `ElkSharpEdgeRefinementTests.Restabilization.cs` is reduced by moving rule families into dedicated partial files +- [ ] `DocumentProcessingWorkflowRenderingTests.Scenarios.cs` is reduced by moving scenario clusters/helpers into dedicated partial files +- [ ] Test discovery remains unchanged + +### TASK-003 - Revalidate focused Elk regressions after structural split +Status: TODO +Dependency: TASK-001 +Owners: Implementer +Task description: +- Run focused Elk renderer regressions that cover gateway boundary handling, target-join repair, repeat-return/shared-lane cleanup, and document scenario checks. +- Confirm the split is behavior-preserving before resuming rendering cleanup work. + +Completion criteria: +- [ ] Focused Elk regression tests pass after the decomposition +- [ ] Execution log records the commands and outcomes + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-28 | Sprint created to separate source decomposition from paused document-render cleanup work. | Implementer | +| 2026-03-28 | Reduced `ElkNodePlacement.cs` into `ElkNodePlacement.Refinement.cs` and `ElkNodePlacement.Grid.cs`; reduced `ElkEdgePostProcessorSimplify.cs` into `ElkEdgePostProcessorSimplify.Shortcuts.cs` and `ElkEdgePostProcessorSimplify.OuterCorridors.cs`. | Implementer | +| 2026-03-28 | Audit of the broader split attempt found that most other decompositions existed only as untracked helper files while the original roots still owned the same methods. Those half-split artifacts were removed from both `src/__Libraries/StellaOps.ElkSharp/` and `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/` to restore a truthful build baseline. | Implementer | +| 2026-03-28 | `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.csproj -v minimal` passed after the half-split cleanup. | Implementer | +| 2026-03-28 | `dotnet build src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj -v minimal` passed after removing duplicate untracked test partials; only the pre-existing `NUnit1033` renderer-test warnings remain. | Implementer | +| 2026-03-28 | Re-ran `dotnet build src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj -v minimal` after the resumed safe splits and confirmed the renderer test project still builds cleanly on the restored baseline. | Implementer | +| 2026-03-28 | Reduced `ElkEdgeRouterHighway.cs` into `ElkEdgeRouterHighway.Groups.cs` and `ElkEdgeRouterHighway.Paths.cs`, and reduced `ElkRepeatCollectorCorridors.cs` into `ElkRepeatCollectorCorridors.Candidates.cs` and `ElkRepeatCollectorCorridors.Rewrite.cs`. All six files are now below the sprint cap and both build commands remained green after the batch. | Implementer | +| 2026-03-28 | Reduced `ElkEdgeRouterAStar8Dir.cs` into `ElkEdgeRouterAStar8Dir.Costs.cs` and `ElkEdgeRouterAStar8Dir.Grid.cs`. The root file is now 286 lines and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer | +| 2026-03-28 | Reduced `ElkEdgeRouterIterative.cs` into `ElkEdgeRouterIterative.CollectorNormalization.cs` and `ElkEdgeRouterIterative.GeometryHelpers.cs`. The root file is now 166 lines and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer | +| 2026-03-28 | Reduced `ElkEdgeRoutingGeometry.cs` into `ElkEdgeRoutingGeometry.Boundary.cs` and `ElkEdgeRoutingGeometry.Intersections.cs`. All three files are now below the sprint cap and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer | +| 2026-03-29 | Reduced `ElkEdgeRouter.cs` into `ElkEdgeRouter.DummyReconstruction.cs`; reduced `ElkEdgePostProcessorCorridor.cs` into `ElkEdgePostProcessorCorridor.Safety.cs`; and reduced `ElkLayoutTypes.cs` into `ElkLayoutTypes.Retry.cs` and `ElkLayoutTypes.Strategy.cs`. All resulting files are below the sprint cap and both build commands stayed green after the batch, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer | +| 2026-03-29 | Reduced `ElkEdgeRouteRefiner.cs` into `ElkEdgeRouteRefiner.Helpers.cs`. The root file is now 254 lines and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer | +| 2026-03-29 | Reduced `ElkCompoundLayout.cs` into `ElkCompoundLayout.Ordering.cs`, `ElkCompoundLayout.BoundaryCrossings.cs`, and `ElkCompoundLayout.Positioning.cs`. The root file is now 300 lines and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer | +| 2026-03-29 | Reduced `ElkEdgeRouterIterative.Finalization.cs` into `ElkEdgeRouterIterative.Finalization.Detours.cs`, `ElkEdgeRouterIterative.Finalization.Chooser.cs`, `ElkEdgeRouterIterative.Finalization.TerminalCleanup.Round.cs`, and `ElkEdgeRouterIterative.Finalization.TerminalCleanup.Closure.cs`. All resulting files are now at or below the sprint cap and both build commands stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer | +| 2026-03-29 | Reduced `ElkShapeBoundaries.cs` into `ElkShapeBoundaries.Intersections.cs`, `ElkShapeBoundaries.GatewayInterior.cs`, `ElkShapeBoundaries.BoundarySlots.cs`, `ElkShapeBoundaries.Exterior.cs`, and `ElkShapeBoundaries.Exterior.Helpers.cs`. The ElkSharp build and the renderer test project build both stayed green after the split, with only the existing `NUnit1033` warnings in the renderer test project. | Implementer | +| 2026-03-29 | Reduced `ElkEdgeRouterIterative.LocalRepair.cs` into `RetryBudgets`, `Selection`, `Ordering`, `Endpoints`, `Eligibility`, `ShortestRepair`, `RepairQuality`, `ShortestPaths`, `ObstacleSkirt`, `Backtracking`, and `CollectorRestoration` partials. The root file is now 194 lines and both build commands stayed green after the split. | Implementer | +| 2026-03-29 | Reduced `ElkEdgeRouterIterative.WinnerRefinement.cs` into `Focus`, `UnderNode`, `SharedLane`, `BoundarySlots`, `TerminalClosures`, `Detours`, `FinalBoundarySlot`, `FinalRestabilized`, `LateRestabilization`, and `Promotion` partials. The root file is now 120 lines and both build commands stayed green after the split. | Implementer | +| 2026-03-29 | Reduced `ElkEdgeRouterIterative.StrategyRepair.cs` into `Evaluate`, `RouteAllEdges`, `RepairPenalizedEdges`, `VerifiedIssues`, `RepairPlan`, `RepairPlan.Expanders`, `ParallelBuilds`, and `Fingerprints` partials. The root file is now 19 lines and both build commands stayed green after the split. | Implementer | + +## Decisions & Risks +- The document-render cleanup sprint remains paused while decomposition is underway; rendering quality work resumes only after the structural split is stable. +- Decomposition stays within the Elk tree and Elk-specific renderer tests so unrelated repo areas do not move during this refactor. +- Method moves are done as-is first; helper redesign is deferred unless a direct move is impossible without duplication. +- The first broad decomposition attempt was not a stable state: most of the added partial files were untracked while the original tracked roots still contained the moved methods. Keeping those files would have left the repository permanently uncompilable, so they were removed rather than carried forward. +- The current stable decomposition baseline is limited to fourteen families: `ElkNodePlacement`, `ElkEdgePostProcessorSimplify`, `ElkEdgeRouterHighway`, `ElkRepeatCollectorCorridors`, `ElkEdgeRouterAStar8Dir`, `ElkEdgeRouterIterative`, `ElkEdgeRoutingGeometry`, `ElkEdgeRouter`, `ElkEdgeRouteRefiner`, `ElkEdgePostProcessorCorridor`, `ElkLayoutTypes`, `ElkCompoundLayout`, `ElkEdgeRouterIterative.Finalization`, and `ElkShapeBoundaries`. +- The current stable decomposition baseline now also includes the three main iterative-control families: `ElkEdgeRouterIterative.LocalRepair`, `ElkEdgeRouterIterative.StrategyRepair`, and `ElkEdgeRouterIterative.WinnerRefinement`. +- The remaining implementation files above the cap are no longer the small mechanical bucket. The next files that still need work are the large helper-extraction hotspots: `ElkEdgePostProcessor`, `ElkEdgeRoutingScoring`, `ElkEdgePostProcessor.UnderNode`, `ElkEdgePostProcessor.BoundarySlots`, `ElkEdgePostProcessor.FaceConflictRepair`, and `ElkEdgePostProcessor.GatewayBoundary`. +- Two iterative-router files still exceed the target cap even after the stable split and need helper extraction rather than another blind move: `ElkEdgeRouterIterative.StrategyRepair.Evaluate.cs` and `ElkEdgeRouterIterative.StrategyRepair.RepairPlan.cs`. +- Test-file decomposition was intentionally rolled back during the cleanup because the split files duplicated tracked tests instead of replacing them. Test splitting should resume only after the code-side split discipline is stable. +- Remaining hotspot families still need careful extraction with an explicit “root trimmed in the same batch” rule: `ElkCompoundLayout`, `ElkShapeBoundaries`, `ElkEdgeRoutingScoring`, `ElkEdgeRouterAStar8Dir`, `ElkEdgeRouterIterative`, `ElkEdgePostProcessor.BoundarySlots`, `ElkEdgePostProcessor.GatewayBoundary`, `ElkEdgePostProcessor.SharedLane`, `ElkEdgePostProcessor.TargetPeerConflicts`, and `ElkEdgePostProcessor.UnderNode`. +- Focused regression revalidation has not yet been rerun on the restored baseline. No rendering-behavior conclusions should be carried over from the discarded half-split state. + +## Next Checkpoints +- Decompose the next single Elk family only if the root file is trimmed in the same batch and both build commands stay green afterward +- After the next stable implementation batch: rerun focused Elk regressions and record the first valid post-cleanup results before resuming any artifact tuning diff --git a/docs/implplan/SPRINT_20260329_006_ElkSharp_hybrid_iterative_routing.md b/docs/implplan/SPRINT_20260329_006_ElkSharp_hybrid_iterative_routing.md new file mode 100644 index 000000000..1551b7ae7 --- /dev/null +++ b/docs/implplan/SPRINT_20260329_006_ElkSharp_hybrid_iterative_routing.md @@ -0,0 +1,107 @@ +# Sprint 20260329-006 - ElkSharp Hybrid Iterative Routing + +## Topic & Scope +- Introduce an opt-in deterministic hybrid iterative router that preserves Sugiyama geometry and replaces whole-graph brute-force strategy fan-out with one baseline route plus bounded targeted repair waves. +- Keep parallel repair work intelligent and deterministic by parallelizing only independent candidate builds, then committing winners in stable order. +- Continue decomposing the iterative-router control families so the new mode lives in focused partials instead of monolithic files. +- Working directory: `src/__Libraries/StellaOps.ElkSharp/`. +- Expected evidence: new iterative-routing mode/config, hybrid parity tests, updated workflow-engine documentation, and stable builds for ElkSharp plus the renderer tests. + +## Dependencies & Concurrency +- Depends on `docs/implplan/SPRINT_20260328_005_ElkSharp_source_decomposition.md` for the ongoing source split baseline. +- Safe cross-module edits for this sprint are limited to: + - `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/` + - `docs/workflow/` + - `docs/implplan/` + +## Documentation Prerequisites +- `docs/code-of-conduct/CODE_OF_CONDUCT.md` +- `docs/code-of-conduct/TESTING_PRACTICES.md` +- `docs/workflow/ENGINE.md` +- `src/__Libraries/StellaOps.ElkSharp/AGENTS.md` +- `docs/implplan/SPRINT_20260328_005_ElkSharp_source_decomposition.md` + +## Delivery Tracker + +### TASK-001 - Add an opt-in hybrid deterministic iterative routing mode +Status: DOING +Dependency: none +Owners: Implementer +Task description: +- Extend the public iterative-routing options with an explicit mode switch and bounded hybrid repair controls. +- Keep the legacy multi-strategy path intact while adding a new hybrid branch that runs one baseline route, plans targeted repairs from the existing issue taxonomy, and applies them in deterministic waves. + +Completion criteria: +- [x] `IterativeRoutingOptions` exposes `Mode`, `MaxRepairWaves`, and `MaxParallelRepairBuilds` +- [x] `ElkEdgeRouterIterative.Optimize` can execute a `HybridDeterministic` path without changing legacy behavior by default +- [x] Hybrid mode preserves fixed Sugiyama node geometry and remains opt-in +- [ ] Hybrid mode replaces the remaining coarse local-repair lock policy with conflict-zone-aware scheduling across the full repair pipeline +- [ ] Hybrid mode is documented as the recommended path for `LeftToRight` once parity is proven + +### TASK-002 - Add deterministic hybrid parity coverage +Status: DOING +Dependency: TASK-001 +Owners: Implementer +Task description: +- Freeze the first hybrid invariants in focused Elk renderer tests. +- The tests must prove deterministic replay, Sugiyama node-geometry stability, and no regression in the primary violation classes used to gate winner selection. + +Completion criteria: +- [x] A focused hybrid test file exists under `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/` +- [x] Hybrid deterministic replay is asserted by a repeated-run geometry comparison +- [x] Hybrid node geometry is asserted against legacy mode +- [x] Hybrid primary-violation counts are asserted to be no worse than legacy for the covered stress graph +- [ ] Focused hybrid parity coverage is expanded to gateway-boundary, boundary-slot, and document-processing scenarios + +### TASK-003 - Continue decomposing iterative control files around the hybrid seam +Status: DOING +Dependency: TASK-001 +Owners: Implementer +Task description: +- Split the iterative-router control families so the new mode remains localized and future helper extraction is tractable. +- Preserve behavior while moving methods as-is into focused partials; avoid redesigning the algorithms unless a direct move is impossible. + +Completion criteria: +- [x] `ElkEdgeRouterIterative.LocalRepair.cs` is reduced to a small root coordinator +- [x] `ElkEdgeRouterIterative.WinnerRefinement.cs` is reduced to a small root coordinator +- [x] `ElkEdgeRouterIterative.StrategyRepair.cs` is reduced to a thin root plus focused partials +- [ ] `ElkEdgeRouterIterative.StrategyRepair.Evaluate.cs` is reduced below the sprint cap +- [ ] `ElkEdgeRouterIterative.StrategyRepair.RepairPlan.cs` is reduced below the sprint cap + +### TASK-004 - Sync docs and execution evidence +Status: DOING +Dependency: TASK-001 +Owners: Implementer +Task description: +- Update the workflow engine layout documentation to describe the new hybrid mode and its deterministic parallel-processing contract. +- Record build and targeted-test evidence in the sprint execution log. + +Completion criteria: +- [x] `docs/workflow/ENGINE.md` documents the hybrid deterministic mode and its bounded parallel-build rules +- [x] Execution log records the ElkSharp build, renderer-test build, and focused hybrid test commands +- [ ] Follow-up docs describe when hybrid should become the default and how `TopToBottom` remains on legacy until parity + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-29 | Sprint created to isolate hybrid iterative-routing work from the ongoing source decomposition sprint. | Implementer | +| 2026-03-29 | Added `IterativeRoutingMode`, `Mode`, `MaxRepairWaves`, and `MaxParallelRepairBuilds` to the public ElkSharp iterative-routing options and threaded the new values into `IterativeRoutingConfig`. | Implementer | +| 2026-03-29 | Added `ElkEdgeRouterIterative.Hybrid.cs` and wired `ElkEdgeRouterIterative.Optimize` to execute the new hybrid deterministic path when requested. | Implementer | +| 2026-03-29 | Added focused hybrid renderer tests covering deterministic replay, stable node geometry versus legacy mode, and no increase in primary violations on the stress graph. | Implementer | +| 2026-03-29 | `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.csproj -v minimal` passed after the hybrid mode implementation. | Implementer | +| 2026-03-29 | `dotnet build src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj -v minimal` passed after the hybrid mode implementation; only the existing `NUnit1033` warnings remain in the renderer test project. | Implementer | +| 2026-03-29 | `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --filter "Name~HybridDeterministicMode" -v normal` passed with 3/3 tests green. | Implementer | +| 2026-03-29 | Reduced `ElkEdgeRouterIterative.LocalRepair`, `ElkEdgeRouterIterative.StrategyRepair`, and `ElkEdgeRouterIterative.WinnerRefinement` into focused partials around the new hybrid seam and revalidated both builds plus the hybrid test slice. | Implementer | + +## Decisions & Risks +- Hybrid mode is opt-in and does not replace legacy multi-strategy routing by default. +- Sugiyama output remains authoritative: node positions, ordering, dummy reconstruction, and upstream anchoring contracts are preserved. +- Parallel processing stays limited to candidate construction on independent repair batches. Candidate commits remain single-threaded and deterministic. +- `TopToBottom` is intentionally not promoted to hybrid mode by default in this sprint; it stays on the legacy path until parity is explicitly proven. +- The current hybrid batching still uses deterministic conflict keys derived from endpoint and collector locality. A fuller conflict-zone graph is still required before the old coarse lock-key assumptions can be removed everywhere. +- The two remaining oversize files in the iterative-control family are `ElkEdgeRouterIterative.StrategyRepair.Evaluate.cs` and `ElkEdgeRouterIterative.StrategyRepair.RepairPlan.cs`. They require helper extraction, not another blind line move. + +## Next Checkpoints +- Reduce `ElkEdgeRouterIterative.StrategyRepair.Evaluate.cs` and `ElkEdgeRouterIterative.StrategyRepair.RepairPlan.cs` below the sprint cap without behavior changes. +- Expand hybrid parity coverage to gateway-boundary, boundary-slot, and document-processing regressions. +- Replace coarse repair-build lock keys with a fuller conflict-zone scheduler before considering hybrid mode as the `LeftToRight` default. diff --git a/docs/implplan/SPRINT_20260329_006_FE_devops_onboarding_ux.md b/docs/implplan/SPRINT_20260329_006_FE_devops_onboarding_ux.md new file mode 100644 index 000000000..475c99100 --- /dev/null +++ b/docs/implplan/SPRINT_20260329_006_FE_devops_onboarding_ux.md @@ -0,0 +1,1276 @@ +# Sprint 006 — DevOps Onboarding UX: Make Every Screen Teach + +## Topic & Scope + +**Persona**: "Alex" — a mid-level developer who was just appointed as DevOps engineer. The previous senior pro who knew everything was fired. Alex knows Docker basics, git, and CI/CD concepts, but has zero knowledge of: SBOM, VEX, reachability analysis, policy gates, decision capsules, attestation, evidence-grade releases, air-gapped deployment, or compliance frameworks (FIPS/eIDAS/GOST). + +**Problem**: Opening Stella Ops for the first time is like walking into a nuclear power plant control room. 30+ screens, 100+ specialized terms, and no one left to explain. The UI currently assumes expert-level domain knowledge — it shows *what* but never explains *why* or *how*. + +**Goal**: Transform every screen so that Alex can self-onboard, understand what each capability does, know what actions to take, and feel confident performing DevOps/security duties — without external documentation or tribal knowledge. + +- Working directory: `src/Web/StellaOps.Web/src/app/` +- Expected evidence: Before/after screenshots, component diffs, onboarding flow tests + +## Dependencies & Concurrency +- No upstream sprint dependencies +- Safe to parallelize across screen sections (Release Control, Security, Evidence, Operations, Settings) +- Uses existing component infrastructure (no new libraries needed) + +## Documentation Prerequisites +- `docs/product/VISION.md` — north star messaging +- `docs/GLOSSARY.md` — canonical term definitions +- `docs/ARCHITECTURE_OVERVIEW.md` — system map for topology hints +- `docs/UI_GUIDE.md` — operator workflow patterns + +--- + +## AUDIT FINDINGS: Screen-by-Screen Analysis + +### Legend +- ✅ = Already good / has helpful content +- ⚠️ = Partially helpful but needs improvement +- ❌ = Missing / confusing / needs major help + +--- + +### 01. Welcome Page (`/welcome`) +**Current state**: ✅ Good foundation +- Shows "After Sign-In You Can" with 4 capabilities +- Shows "What Stella Replaces" comparisons +- Has badges: Air-gap Ready, FIPS/eIDAS/GOST/SM, BUSL-1.1 + +**What's missing for Alex**: +- ❌ No "Getting Started Checklist" — Alex doesn't know the ORDER of operations +- ❌ No explanation of what "Release Control Plane" means in practical terms +- ⚠️ "Governed releases with policy gates" — Alex doesn't know what policy gates are + +**Recommendations**: +1. Add a "Your First Hour" section below the sign-in button: + ``` + YOUR FIRST HOUR + 1. Run Diagnostics → Check all services are healthy + 2. Connect a Registry → Link where your container images live + 3. Scan Your First Image → See what's inside it + 4. Review Findings → Understand your security posture + 5. Create Your First Release → Bundle verified artifacts + ``` +2. Add a one-sentence plain-English translation under "Release Control Plane": + > "Think of it as a smart gatekeeper between your CI pipeline and production. It scans your containers, checks security policies, requires approvals, and keeps signed proof of every decision." + +--- + +### 02. Dashboard (`/`) +**Current state**: ⚠️ Rich with data, zero explanation +- Shows: Pending Actions (environment cards), Vulnerability Summary, SBOM Health, Environment Health, Environments at Risk, Feed Status, Quick Links +- All environments show "SBOM: missing", "Health: unknown" + +**What's missing for Alex**: +- ❌ No explanation of what "SBOM" means (Software Bill of Materials — a list of every component inside your container) +- ❌ "SBOM: missing" everywhere but no hint on HOW to fix it (answer: scan an image) +- ❌ "Health: unknown" with no hint on what determines health +- ❌ Vulnerability counts (Critical: 3, High: 2) with no context — is this bad? Normal? What should Alex do? +- ❌ "CRIT. REACHABLE: 0" — Alex has no idea what reachability means +- ❌ "Feed Status: 42 active, Not checked" — what are feeds? Why do they matter? +- ❌ Quick Links section is just labels with no descriptions of what each leads to + +**Recommendations**: +1. **First-visit welcome banner** (dismissable, shows only once): + ``` + 👋 Welcome to Stella Ops, Alex! + You're looking at the operations dashboard — your daily command center. + Everything here updates in real-time as you scan images, create releases, and promote deployments. + + Looks empty? That's normal for a fresh setup. Here's your getting-started checklist: + [Start Setup Wizard →] + ``` + +2. **Contextual help icons (?) next to every metric**: + - SBOM: "Software Bill of Materials — an inventory of every package, library, and binary inside your container image. Run a scan to generate one." + - Reachability: "Can an attacker actually reach this vulnerability through your code? Stella analyzes call graphs to separate real risks from theoretical ones." + - Feed Status: "Vulnerability advisory feeds (NVD, OSV, etc.) — databases of known security issues that Stella checks your images against. These update automatically." + +3. **Color-coded severity guide** (inline, first visit): + ``` + SEVERITY GUIDE + 🔴 Critical — Exploitable, often remotely. Fix immediately. + 🟠 High — Significant risk. Plan remediation within days. + 🟡 Medium — Moderate risk. Address in next sprint. + 🟢 Low — Minimal risk. Track and fix when convenient. + ``` + +4. **"What should I do next?" card** when dashboard shows issues: + - "3 Critical vulnerabilities found → [View & Triage →]" + - "SBOM missing for all environments → [Scan your first image →]" + - "No environments configured → [Set up environments →]" + +--- + +### 03. Deployments (`/releases/deployments`) +**Current state**: ⚠️ Has approval card, broken empty state +- Shows "1 Pending Approval" card with Approve/Reject/View buttons +- Pipeline tab shows "event_busy" (raw Material icon name as text — **BUG**) +- "No runs match the active filters." + +**What's missing for Alex**: +- ❌ **BUG**: "event_busy" rendered as text instead of icon +- ❌ No explanation of what a "deployment" is in Stella context (a promotion of a release to a target environment) +- ❌ "Gates OK" / "expired" labels with no explanation +- ❌ "Normal" priority label — what other priorities exist? +- ❌ No guidance on WHEN to approve vs reject +- ❌ Empty pipeline state gives no hint on what triggers runs + +**Recommendations**: +1. **Fix the icon bug**: `event_busy` should render as a Material icon, not text +2. **Subtitle enhancement**: Change "Deployment runs, approvals, and promotion activity." to: + > "Track container deployments across your environments. Approve promotions, review gate status, and monitor rollout progress. Deployments are created when a release is promoted from one environment to another (e.g., Staging → Production)." +3. **Empty state for Pipeline tab**: + ``` + No deployment runs yet + + Deployment runs are created when you promote a release from one environment + to another. Each run goes through your configured gates (security scan, + policy check, approval) before reaching the target. + + To see activity here: + 1. Go to Releases → select a release → click "Promote" + 2. Or use the "Create Deployment" button above + + [Create Deployment →] [Learn about promotions →] + ``` +4. **Approval card tooltips**: + - "Gates OK" → tooltip: "All security and policy gates passed. This release meets your organization's requirements for this environment." + - "expired" → tooltip: "The approval window has passed. The approver needs to re-request or the admin must extend the deadline." + +--- + +### 04. Releases (`/releases`) +**Current state**: ⚠️ Data-rich table, unexplained columns +- Shows releases with: Gates (PASS/WARN/BLOCK), Risk (CRITICAL), Evidence (Verified/Missing), Status (Deployed/Ready/Failed/Draft) + +**What's missing for Alex**: +- ❌ "Gates: PASS/WARN/BLOCK" — what are gates? What triggers each status? +- ❌ "Risk: CRITICAL" on everything — is this the vulnerability risk? The release risk? +- ❌ "Evidence: Missing" vs "Verified" — what evidence? Where does it come from? +- ❌ "Standard" release type — what other types exist? +- ❌ sha256 digests shown but not explained — why are they important? + +**Recommendations**: +1. **Column header tooltips**: + - **Gates**: "Policy gates evaluate your release against security rules, compliance requirements, and approval workflows. PASS = all gates satisfied. WARN = advisory issues found. BLOCK = release cannot proceed until issues are resolved." + - **Risk**: "Aggregate security risk based on vulnerability severity and reachability. Considers how many critical/high findings are actually reachable in your code." + - **Evidence**: "Cryptographically signed proof of every scan, policy decision, and approval. 'Verified' means a complete evidence chain exists. 'Missing' means no Decision Capsule has been generated yet." + - **Status**: "Draft = created but not evaluated. Ready = gates passed, awaiting promotion. Deployed = successfully delivered. Failed = deployment or gate failure." +2. **First-visit inline guide** above the table: + ``` + RELEASE LIFECYCLE + Draft → Ready → Promoted → Deployed + ↘ Failed (if gates block or deployment fails) + + Each release bundles container images by their immutable digest (sha256:...), + ensuring you deploy exactly what was scanned — no tag mutations possible. + ``` + +--- + +### 05. Environments (`/environments/overview`) +**Current state**: ✅ Good topology visualization +- Shows Dev → Staging → Production flow with environment cards +- Arrows indicate promotion paths + +**What's missing for Alex**: +- ⚠️ Cards show "UNKNOWN" health but no explanation +- ❌ No indication of how to add/configure environments +- ❌ No explanation of what the arrows (promotion paths) mean operationally +- ❌ "prod-us-east", "eu-west" etc. without explaining region concept + +**Recommendations**: +1. **Topology legend**: + ``` + READING THIS MAP + Each box is an environment — an isolated deployment target with its own + security policies and approval rules. + + Arrows show promotion paths: a release must pass through each environment + in order (Dev → Staging → Production). You can't skip environments. + + Colors: 🟢 Healthy | 🟡 Degraded | 🔴 Blocked | ⚪ Unknown + ``` +2. **"Add Environment" button** with guidance when fewer than 3 environments exist + +--- + +### 06. Readiness (`/releases/readiness`) +**Current state**: ❌ Broken empty state +- Shows: "No readiness data available. Your readiness or targets is not ready." +- Grammatical error in message + +**Recommendations**: +1. **Fix grammar**: "Your readiness or targets is not ready" → proper message +2. **Replace with helpful empty state**: + ``` + No Readiness Data Yet + + The readiness dashboard shows whether your environments and deployment + targets are prepared to receive new releases. It checks: + + • Agent connectivity — Are deployment agents online and responsive? + • Target health — Are Docker hosts / Compose targets reachable? + • Policy compliance — Do pending releases pass all required gates? + • Resource capacity — Is there enough disk/memory for the deployment? + + To populate this dashboard: + 1. Deploy at least one agent to a target host + 2. Configure environment-to-target mappings + 3. Create and scan a release + + [Deploy an Agent →] [Configure Environments →] + ``` + +--- + +### 07. Vulnerabilities (`/triage/artifacts`) +**Current state**: ⚠️ Shows scan artifacts, minimal guidance +- Has tabs: Active, Craft, Needs Review +- Shows one scanned artifact with vulnerability counts + +**What's missing for Alex**: +- ❌ No explanation of the triage workflow (what does "triage" mean here?) +- ❌ "Craft" tab name is unclear +- ❌ "Open workspace" / "Bundle" buttons without context + +**Recommendations**: +1. **Subtitle enhancement**: + > "Review security findings for your container images. Triage means deciding what to do about each vulnerability: fix it, accept the risk (with justification), or mark it as not applicable. Every decision is recorded as auditable evidence." +2. **Triage workflow guide** (collapsible): + ``` + TRIAGE WORKFLOW + 1. Select an artifact (scanned container image) + 2. Review findings by severity + 3. For each finding, decide: + • Fix — create a remediation task + • Accept Risk — document justification (creates a VEX statement) + • Not Applicable — mark as unreachable or irrelevant (with proof) + 4. When all critical/high findings are addressed → release is "Ready" + ``` + +--- + +### 08. Security Posture (`/security`) +**Current state**: ⚠️ Rich metrics, no interpretation +- Shows: Risk Posture (HIGH), VEX Coverage (1), SBOM Health, Advisories Health +- Has "Top Blocking Items", "Expiring Waivers", "Advisories & VEX Health", "Supply Chain Coverage" + +**What's missing for Alex**: +- ❌ "Risk Posture: HIGH" — is this a score? A grade? What makes it high? +- ❌ "VEX Coverage" — what is VEX? +- ❌ "Advisories & VEX Health" — what does "health" mean for advisories? + +**Recommendations**: +1. **Metric explanations** (inline, hover, or expandable): + - Risk Posture: "Your organization's overall security risk level, calculated from unresolved vulnerabilities weighted by severity and reachability. Target: MEDIUM or lower." + - VEX Coverage: "Vulnerability Exploitability eXchange — formal statements about whether vulnerabilities actually affect your software. Higher coverage = fewer 'unknown' findings = better signal-to-noise." +2. **"Start a Scan" CTA** when SBOM is empty: + > "No SBOMs generated yet. Scan a container image to populate your security posture. [Scan Image →]" + +--- + +### 09. Supply-Chain Data (`/security/supply-chain-data`) +**Current state**: ❌ Empty with no guidance +- Shows tabs: SBOM Viewer, SBOM Graph, SBOM Labs, Reachability, ConvergedVerdicts +- "No SBOM components here for current scope." + +**Recommendations**: +1. **Replace empty state**: + ``` + No Supply-Chain Data Yet + + Supply-chain data is the complete inventory of everything inside your + container images: OS packages, language libraries, native binaries, and + their dependency trees. + + This data powers: + • Vulnerability matching — knowing what's inside tells you what's vulnerable + • Reachability analysis — tracing whether vulnerabilities are actually callable + • License compliance — identifying license obligations in your dependencies + • Drift detection — spotting unexpected changes between releases + + To populate this view, scan a container image: + [Scan Image →] + + Or connect a registry to auto-discover images: + [Connect Registry →] + ``` + +--- + +### 10. Findings Explorer (`/security/findings`) +**Current state**: ⚠️ Shows "No recommendations available" and baseline note +- "Comparison evidence becomes available after a baseline is selected." + +**Recommendations**: +1. **Explain baselines**: + > "A baseline is a known-good reference scan. When you select one, Stella shows what CHANGED — new vulnerabilities added, old ones fixed, risk delta. This is the 'Smart-Diff' that separates real regressions from inherited noise." +2. **Guided first action**: "Select an active scan from the dropdown to start exploring, or [scan a new image →]" + +--- + +### 11. Reachability (`/security/reachability`) +**Current state**: ⚠️ Shows coverage data, no explanation +- Shows assets with coverage percentages (78%, 94%) and last fact dates + +**What's missing for Alex**: +- ❌ No explanation of what reachability IS or why it matters + +**Recommendations**: +1. **Page-level explainer** (collapsible): + ``` + WHAT IS REACHABILITY? + + Not all vulnerabilities are equally dangerous. A critical CVE in a library + you imported but never call is noise. Reachability analysis answers: + "Can an attacker actually reach this code?" + + Stella uses a hybrid approach: + • Static analysis — traces call graphs from entry points to vulnerable functions + • Runtime signals — observes which code paths are actually executed in practice + • Confidence scoring — rates each finding from "theoretical" to "confirmed exploitable" + + COVERAGE shows what percentage of your codebase has been analyzed. + Higher = more confident decisions. Target: >80% for production environments. + + WHY THIS MATTERS + With reachability, you might turn 200 "critical" findings into 12 that + actually matter — dramatically reducing alert fatigue and triage time. + ``` + +--- + +### 12. Unknowns (`/security/unknowns`) +**Current state**: ❌ Metrics shown, meaning unclear +- Shows: Total (0), Binaries (0), Symbols (0), AI Status (0) +- "No unknowns matched the current filters." + +**Recommendations**: +1. **Page-level explainer**: + ``` + WHAT ARE UNKNOWNS? + + Unknowns are components the scanner found but couldn't fully identify — + stripped binaries without debug symbols, obfuscated code, or packages + from sources not in any advisory database. + + Why they matter: You can't assess risk for something you can't identify. + Unknowns represent blind spots in your security posture. + + Resolution options: + • Upload debug symbols → enables binary analysis + • Add manual annotations → record what you know about the component + • Flag for AI analysis → use advisory AI to attempt identification + • Accept risk → document the unknown with justification + ``` +2. **Good news message when zero**: "✅ No unknowns — your supply chain is fully identified. All components can be matched against advisory databases." + +--- + +### 13. Scan Image (`/security/scan`) +**Current state**: ⚠️ Functional form, minimal guidance +- Input fields for image reference and tag/digest + +**Recommendations**: +1. **Add examples and explanation**: + ``` + SCAN A CONTAINER IMAGE + + Submit an image reference to generate a complete security analysis: + SBOM, vulnerability scan, reachability assessment, and compliance check. + + Examples: + • registry.example.com/myapp:v2.1.0 + • ghcr.io/org/service@sha256:abc123... + • docker.io/library/nginx:1.25 + + 💡 Tip: Using a digest (sha256:...) instead of a tag ensures you scan + exactly the image you intend — tags can be overwritten, digests can't. + + What happens after you submit: + 1. Image layers are pulled and analyzed + 2. SBOM is generated (all packages, libraries, binaries) + 3. Vulnerabilities are matched against advisory feeds + 4. Reachability analysis determines which findings are exploitable + 5. Results appear in Security Posture within ~2-5 minutes + ``` + +--- + +### 14. VEX & Exceptions (`/ops/policy/vex`) +**Current state**: ❌ All zeros, no explanation +- VEX Statement Dashboard with status cards: Total (0), Affected (0), Not Affected (0), Fixed (0), Investigating (0) +- "No recent activity" + +**Recommendations**: +1. **Full VEX explainer** (this is one of the most confusing concepts): + ``` + WHAT IS VEX? + + VEX (Vulnerability Exploitability eXchange) is a formal way to say: + "Yes, our software uses this library, but this specific vulnerability + doesn't affect us because [reason]." + + It's like a doctor's note for vulnerabilities. Instead of fixing every + theoretical issue, you document WHY certain findings are not exploitable + in your specific context. + + VEX STATUSES + 🔴 Affected — This vulnerability impacts your software. Action required. + 🟢 Not Affected — You use the library, but the vulnerable code path + is not reachable/enabled in your configuration. + 🔵 Fixed — The vulnerability existed but has been patched. + 🟡 Under Investigation — Still determining impact. Timeline: [date]. + + WHY VEX MATTERS + Without VEX, every scan produces hundreds of findings that are technically + true but practically irrelevant. VEX lets you: + • Reduce noise by 60-80% with documented justifications + • Share assessments with auditors and customers + • Auto-suppress known non-issues in future scans + • Build institutional knowledge about your codebase + + GETTING STARTED + 1. Go to Vulnerabilities → select a finding + 2. Click "Create VEX Statement" + 3. Choose status and provide justification + 4. Statement is signed and stored as auditable evidence + + [Create VEX Statement →] [Import VEX Document →] + ``` + +--- + +### 15. Risk & Governance (`/ops/policy/governance`) +**Current state**: ✅ Good — has budget trend, top contributors, active alerts +- Shows risk budget (72%), scores, trends, alerts + +**What's missing for Alex**: +- ⚠️ "Budget threshold exceeded: 70% (Medium)" — what is a risk budget? + +**Recommendations**: +1. **Risk budget explainer**: + > "Your risk budget is like a credit limit for security debt. It measures what percentage of your allowed risk capacity is consumed. When it exceeds thresholds (70% = warning, 90% = critical), promotions may be blocked until risk is reduced through fixes or VEX statements." + +--- + +### 16. Policy Simulation (`/ops/policy/simulation`) +**Current state**: ✅ Good empty state with CTA +- "No Shadow Mode Results" with "Enable Shadow Mode" button +- Has explanation link + +**What's missing for Alex**: +- ⚠️ "Shadow mode" concept not explained on the page itself + +**Recommendations**: +1. **Inline explanation**: + ``` + SHADOW MODE + + Test policy changes safely before they affect real releases. Shadow mode + runs your proposed policy rules alongside the active ones and shows where + they would produce different decisions — without actually blocking anything. + + Use cases: + • "If I tighten the severity threshold, how many releases would be blocked?" + • "Will this new compliance rule break existing deployments?" + • "What's the impact of requiring reachability proof for all criticals?" + ``` + +--- + +### 17. Policy Audit (`/ops/policy/audit`) +**Current state**: ⚠️ Empty table, some tab structure +- Shows tabs: All, Promotions, Approvals, Rejections, Simulations + +**Recommendations**: +1. **Empty state with event type guide**: + ``` + No Policy Audit Events Yet + + This log captures every policy-related action in your organization: + + • Promotions — when a release was promoted between environments + • Approvals — who approved what, when, and why + • Rejections — blocked promotions with gate failure details + • Simulations — shadow mode comparisons and what-if analyses + + Events are generated automatically as your team uses the platform. + The audit trail is immutable and cryptographically signed. + + [View sample audit event →] + ``` + +--- + +### 18. Evidence Overview (`/evidence/overview`) +**Current state**: ✅ Good — shows stats, search, quick views +- 1,842 evidence pieces, 12,340 audit events, 5,271 proof chains + +**Recommendations**: +1. **Stats context**: Add "(since installation)" or date range +2. **Quick explainer for first visit**: + > "Evidence is the signed, tamper-proof record of every scan, decision, approval, and deployment. Unlike logs that can be edited, evidence is cryptographically sealed — providing audit-grade proof that you can present to regulators, customers, or your future self." + +--- + +### 19. Decision Capsules (`/evidence/capsules`) +**Current state**: ✅ Good empty state +- "No decision capsules found" with "Create a Release" CTA + +**Recommendations**: +1. **Add capsule explanation**: + ``` + WHAT IS A DECISION CAPSULE? + + A Decision Capsule bundles ALL the inputs and outputs of a release + decision into a single, signed, verifiable package: + + 📦 What's inside: + • The exact SBOM at scan time + • Vulnerability findings and VEX statements + • Reachability evidence + • Policy rules that were evaluated + • Approval records (who, when, why) + • Cryptographic signatures over everything + + Why it matters: + If an auditor asks "why did you release this?" — you hand them the capsule. + It's self-contained, offline-verifiable, and can be deterministically + replayed to prove the decision was correct. + ``` + +--- + +### 20. Audit Log (`/evidence/audit-log`) +**Current state**: ✅ Good — has event category explanation +- Lists what events are captured (releases, policy, VEX, integration, identity) +- Shows "200+ event capture is active" + +**Recommendations**: +1. Already well-designed. Add: "Events will appear here within seconds of any platform action." + +--- + +### 21. Export Center (`/evidence/exports`) +**Current state**: ✅ Good — 3 pre-configured export profiles +- StellBundle, Daily Compliance Export, Audit Bundle + +**Recommendations**: +1. **Profile descriptions could be richer**: + - StellBundle: Add "Use this for: sharing evidence with external auditors, transferring to air-gapped environments, or archiving for compliance retention" + - Daily Compliance: Add "Use this for: automated daily compliance reporting, regulatory submissions, continuous monitoring evidence" + +--- + +### 22. Operations Hub (`/ops/operations`) +**Current state**: ✅ Excellent — most useful page for a new DevOps person +- Shows: Blocking issues, pending operator actions, budgets per category, health status +- Has actionable items with "Open" links + +**Recommendations**: +1. **This should be promoted in onboarding**: "Start your day here. The Operations Hub shows everything that needs your attention." +2. **Add "What do these mean?" collapsible for budget categories**: + - Blocking Sub: items preventing releases + - Blocking: items that can block releases + - Events: platform events needing attention + - Health: service and infrastructure status + - Supply And Airgap: feed freshness and offline kit status + - Capacity: resource utilization + +--- + +### 23. Policy Packs (`/ops/policy/packs`) +**Current state**: ❌ Shows raw pack IDs, no descriptions +- Lists packs with IDs like "pack-23f832c3a4..." and "ACTIVE" badge +- No human-readable names or descriptions + +**Recommendations**: +1. **Show pack display names and descriptions** (not just IDs) +2. **Add page-level explainer**: + ``` + WHAT ARE POLICY PACKS? + + Policy packs are bundles of security rules that define what your + organization allows. Think of them as "security profiles" you can + apply to different environments. + + Examples: + • "Production Strict" — no critical CVEs, all findings must have + reachability proof, 2 approvers required + • "Development Relaxed" — allow high-severity findings, + single approver, faster iteration + • "Compliance SOC2" — specific controls for SOC 2 certification + + Each pack contains rules written in Stella DSL (a policy language) + that are evaluated automatically during promotions. + + [Create Pack →] [Import Pack →] [Browse Templates →] + ``` + +--- + +### 24. Scheduled Jobs (`/ops/operations/jobengine`) +**Current state**: ✅ Good — has explanatory sections +- Shows job stats, execution quotas, dead-letter recovery, access info + +**Recommendations**: +1. **Add context for "No jobs submitted yet"**: + > "Jobs are created automatically when releases are promoted, scans are triggered, or scheduled tasks run. You can also create manual jobs for one-off operations." + +--- + +### 25. Feeds & Airgap (`/ops/operations/feeds-airgap`) +**Current state**: ⚠️ Shows feed sources, minimal context +- Shows NVD Mirror and OSV Mirror with sync status +- Tabs: Advisory Mirrors, Airgap Bundles, Vendor Links, Offline Kit + +**Recommendations**: +1. **Page-level explainer**: + ``` + ADVISORY FEEDS & OFFLINE OPERATIONS + + Stella continuously syncs vulnerability databases from multiple sources + to match against your scanned images: + + • NVD (National Vulnerability Database) — US government CVE database + • OSV (Open Source Vulnerabilities) — Google's aggregated OSV database + • Additional sources configurable per your region/compliance needs + + AIRGAP MODE + For environments without internet access, Stella can package everything + needed for offline operation: + • Vulnerability databases (frozen at export time) + • Container images for Stella services + • Scanner analyzers and detection rules + • CLI tools and task packs + + Feed freshness directly impacts scan accuracy. Stale feeds = missed + vulnerabilities. The "Staleness Budget" setting controls how old feeds + can be before promotions are blocked. + ``` + +--- + +### 26. Agent Fleet (`/ops/operations/agents`) +**Current state**: ❌ Very sparse empty state +- "No groups for current filters." +- Two tabs (Agents, Approvals) with no context + +**Recommendations**: +1. **Replace empty state**: + ``` + No Deployment Agents Configured + + Agents are lightweight services you deploy on your target hosts + (Docker hosts, VM clusters, etc.) that execute deployments on + behalf of Stella Ops. + + How agents work: + 1. You install an agent on each deployment target + 2. The agent registers with Stella and joins an agent group + 3. When a release is promoted, Stella sends deployment instructions + 4. The agent executes docker-compose up/docker run on the target + 5. Results are reported back with full evidence capture + + Agent types: + • Docker Compose — for compose-based deployments + • Docker Direct — for standalone container management + • SSH/WinRM — for remote host management + + [Deploy First Agent →] [Download Agent →] [View Agent Docs →] + ``` + +--- + +### 27. Signals (`/ops/operations/signals`) +**Current state**: ⚠️ Shows runtime data, no explanation +- Shows probe health per host with HEALTHY/DEGRADED status + +**Recommendations**: +1. **Page-level explainer**: + ``` + RUNTIME SIGNALS + + Signals are runtime probes deployed alongside your containers that + collect execution data for reachability analysis. They observe which + code paths your applications actually use in each environment. + + This powers the "Dynamic" layer of reachability analysis: + • Which functions are called at runtime? + • What network connections are made? + • Which library entry points are exercised? + + Combined with static analysis, signals help distinguish between + "this vulnerability exists in your code" and "this vulnerability + is actively reachable in production." + ``` + +--- + +### 28. Scripts (`/ops/scripts`) +**Current state**: ✅ Good — shows useful pre-configured scripts +- Pre-deploy Health Check, Database Migration Validator, Container Image Size Monitor + +**Recommendations**: +1. Add: "Scripts run as part of deployment workflows. You can create custom scripts for pre-deploy checks, post-deploy validation, or scheduled maintenance." + +--- + +### 29. Diagnostics (`/ops/operations/doctor`) +**Current state**: ✅ Excellent — comprehensive health checks +- Shows all services with individual check results + +**Recommendations**: +1. **Promote in onboarding**: "This is your first stop when something seems wrong. Doctor runs 100+ health checks across all platform services." +2. **Add severity guide**: "🟢 Pass = service is healthy. 🔴 Fail = needs attention. Click any check for remediation steps." +3. **Add "Run Full Diagnostic" prominent button** for first-time users + +--- + +### 30. Integrations (`/setup/integrations`) +**Current state**: ✅ Good — has "Suggested Setup Order" +- Shows numbered setup sequence: SCM → Registries → Scanner → Release → Notify + +**Recommendations**: +1. **Enhance setup order descriptions**: + ``` + SUGGESTED SETUP ORDER + + 1. 🔗 Registries (FIRST) + Connect where your container images live (Docker Hub, Harbor, + GitHub Container Registry, AWS ECR, etc.) + → This lets Stella discover and scan your images + + 2. 📦 Source Control + Connect your Git repositories (Gitea, GitHub, GitLab) + → Enables automated scanning on push and PR comments + + 3. 🔍 Scanner Config + Configure scan depth, language analyzers, and secret detection + → Customizes what Stella looks for inside your images + + 4. 🚀 Release Controls + Set up environments, promotion paths, and approval policies + → Defines your release pipeline gates + + 5. 📢 Notifications + Configure alerts (Slack, email, webhook) for scan results, + approvals, and deployment events + → Keeps your team informed without checking the UI + ``` + +--- + +### 31. Identity & Access (`/setup/identity-access`) +**Current state**: ⚠️ Shows user table, minimal guidance +- Has tabs: Users, Roles, OAuth Clients, API Tokens, Tenants + +**Recommendations**: +1. **Role descriptions**: When clicking Roles tab, show what each built-in role can do: + ``` + BUILT-IN ROLES + + • Admin — Full platform access. Can manage users, integrations, and trust. + • Operator — Can create releases, approve promotions, manage scans. + • Viewer — Read-only access to all dashboards and evidence. + • Auditor — Read-only + evidence export + audit log access. + • Developer — Can submit scans and view findings for their projects. + + 💡 Separation of Duties: For production promotions, the person who + creates a release should NOT be the same person who approves it. + ``` + +--- + +### 32. Certificates & Trust (`/setup/trust-signing`) +**Current state**: ⚠️ Shows signing keys, technical +- Shows one active signing key with algorithm and status + +**Recommendations**: +1. **Page-level explainer**: + ``` + SIGNING & TRUST + + Stella signs everything — scans, decisions, evidence, deployments — + with cryptographic signatures. This proves that evidence hasn't been + tampered with and came from your Stella installation. + + Signing Keys: Used to create DSSE (Dead Simple Signing Envelope) + signatures on evidence bundles. Rotate periodically. + + Trusted Issuers: External parties whose VEX statements or advisories + you trust. Each issuer has a trust score. + + Certificates: mTLS certificates for service-to-service communication + and client authentication. + + ⚠️ Key rotation: When you rotate a key, both old and new keys remain + valid during the transition period. Old evidence remains verifiable. + ``` + +--- + +### 33. Theme & Branding (`/setup/tenant-branding`) +**Current state**: ✅ Self-explanatory + +--- + +### 34. User Preferences (`/setup/preferences`) +**Current state**: ✅ Self-explanatory + +--- + +## CROSS-CUTTING IMPROVEMENTS + +### A. Global Help System + +**A1. Contextual Help Button (?) in Header** +Every page should have a `(?)` button in the header that opens a slide-out panel with: +- What this page is for (1 paragraph) +- Key concepts used on this page +- Common actions with step-by-step guidance +- Link to detailed documentation + +**A2. Glossary Tooltip System** +First occurrence of any domain term on a page should be underline-dotted with hover tooltip: +- SBOM, VEX, CVE, Reachability, Decision Capsule, Gate, Promotion, Digest, Attestation, DSSE, Evidence, Finding, Policy Pack, Risk Budget, Shadow Mode, Baseline, Feed, Agent, Signal, etc. + +**A3. Ctrl+K Command Palette Enhancement** +The command palette should include help commands: +- "help: what is SBOM" → shows definition +- "help: how to scan" → shows guided workflow +- "help: troubleshoot deployment" → shows diagnostic steps +- "guide: first setup" → launches setup wizard + +### B. Status Bar Education + +The bottom status bar shows: Events, Policy, Evidence, Feed, Offline +Each indicator should have an expanded tooltip: + +- **Events: Connected** → "Real-time event stream is active. Platform changes appear instantly across all dashboards." +- **Policy: No baseline** → "⚠️ No active policy pack is set as baseline. Without a baseline, releases won't be checked against security rules. [Set a baseline →]" +- **Evidence: ON** → "Evidence signing is active. All scans, decisions, and deployments are cryptographically signed." +- **Feed: Live** → "Advisory feeds are syncing normally. Your vulnerability data is current." +- **Offline: OK** → "Platform is connected to the internet. Advisory feeds and license validation are using live data." + +### C. Empty State Design System + +Every empty state should follow this pattern: +``` +[Relevant Icon — not raw Material icon names!] + +[What this section shows when populated] + +[Why it's empty right now] + +[Exactly what to do to populate it — with direct action buttons] + +[Link to learn more] +``` + +**Never show**: Raw icon names as text (e.g., "event_busy"), generic "no data" messages, or empty tables without context. + +### D. First-Time Setup Wizard + +A guided wizard that appears on first login (or is accessible from Dashboard): + +``` +WELCOME TO STELLA OPS — LET'S GET YOU SET UP + +Step 1 of 6: Run Diagnostics + "Let's make sure all platform services are healthy." + [Run Doctor →] + +Step 2 of 6: Connect Your First Registry + "Where do your container images live?" + [Connect Registry →] + +Step 3 of 6: Scan Your First Image + "Let's see what's inside one of your images." + [Scan Image →] + +Step 4 of 6: Review Your Findings + "Here's what Stella found. Let's triage the critical ones." + [Open Triage →] + +Step 5 of 6: Create Your First Release + "Bundle your verified image into a tracked release." + [Create Release →] + +Step 6 of 6: Set Up a Policy Pack + "Define the security rules for your environments." + [Configure Policy →] + +🎉 You're ready! Check the Operations Hub daily for items needing attention. +``` + +### E. "Day in the Life" Quick Actions (Dashboard) + +Replace the current generic "Quick Links" section with role-based daily workflows: + +``` +YOUR DAILY CHECKLIST +☐ Check Operations Hub for blocking issues +☐ Review pending approvals (2 pending) +☐ Verify feed freshness (last sync: 2 hours ago ✅) +☐ Triage new critical findings (3 new since yesterday) +☐ Check environment health +``` + +### F. Sidebar Menu Improvements + +**F1. Section descriptions** (shown when hovering section headers): +- **Release Control**: "Manage your deployment pipeline: create releases, approve promotions, monitor environments" +- **Security**: "Scan containers, triage vulnerabilities, assess reachability, manage VEX statements" +- **Evidence**: "Browse signed audit trails, decision capsules, and exportable compliance bundles" +- **Operations**: "Platform health, scheduled jobs, advisory feeds, deployment agents, diagnostics" +- **Settings**: "Integrations, users, certificates, branding, and preferences" + +**F2. Badge explanations**: The "2" badge on Deployments should have tooltip: "2 deployments pending approval" + +**F3. Recommended first visit order**: On first login, subtly highlight the recommended navigation path (Diagnostics → Integrations → Scan Image → Dashboard) + +### G. Contextual "What Should I Do?" Panels + +On pages with actionable data, add a collapsible "What to do next" section: + +- **Dashboard with criticals**: "You have 3 critical vulnerabilities. Start by opening the Vulnerabilities page to triage them. Critical = remotely exploitable, fix first." +- **Release with BLOCK gate**: "This release is blocked by gate failures. Click 'Review Gates' to see which rules failed and what needs to change." +- **Environment showing UNKNOWN**: "Health is unknown because no agent is reporting from this environment. Deploy an agent to start monitoring." + +--- + +## Delivery Tracker + +### T0a - Stella Helper Core (Clippy-Style Contextual Guide) +Status: DONE +Dependency: none +Owners: Frontend Developer + +Implemented the Win97 Clippy-inspired animated mascot with speech bubble, page-level tips, tip cycling, dismiss/restore, idle animations. + +**Files:** +- `shared/components/stella-helper/stella-helper.component.ts` — Animated mascot + speech bubble +- `shared/components/stella-helper/stella-helper-tips.config.ts` — 35 page configs, 100+ tips +- `layout/app-shell/app-shell.component.ts` — Integration into app shell + +Completion criteria: +- [x] Animated mascot with speech bubble, entrance animation, idle bounce/wiggle/peek +- [x] Page-aware tip switching via Router, first-visit auto-open +- [x] 100+ tips across 35+ page configs with action buttons +- [x] Dismissable/restorable with localStorage persistence +- [x] Build passes, visually verified on Dashboard and VEX pages + +### T0b - Stella Helper Deep Context (Tab, Alert, State Awareness) +Status: TODO +Dependency: T0a +Owners: Frontend Developer + +Deepen the helper so tips respond to the EXACT context the user is in — not just which page, but which tab, what alerts are showing, what state the data is in. This is what makes the helper truly useful vs. generic. + +**Architecture changes needed:** +1. `StellaHelperContextService` — injectable service that page/tab components push context signals to +2. Enhanced route resolution — tab-level URL matching (e.g., `/ops/policy/vex/consensus` gets consensus-specific tips, not just VEX tips) +3. Reactive tip injection — components can push `{ context: 'sbom-missing' }` and the helper reacts with a relevant tip +4. Priority tip system — alert-driven tips take priority over generic page tips + +**Tab-level tips to add (every tab on every tabbed page):** + +VEX & Exceptions (8 tabs): +- Dashboard: VEX overview, what the status cards mean, why everything is zero +- Search: how to find existing VEX statements, search syntax +- Create: step-by-step VEX creation workflow, required fields, justification +- Stats: what the statistics measure, trends to watch +- Consensus: how multi-source VEX consensus works, trust weighting +- Explorer: browsing raw VEX data, linking to advisories +- Conflicts: what conflicts mean, how to resolve provider disagreements +- Exceptions: policy exception workflow, approval requirements, expiry + +Policy Governance (5+ tabs): +- Risk Budget: what budget means, thresholds, how to adjust +- Profiles: what risk profiles are, how they map to environments +- Configuration: sealed mode, staleness, trust weights explained +- Conflicts: policy rule conflicts, resolution strategies +- Developer Tools: schema playground, validators, impact preview + +Policy Simulation (6 tabs): +- Shadow Mode: what it does, how to interpret results +- Promotion Gate: simulating gate outcomes before real promotion +- Test & Validate: testing rules against sample data +- Pre-Promotion Review: previewing what would happen on promote +- Effective Policies: the final merged policy view +- Exceptions: exemptions and their impact on simulation + +Deployments (2 tabs): +- Pipeline: what runs are, status meanings, filtering +- Approvals: approval workflow, what to review before approving + +Releases (2 tabs): +- Releases: release list, column meanings, actions +- Versions: version history, version vs release difference + +Evidence Audit Log (4 tabs): +- Overview: event categories, what gets captured +- Events: filtering and searching events, export +- Timeline: chronological visualization, pattern detection +- Correlation: linking related events across modules + +Certificates & Trust (3 tabs): +- Signing Keys: key management, rotation, algorithms +- Trusted Issuers: external trust, scores, verification +- Certificates: mTLS, client certs, renewal + +Identity & Access (5 tabs): +- Users: user management, least privilege +- Roles: RBAC, built-in roles, custom roles +- OAuth Clients: service-to-service auth, client credentials +- API Tokens: CI/CD tokens, scoping, rotation +- Tenants: multi-tenancy, isolation, context switching + +Integrations (7 tabs): +- Mail: notification delivery setup +- Registries: container registry connections, auto-discovery +- SCM: source control linking, webhook configuration +- CICD: CI pipeline integration, scan triggers +- Runtime/Hooks: runtime probe deployment, webhook receivers +- Advisory & VEX: advisory source configuration +- Secrets: vault connections, sealed secrets + +Export Center (2 tabs): +- Profiles: export profile configuration, what each includes +- Export Runs: run history, download, scheduling + +Findings Explorer (4 sections): +- Governance: policy impact view of findings +- Security: technical vulnerability details +- Audit: evidence and decision history per finding +- Export: generating finding reports + +Agent Fleet (2 tabs): +- Agents: agent health, group management, deployment +- Approvals: deployment approvals from agent perspective + +**Alert/state-driven tips:** +- SBOM: missing on any environment → "Your environments show SBOM: missing. This means no container images have been scanned for this environment yet. [Scan Image →]" +- Risk: CRITICAL → "Critical risk detected. This means exploitable vulnerabilities with high severity were found. Open the finding to start triage." +- Gates: BLOCK → "A release gate is blocking promotion. Click 'Review Gates' to see which policy rule failed and what evidence is needed." +- Budget threshold exceeded → "Your risk budget is over 70%. This means accumulated security debt is approaching the organizational limit. Focus on triaging top contributors." +- Feed: stale → "Advisory feeds haven't synced recently. Stale feeds mean new vulnerabilities won't be detected. Check Feeds & Airgap." +- Policy: No baseline → "No policy baseline is set. Without a baseline, releases won't be checked against security rules. Set one in Policy Packs." +- Evidence: Missing → "This release has no Decision Capsule. Evidence is generated when you scan and promote. Without it, the release can't be audited." +- Agent: none connected → "No deployment agents are connected. Without agents, Stella can't deploy releases to target hosts." +- Health: unknown → "Environment health is unknown because no monitoring data is being received. Deploy a signal probe or agent." +- 0 total on any stat card → contextual "This is zero because [reason]. To populate: [action]." + +**Implementation approach:** +1. Add `StellaHelperContextService` with signal-based context injection +2. Expand `resolvePageKey()` with 60+ additional sub-route keys for tabs +3. Add `StellaHelperTip.contextTrigger?: string` field for state-driven tips +4. Helper component subscribes to context service + route changes +5. Priority: context-triggered tips > tab-specific tips > page-level tips + +Completion criteria: +- [ ] 60+ tab-level route configs added to tips config +- [ ] `StellaHelperContextService` created with context signal injection +- [ ] Alert-driven tips for 10+ common platform states (SBOM missing, gate blocked, feed stale, etc.) +- [ ] Priority system: alert tips surface above generic tips +- [ ] Tab components push context on activation +- [ ] Every tabbed page has per-tab tips (not just page-level) +- [ ] Total tip count reaches 250+ + +### T1 - First-Time Setup Wizard Component +Status: TODO +Dependency: none +Owners: Frontend Developer + +Create a step-by-step setup wizard component that guides new users through initial platform configuration. Should be dismissable, remember completion state per user, and be re-accessible from Settings. + +Completion criteria: +- [ ] Wizard component with 6 steps (diagnostics, registry, scan, triage, release, policy) +- [ ] Each step links to the actual page/action +- [ ] Progress persisted in user preferences +- [ ] Accessible from Dashboard "Getting Started" card and Settings + +### T2 - Dashboard Welcome Banner & Contextual Hints +Status: TODO +Dependency: none +Owners: Frontend Developer + +Add first-visit welcome banner, severity guide, metric tooltips, and "What should I do next?" cards to the Dashboard. + +Completion criteria: +- [ ] Dismissable welcome banner for first visit +- [ ] (?) tooltips on SBOM, Reachability, Feed Status, all vulnerability metrics +- [ ] "What should I do next?" card appears when actionable items exist +- [ ] Severity guide (Critical/High/Medium/Low) shown on first visit + +### T3 - Empty State Overhaul (All Pages) +Status: TODO +Dependency: none +Owners: Frontend Developer + +Replace all generic/broken empty states with educational content following the design system pattern: icon + explanation + action + learn more. + +Completion criteria: +- [ ] Fix "event_busy" text bug on Deployments page +- [ ] Readiness: fix grammar + add helpful empty state +- [ ] Supply-Chain Data: add SBOM explanation + scan CTA +- [ ] Agent Fleet: add agent explanation + deploy CTA +- [ ] Unknowns: add explanation + zero-state positive message +- [ ] Policy Audit: add event type guide +- [ ] All empty tables show contextual help, not just "no data" + +### T4 - Domain Glossary Tooltip System +Status: TODO +Dependency: none +Owners: Frontend Developer + +Create a shared tooltip directive that detects domain terms (SBOM, VEX, CVE, etc.) and provides inline definitions on hover. Sourced from a central glossary config. + +Completion criteria: +- [ ] Glossary config with 25+ domain terms and definitions +- [ ] Angular directive or pipe that wraps first occurrence with tooltip +- [ ] Works across all pages without per-page configuration +- [ ] Definitions written for a developer audience (not security experts) + +### T5 - Page-Level Help Panels +Status: TODO +Dependency: none +Owners: Frontend Developer + +Add collapsible "About this page" sections to all 30 main pages. Each explains: what this page is for, key concepts, common actions, and links to docs. + +Completion criteria: +- [ ] Help content for all pages (text from this sprint's audit findings) +- [ ] Collapsible UI component (expanded by default on first visit, collapsed after) +- [ ] Consistent placement (below page title, above content) +- [ ] Per-page help state persisted in user preferences + +### T6 - Status Bar Tooltips +Status: TODO +Dependency: none +Owners: Frontend Developer + +Enhance the bottom status bar indicators (Events, Policy, Evidence, Feed, Offline) with educational tooltips and actionable warnings. + +Completion criteria: +- [ ] Each indicator has tooltip explaining what it means +- [ ] Warning states include actionable guidance (e.g., "Policy: No baseline → [Set a baseline →]") +- [ ] Tooltips written for non-expert audience + +### T7 - VEX & Reachability Education Pages +Status: TODO +Dependency: none +Owners: Frontend Developer + +The two most confusing concepts (VEX and Reachability) need substantial inline education. Add collapsible explainer panels with diagrams/examples. + +Completion criteria: +- [ ] VEX page: full explainer (what, why, statuses, workflow, getting started) +- [ ] Reachability page: full explainer (what, hybrid approach, coverage, why it matters) +- [ ] Decision Capsules page: full explainer (what's inside, why it matters) +- [ ] Findings Explorer: baseline explanation and guided first action + +### T8 - Integrations Setup Order Enhancement +Status: TODO +Dependency: none +Owners: Frontend Developer + +Enhance the existing "Suggested Setup Order" on the Integrations page with richer descriptions, icons, and direct links to each setup action. + +Completion criteria: +- [ ] Each setup step has icon, description, and "why" explanation +- [ ] Each step links directly to the relevant setup page +- [ ] Completion state shown (✅ Done / ⚪ Not started) + +### T9 - Sidebar & Menu Context +Status: TODO +Dependency: none +Owners: Frontend Developer + +Add section-level descriptions, badge tooltips, and first-visit navigation guidance to the sidebar. + +Completion criteria: +- [ ] Section headers have hover descriptions +- [ ] Badges have tooltips explaining count meaning +- [ ] Optional "Recommended for new users" highlight on first login + +### T10 - Ctrl+K Command Palette Help Integration +Status: TODO +Dependency: T4 +Owners: Frontend Developer + +Extend the Ctrl+K command palette with help/guide commands that surface glossary definitions and guided workflows. + +Completion criteria: +- [ ] "help: [term]" commands for all glossary terms +- [ ] "guide: first setup" launches setup wizard +- [ ] "guide: scan image" shows step-by-step +- [ ] Help results appear inline in palette results + +--- + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-29 | Sprint created. Full UI audit completed across 34 screens with screenshots. Comprehensive findings documented with specific recommendations per screen. | Planning | +| 2026-03-29 | T0 DONE: Stella Helper (Clippy) implemented and integrated. 35 page configs, 100+ tips, animated mascot with speech bubble. Build passes, visually verified on Dashboard and VEX pages. | Developer | + +## Decisions & Risks +- **Decision**: All educational content should be written for a developer audience (not security experts). Use analogies and practical examples. +- **Decision**: Help panels should be collapsible and remember state — don't force experts to dismiss them every time. +- **Decision**: First-visit detection should use user preferences API, not local storage, so it works across devices. +- **Decision**: Stella Helper (Clippy) is the PRIMARY onboarding vehicle. All other tasks (empty states, glossary, status bar, etc.) are complementary — they make each page self-documenting, while the helper provides proactive guidance. +- **Decision**: Deep contextual tips (T0b) should use a service + signal pattern so any component can push context to the helper. This avoids tight coupling while allowing rich state-awareness. +- **Risk**: Content volume is large (30+ pages, 80+ tabs, 250+ tips). Mitigate by: writing all content in the tips config first (data layer), then implementing features in phases. +- **Risk**: Glossary tooltip system (T4) needs careful UX — too many tooltips = visual noise. Only annotate first occurrence per page. +- **Risk**: Helper context service (T0b) could create performance overhead if too many components push signals. Use debounce and single-signal-per-page pattern. + +## Task Interconnection Map + +``` +T0a (Clippy Core) ──DONE──┐ + ├──► T0b (Deep Context: tabs, alerts, state) +T4 (Glossary)──────────────┤ │ + │ ├──► Stella Helper becomes THE onboarding system +T6 (Status Bar)────────────┘ │ + │ +T1 (Setup Wizard) ──────────────────►│ (wizard progress shown via helper too) +T2 (Dashboard Hints) ──────────────►│ (dashboard tips in helper + inline hints) +T3 (Empty States) ─────────────────►│ (empty states trigger helper context) +T5 (Page Help Panels) ─────────────►│ (help panels are static; helper is interactive) +T7 (VEX/Reachability Education) ───►│ (inline education + helper tips) +T8 (Integrations Setup) ──────────►│ (setup guidance + helper tips) +T9 (Sidebar Context) ─────────────►│ (sidebar tooltips complement helper) +T10 (Ctrl+K Help) ────────────────►│ (palette surfaces same glossary as T4) +``` + +All 12 tasks work together. The Stella Helper (T0a+T0b) is the PROACTIVE guide ("here's what you need to know"). The other tasks are REACTIVE aids ("hover/click to learn more"). Together they create a self-teaching UI. + +## Phasing (execution order) + +### Phase 0 — DONE +- [x] T0a: Stella Helper Core (mascot, 100+ tips, page awareness) + +### Phase 1 — Highest Impact (next) +- [ ] T0b: Deep contextual tips (tabs, alerts, state-driven tips, 250+ total) +- [ ] T3: Empty state overhaul (fix bugs like "event_busy", add educational empty states) +- [ ] T2: Dashboard welcome banner + inline metric hints + +### Phase 2 — Structure +- [ ] T7: VEX & Reachability inline education (the hardest concepts need dedicated panels) +- [ ] T1: First-time setup wizard (6-step guided setup) +- [ ] T5: Page-level help panels (collapsible "About this page" on all 30 pages) +- [ ] T8: Integrations setup order enhancement + +### Phase 3 — Polish & System +- [ ] T4: Domain glossary tooltip system (25+ terms, auto-annotate first occurrence) +- [ ] T6: Status bar educational tooltips +- [ ] T9: Sidebar section descriptions + badge tooltips +- [ ] T10: Ctrl+K command palette help commands (depends on T4 glossary)