From b521b5bde82aed073543c6822f5e1c0a14a58371 Mon Sep 17 00:00:00 2001
From: master <>
Date: Sun, 8 Mar 2026 12:41:09 +0200
Subject: [PATCH] feat(ui): ship evidence capsules cutover
---
..._FE_evidence_capsules_canonical_cutover.md | 95 ++++
.../evidence-capsules-canonical-cutover-ui.md | 54 ++
docs/modules/ui/TASKS.md | 4 +
.../README.md | 46 ++
docs/modules/ui/implementation_plan.md | 2 +
src/Web/StellaOps.Web/src/app/app.routes.ts | 12 +
.../ai-runs/ai-run-viewer.component.ts | 10 +-
.../evidence-pack-list.component.ts | 23 +-
.../evidence-pack-viewer.component.ts | 90 +++-
.../evidence-capsules-cutover.spec.ts | 346 +++++++++++++
.../e2e/evidence-capsules-cutover.spec.ts | 477 ++++++++++++++++++
11 files changed, 1145 insertions(+), 14 deletions(-)
create mode 100644 docs-archived/implplan/SPRINT_20260308_011_FE_evidence_capsules_canonical_cutover.md
create mode 100644 docs/features/checked/web/evidence-capsules-canonical-cutover-ui.md
create mode 100644 docs/modules/ui/evidence-capsules-canonical-cutover/README.md
create mode 100644 src/Web/StellaOps.Web/src/tests/evidence/evidence-capsules-cutover.spec.ts
create mode 100644 src/Web/StellaOps.Web/tests/e2e/evidence-capsules-cutover.spec.ts
diff --git a/docs-archived/implplan/SPRINT_20260308_011_FE_evidence_capsules_canonical_cutover.md b/docs-archived/implplan/SPRINT_20260308_011_FE_evidence_capsules_canonical_cutover.md
new file mode 100644
index 000000000..b6442efc2
--- /dev/null
+++ b/docs-archived/implplan/SPRINT_20260308_011_FE_evidence_capsules_canonical_cutover.md
@@ -0,0 +1,95 @@
+# Sprint 20260308_011_FE - Evidence Capsules Canonical Cutover
+
+## Topic & Scope
+- Restore the usable decision-capsule workflow under the canonical Evidence shell instead of leaving it split between working components and dead legacy paths.
+- Make `/evidence/capsules` and `/evidence/capsules/:capsuleId` the only operator-facing owner routes for evidence-pack browsing, while preserving stale `/evidence-packs*` bookmarks.
+- Complete the cross-shell handoffs so AI Runs and release/evidence contexts deep-link into capsules with deterministic return-to behavior and an actionable related-run jump.
+- Working directory: `src/Web/StellaOps.Web`.
+- Expected evidence: focused Angular route/component tests, browser verification, updated UI docs, archived sprint.
+
+## Dependencies & Concurrency
+- Builds on the shipped Evidence shell, workflow-visualization run workspace, and contextual route-state utilities already present in `src/Web/StellaOps.Web`.
+- Safe to implement in parallel with unrelated backend or Router work as long as edits stay inside `src/Web/StellaOps.Web` and scoped UI docs.
+
+## Documentation Prerequisites
+- `docs/modules/ui/README.md`
+- `docs/modules/ui/implementation_plan.md`
+- `docs/modules/ui/component-preservation-map/RESTORATION_PRIORITIES.md`
+- `docs/modules/platform/architecture-overview.md`
+
+## Delivery Tracker
+
+### FE-EC-001 - Canonical capsule owner route and alias repair
+Status: DONE
+Dependency: none
+Owners: Developer / Implementer
+Task description:
+- Preserve the current Evidence shell as the owner of decision capsules and repair the stale route contract that still points live components at `/evidence-packs/:id`.
+- Add bookmark-safe alias handling for legacy evidence-pack paths so operators and old links land on the canonical capsule detail route without dropping query state.
+
+Completion criteria:
+- [x] Live components navigate to `/evidence/capsules` and `/evidence/capsules/:capsuleId`.
+- [x] Legacy `/evidence-packs` aliases redirect to canonical capsule routes while preserving query params and fragments.
+- [x] The capsule list/detail flow is discoverable and usable from the live Evidence shell.
+
+### FE-EC-002 - Cross-shell handoffs and related-run navigation
+Status: DONE
+Dependency: FE-EC-001
+Owners: Developer / Implementer
+Task description:
+- Complete the worthwhile behavior from the dropped evidence/proof surfaces by wiring cross-shell entry points into the canonical capsule detail route with deterministic return-to context.
+- Ensure the capsule viewer can jump to the related owner workflow instead of the stale AI-run-only path, using the active Releases run workspace when the pack represents release evidence.
+
+Completion criteria:
+- [x] AI Runs and other current entry points deep-link into canonical capsule detail routes with a valid return-to contract.
+- [x] Capsule detail provides a usable back action to the originating context or canonical capsule list.
+- [x] Related-run navigation lands on a live owner route instead of a stale or orphaned path.
+
+### FE-EC-003 - Verification coverage for the cutover
+Status: DONE
+Dependency: FE-EC-002
+Owners: Developer / Implementer, Test Automation, QA
+Task description:
+- Add focused Angular tests for alias handling, canonical route hydration, and the related-run / return-to navigation behavior.
+- Add browser verification that proves both the live capsule flow and a legacy bookmark cut over correctly.
+
+Completion criteria:
+- [x] Targeted Angular tests cover the canonical capsule route contract and navigation behavior.
+- [x] Browser verification covers at least one live entry point plus one legacy alias.
+- [x] The scoped test suite passes deterministically.
+
+### FE-EC-004 - Docs sync, archive, and shipped-feature note
+Status: DONE
+Dependency: FE-EC-003
+Owners: Developer / Implementer, Documentation author
+Task description:
+- Document the canonical capsule owner route, alias rules, and cross-shell handoff behavior in the UI module docs.
+- Record the verified behavior in a checked-feature note, update the task board and implementation plan, then archive the sprint only after the delivery tasks are actually complete.
+
+Completion criteria:
+- [x] Module docs describe the canonical capsule workflow and alias contract.
+- [x] Checked-feature verification note records the actual commands and outcomes.
+- [x] Sprint is archived with all tasks marked `DONE`.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-08 | Sprint created and moved to DOING for the canonical evidence capsules cutover. | Implementer |
+| 2026-03-08 | Repaired the canonical Decision Capsule list and detail routes, added bookmark-safe `/evidence-packs*` aliases, and switched live capsule navigation away from the stale pack paths. | Implementer |
+| 2026-03-08 | Completed cross-shell handoffs from AI Runs and release evidence so capsule detail pages preserve `returnTo` context and open the live owner workspace for related runs. | Implementer |
+| 2026-03-08 | Verification passed: Angular targeted tests `1` file / `7` tests, Playwright `2` scenarios, and `npm run build` with existing bundle-budget warnings only. | Implementer |
+
+## Decisions & Risks
+- This sprint is intentionally bounded to the canonical capsule list/detail flow plus handoffs. Broader proof-chain or evidence-thread restoration should land in separate evidence-domain sprints.
+- Evidence packs come from more than one product area; related-run navigation must prefer live owner routes and avoid reintroducing dead `/evidence-packs` or orphaned `/ai-runs` paths.
+- Route alias handling must preserve query params and fragments so release-context and AI-run bookmarks remain deterministic.
+- Browser verification initially failed because the release-run evidence workspace fixture returned the base run detail object for sibling endpoints like `/approvals` and `/deployments`; the E2E harness was corrected to return the real per-endpoint shapes instead of weakening the assertion surface.
+- Verification commands:
+ - `npm run test -- --watch=false --include src/tests/evidence/evidence-capsules-cutover.spec.ts`
+ - `npx playwright test --config playwright.config.ts tests/e2e/evidence-capsules-cutover.spec.ts --workers=1`
+ - `npm run build`
+
+## Next Checkpoints
+- Canonical route and alias cutover complete with focused tests.
+- Cross-shell handoffs verified in browser.
+- Sprint archived and committed locally without unrelated files.
diff --git a/docs/features/checked/web/evidence-capsules-canonical-cutover-ui.md b/docs/features/checked/web/evidence-capsules-canonical-cutover-ui.md
new file mode 100644
index 000000000..05b665bea
--- /dev/null
+++ b/docs/features/checked/web/evidence-capsules-canonical-cutover-ui.md
@@ -0,0 +1,54 @@
+# Evidence Capsules Canonical Cutover UI
+
+## Module
+Web
+
+## Status
+VERIFIED
+
+## Description
+Shipped the canonical Decision Capsule flow under `Evidence`, repaired stale `/evidence-packs*` bookmarks, and completed the cross-shell handoffs so AI Runs and release evidence can open capsule detail pages and return to their live owner workspaces without dead ends.
+
+## Implementation Details
+- **Feature directories**:
+ - `src/Web/StellaOps.Web/src/app/features/evidence-pack/`
+ - `src/Web/StellaOps.Web/src/app/features/ai-runs/`
+ - `src/Web/StellaOps.Web/src/app/features/workflow-visualization/`
+- **Primary components**:
+ - `evidence-pack-list` (`src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-list.component.ts`)
+ - `evidence-pack-viewer` (`src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-viewer.component.ts`)
+ - `ai-run-viewer` (`src/Web/StellaOps.Web/src/app/features/ai-runs/ai-run-viewer.component.ts`)
+- **Canonical routes**:
+ - `/evidence/capsules`
+ - `/evidence/capsules/:capsuleId`
+- **Legacy aliases**:
+ - `/evidence-packs`
+ - `/evidence-packs/:capsuleId`
+- **Secondary entry points**:
+ - `Ops > Operations > AI Runs`
+ - `Releases > Runs > Evidence`
+
+## E2E Test Plan
+- **Setup**:
+ - [x] Start the local Angular test server with `npm run serve:test`.
+ - [x] Use a test session with ops, release, policy, and signer scopes.
+- **Core verification**:
+ - [x] Verify AI Run detail opens canonical Decision Capsule detail with a usable back action.
+ - [x] Verify Decision Capsule detail opens the live related-run workspace, not a stale route.
+- **Legacy verification**:
+ - [x] Verify `/evidence-packs/:capsuleId` bookmarks land on `/evidence/capsules/:capsuleId`.
+ - [x] Verify the legacy bookmark can continue into the canonical release evidence workspace.
+
+## Verification
+- Run:
+ - `npm run test -- --watch=false --include src/tests/evidence/evidence-capsules-cutover.spec.ts`
+ - `npx playwright test --config playwright.config.ts tests/e2e/evidence-capsules-cutover.spec.ts --workers=1`
+ - `npm run build`
+- Tier 0 (source): pass
+- Tier 1 (build/tests): pass
+- Tier 2 (behavior): pass
+- Notes:
+ - Angular targeted tests passed: `1` file, `7` tests.
+ - Playwright passed: `2` scenarios.
+ - Production build passed; existing bundle-budget warnings remain unchanged from the baseline.
+- Verified on (UTC): 2026-03-08T10:37:03Z
diff --git a/docs/modules/ui/TASKS.md b/docs/modules/ui/TASKS.md
index c36deba12..3e471a91d 100644
--- a/docs/modules/ui/TASKS.md
+++ b/docs/modules/ui/TASKS.md
@@ -115,6 +115,10 @@
- [DONE] FE-RP-002 Wire release-context handoff into the canonical promotion wizard
- [DONE] FE-RP-003 Verify route cutover and usable promotion request workflow
- [DONE] FE-RP-004 Sync docs, archive the sprint, and record the shipped feature
+- [DONE] FE-EC-001 Repair canonical capsule ownership and preserve `/evidence-packs*` aliases
+- [DONE] FE-EC-002 Complete cross-shell capsule handoffs and related-run navigation
+- [DONE] FE-EC-003 Verify route cutover and usable capsule workflow
+- [DONE] FE-EC-004 Sync docs, archive the sprint, and record the shipped feature
- [DONE] FE-PO-001 Freeze Operations overview taxonomy and submenu structure
- [DONE] FE-PO-002 Overview page regrouping and blocking-card contract
- [DONE] FE-PO-003 Legacy widget absorption matrix for Platform Ops
diff --git a/docs/modules/ui/evidence-capsules-canonical-cutover/README.md b/docs/modules/ui/evidence-capsules-canonical-cutover/README.md
new file mode 100644
index 000000000..02bfc6c0a
--- /dev/null
+++ b/docs/modules/ui/evidence-capsules-canonical-cutover/README.md
@@ -0,0 +1,46 @@
+# Evidence Capsules Canonical Cutover
+
+## Purpose
+- Keep Decision Capsules owned by the live `Evidence` shell instead of splitting them across canonical routes, stale legacy bookmarks, and context-specific dead ends.
+- Finish the usable workflow, not just the references: list, detail, back-navigation, related-run handoff, and bookmark repair all need to work for operators.
+
+## Canonical Routes
+- `/evidence/capsules`
+- `/evidence/capsules/:capsuleId`
+
+## Alias Policy
+- Preserve `/evidence-packs`
+- Preserve `/evidence-packs/:capsuleId`
+- Redirect aliases into the canonical `/evidence/capsules*` subtree while preserving query params and fragments.
+
+## Shell Ownership
+- `Evidence` remains the only operator-facing owner of Decision Capsule browsing.
+- The capsule list uses Decision Capsule terminology consistently and opens detail pages inside the canonical Evidence shell.
+- Capsule detail exposes a back action that prefers the originating context and falls back to the canonical capsule list.
+
+## Cross-Shell Handoffs
+- `Ops > Operations > AI Runs` opens canonical capsule detail routes with a deterministic `returnTo` contract.
+- Capsule detail routes related AI-generated evidence back into `/ops/operations/ai-runs/:runId`.
+- Capsule detail routes release evidence into `/releases/runs/:runId/evidence`.
+- Related-run handoffs always preserve a valid return path back to the canonical capsule detail page.
+
+## Merge Notes From Dropped Surfaces
+- The stale `/evidence-packs*` surface was not preserved as a second owner route.
+- The useful behavior from the half-wired pack flow was merged into the canonical Evidence shell:
+ - bookmark-safe alias repair
+ - context-aware back navigation
+ - live owner-route jumps for AI and release contexts
+
+## Verification
+- Angular tests cover:
+ - canonical capsule route ownership
+ - legacy alias redirects
+ - list/detail navigation behavior
+ - capsule viewer `returnTo` and related-run handoffs
+- Playwright covers:
+ - a live AI Runs entry point into capsule detail and back
+ - a legacy `/evidence-packs/:capsuleId` bookmark that cuts over into the live release evidence workspace
+
+## Related
+- `docs/features/checked/web/evidence-capsules-canonical-cutover-ui.md`
+- `docs/modules/ui/component-preservation-map/RESTORATION_PRIORITIES.md`
diff --git a/docs/modules/ui/implementation_plan.md b/docs/modules/ui/implementation_plan.md
index c1146f7d0..17cea5bc1 100644
--- a/docs/modules/ui/implementation_plan.md
+++ b/docs/modules/ui/implementation_plan.md
@@ -35,6 +35,7 @@ Provide a living plan for UI deliverables, dependencies, and evidence.
- `docs/features/checked/web/security-operations-leaves-ui.md` - shipped verification note for mission alerts/activity surfacing, unknowns route repair, notifications ownership, and legacy security alias cutover.
- `docs/features/checked/web/platform-setup-canonical-route-preservation-ui.md` - shipped verification note for preserved `/ops/platform-setup/*` URLs during the shared setup/topology cutover.
- `docs/features/checked/web/release-promotions-cutover-ui.md` - shipped verification note for canonical release promotions routing, alias cutover, release-context wizard handoff, and end-to-end request submission.
+- `docs/features/checked/web/evidence-capsules-canonical-cutover-ui.md` - shipped verification note for canonical Evidence-owned capsule routes, `/evidence-packs*` bookmark repair, and AI/release context handoffs.
- `docs/modules/ui/reachability-witnessing/README.md` - detailed witness and proof UX dossier plus cross-shell deep-link contract.
- `docs/modules/ui/platform-ops-consolidation/README.md` - detailed Operations overview taxonomy and legacy absorption plan.
- `docs/modules/ui/offline-operations/README.md` - detailed owner-shell contract for Offline Kit, Feeds & Airgap, Evidence handoffs, and stale alias policy.
@@ -44,6 +45,7 @@ Provide a living plan for UI deliverables, dependencies, and evidence.
- `docs/modules/ui/security-operations-leaves/README.md` - canonical owner contract for mission alerts/activity, security unknowns, notifications, and stale `/analyze`/`/notify` handoffs.
- `docs/modules/ui/platform-setup-canonical-route-preservation/README.md` - preserved route contract for canonical `/ops/platform-setup/*` leaves during the shared setup/topology cutover.
- `docs/modules/ui/release-promotions-cutover/README.md` - canonical promotions owner contract, alias rules, and release-context handoff for the Releases shell.
+- `docs/modules/ui/evidence-capsules-canonical-cutover/README.md` - canonical Evidence owner contract for Decision Capsule list/detail browsing, legacy bookmark aliases, and related-run handoffs.
- `docs/modules/ui/triage-explainability-workspace/README.md` - detailed artifact workspace and audit-bundle UX dossier.
- `docs/modules/ui/workflow-visualization-replay/README.md` - detailed run-detail graph, timeline, replay, and evidence UX dossier.
- `docs/modules/ui/contextual-actions-patterns/README.md` - shared placement contract for stray actions, pages, drawers, and tabs.
diff --git a/src/Web/StellaOps.Web/src/app/app.routes.ts b/src/Web/StellaOps.Web/src/app/app.routes.ts
index 699c95088..bd3de816d 100644
--- a/src/Web/StellaOps.Web/src/app/app.routes.ts
+++ b/src/Web/StellaOps.Web/src/app/app.routes.ts
@@ -347,6 +347,18 @@ export const routes: Routes = [
{ path: '**', redirectTo: '/evidence/overview' },
],
},
+ {
+ path: 'evidence-packs',
+ children: [
+ { path: '', redirectTo: preserveAppRedirect('/evidence/capsules'), pathMatch: 'full' },
+ {
+ path: ':capsuleId',
+ redirectTo: preserveAppRedirect('/evidence/capsules/:capsuleId'),
+ pathMatch: 'full',
+ },
+ { path: '**', redirectTo: preserveAppRedirect('/evidence/capsules') },
+ ],
+ },
{
path: 'security-risk',
children: [
diff --git a/src/Web/StellaOps.Web/src/app/features/ai-runs/ai-run-viewer.component.ts b/src/Web/StellaOps.Web/src/app/features/ai-runs/ai-run-viewer.component.ts
index 979e3f9c5..a72d9736e 100644
--- a/src/Web/StellaOps.Web/src/app/features/ai-runs/ai-run-viewer.component.ts
+++ b/src/Web/StellaOps.Web/src/app/features/ai-runs/ai-run-viewer.component.ts
@@ -35,6 +35,7 @@ import {
AttestationContent,
} from '../../core/api/ai-runs.models';
import { AI_RUNS_API } from '../../core/api/ai-runs.client';
+import { buildContextReturnTo } from '../../shared/ui/context-route-state/context-route-state';
@Component({
selector: 'stellaops-ai-run-viewer',
@@ -912,7 +913,14 @@ export class AiRunViewerComponent implements OnInit, OnChanges {
onNavigateToEvidencePack(packId: string): void {
this.navigateToEvidencePack.emit(packId);
- this.router.navigate(['/evidence-packs', packId]);
+ const currentRunId = this.runId ?? this.run()?.runId ?? '';
+ void this.router.navigate(['/evidence/capsules', packId], {
+ queryParams: currentRunId
+ ? {
+ returnTo: buildContextReturnTo(this.router, ['/ops/operations/ai-runs', currentRunId]),
+ }
+ : undefined,
+ });
}
formatEventType(type: string): string {
diff --git a/src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-list.component.ts b/src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-list.component.ts
index 81f19457e..f000e011f 100644
--- a/src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-list.component.ts
+++ b/src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-list.component.ts
@@ -31,7 +31,10 @@ import { ErrorStateComponent } from '../../shared/components/error-state/error-s
} @else {
@@ -157,6 +160,12 @@ import { ErrorStateComponent } from '../../shared/components/error-state/error-s
margin: 0;
}
+ .list-subtitle {
+ margin: 0.25rem 0 0;
+ font-size: 0.8rem;
+ color: var(--color-text-secondary);
+ }
+
.filters {
display: flex;
align-items: center;
@@ -393,7 +402,7 @@ export class EvidencePackListComponent implements OnInit {
this.loading.set(false);
},
error: (err) => {
- this.error.set(err.message || 'Failed to load evidence packs');
+ this.error.set(err.message || 'Failed to load decision capsules');
this.loading.set(false);
},
});
@@ -411,6 +420,8 @@ export class EvidencePackListComponent implements OnInit {
onSelect(pack: EvidencePackSummary): void {
this.packSelected.emit(pack);
- this.router.navigate(['/evidence-packs', pack.packId]);
+ void this.router.navigate(['/evidence/capsules', pack.packId], {
+ queryParams: { returnTo: this.router.url },
+ });
}
}
diff --git a/src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-viewer.component.ts b/src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-viewer.component.ts
index f0ab8c31a..72a405118 100644
--- a/src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-viewer.component.ts
+++ b/src/Web/StellaOps.Web/src/app/features/evidence-pack/evidence-pack-viewer.component.ts
@@ -11,6 +11,7 @@ import {
Input,
Output,
EventEmitter,
+ DestroyRef,
inject,
signal,
computed,
@@ -18,6 +19,7 @@ import {
OnInit,
SimpleChanges,
} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { CommonModule } from '@angular/common';
import { ActivatedRoute, Router } from '@angular/router';
import {
@@ -30,6 +32,7 @@ import {
} from '../../core/api/evidence-pack.models';
import { EVIDENCE_PACK_API } from '../../core/api/evidence-pack.client';
import { ErrorStateComponent } from '../../shared/components/error-state/error-state.component';
+import { buildContextReturnTo, readContextRouteParam } from '../../shared/ui/context-route-state/context-route-state';
@Component({
selector: 'stellaops-evidence-pack-viewer',
@@ -52,7 +55,10 @@ import { ErrorStateComponent } from '../../shared/components/error-state/error-s