Repair release investigation workspace contracts

docs/implplan/SPRINT_20260309_016_SbomService_release_investigation_workspace_contract_repair.md

@@ -0,0 +1,91 @@
+# Sprint 20260309_016 - Release Investigation Workspace Contract Repair
+
+## Topic & Scope
+- Replace the broken release-investigation route contract with a self-sufficient workspace that no longer depends on orphaned query params or dead API paths.
+- Restore canonical behavior for `/releases/investigation/deploy-diff` and `/releases/investigation/change-trace` on a fresh live stack where comparison data may be absent.
+- Keep the repair scoped to release-investigation surfaces, the SbomService compatibility layer they depend on, and the docs that describe the contract.
+- Working directory: `src/SbomService/`.
+- Allowed coordination edits: `src/Web/StellaOps.Web/src/app/features/deploy-diff/`, `src/Web/StellaOps.Web/src/app/features/change-trace/`, `src/Web/StellaOps.Web/scripts/`, `docs/features/checked/web/`, and `docs/modules/sbom-service/`.
+- Expected evidence: focused .NET tests, focused Angular tests, rebuilt `sbomservice` + web bundle, live Playwright recheck artifacts.
+
+## Dependencies & Concurrency
+- Depends on the current `stella-ops.local` compose stack already rebuilt from source on 2026-03-09.
+- Safe to run in parallel with unrelated search/runtime/auth work as long as those edits do not overwrite the touched release-investigation files.
+- Do not modify unrelated dirty files from other agents.
+
+## Documentation Prerequisites
+- `docs/modules/sbom-service/architecture.md`
+- `docs/features/checked/web/release-investigation-routes.md`
+- `docs/features/checked/web/a-b-deploy-diff-panel.md`
+- `docs/qa/feature-checks/FLOW.md`
+
+## Delivery Tracker
+
+### SBOM-RIW-001 - Define canonical workspace/default-context contract
+Status: DONE
+Dependency: none
+Owners: Product Manager, Developer
+Task description:
+- Replace the legacy assumption that the deploy-diff route is only valid when a caller injects `from` and `to` query parameters. The canonical Releases-owned workspace must remain useful when opened directly from the shell on a fresh setup.
+- Decide and document how the investigation pages behave when comparison data is unavailable in the live stack: they must show explicit product states and recovery paths, not placeholder errors.
+
+Completion criteria:
+- [ ] Release-investigation docs describe the new direct-load behavior and the live-data fallback behavior.
+- [ ] The selected contract is reflected consistently in both web and sbomservice implementations.
+
+### SBOM-RIW-002 - Rebase deploy diff on the live lineage compare contract
+Status: DONE
+Dependency: SBOM-RIW-001
+Owners: Developer, Test Automation
+Task description:
+- Remove the dead `/api/v1/sbom/diff` dependency from the deploy-diff feature.
+- Use the live lineage compare capability as the canonical comparison source and normalize it into the deploy-diff UI model.
+- Ensure the direct route either loads a comparison or lands in an explicit, user-actionable empty state instead of `Missing Parameters`.
+
+Completion criteria:
+- [ ] Deploy-diff uses a live contract that exists in sbomservice.
+- [ ] Direct navigation to `/releases/investigation/deploy-diff` no longer renders the legacy missing-parameter failure state.
+- [ ] Focused frontend tests cover both loaded and no-comparison states.
+
+### SBOM-RIW-003 - Restore change trace compatibility API and viewer behavior
+Status: DONE
+Dependency: SBOM-RIW-001
+Owners: Developer, Test Automation
+Task description:
+- Implement the missing `/api/change-traces` compatibility layer in SbomService instead of leaving the gateway to route into a void.
+- Make the change-trace viewer support canonical direct-load behavior and a deterministic empty state when there is no active comparison context.
+
+Completion criteria:
+- [ ] `/api/change-traces/build` and compatible read behavior exist in sbomservice with focused tests.
+- [ ] `/releases/investigation/change-trace` no longer renders the legacy inert empty shell on direct load.
+- [ ] Live Playwright verifies the viewer loads meaningful state and recovery actions.
+
+### SBOM-RIW-004 - Verify live route behavior after rebuild
+Status: DONE
+Dependency: SBOM-RIW-002
+Owners: QA, Test Automation
+Task description:
+- Rebuild the touched targets, redeploy only the changed services, rerun the focused Playwright surfaces, and capture the before/after evidence.
+- Do not mark the iteration done until the live shell confirms the repaired routes and their primary actions.
+
+Completion criteria:
+- [x] Focused .NET and Angular tests pass.
+- [x] `sbomservice` and web assets are rebuilt and redeployed.
+- [x] Live Playwright evidence shows the repaired routes and actions behaving correctly.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-09 | Sprint created after live Playwright confirmed `/releases/investigation/deploy-diff` rendered `Missing Parameters` and `/releases/investigation/change-trace` rendered `No Change Trace Loaded`; live stack inspection showed the mounted routes depended on dead or missing contracts. | Developer |
+| 2026-03-09 | Rebased deploy-diff on lineage compare, restored the `/api/change-traces` compatibility layer, and added focused verification: `dotnet test src/SbomService/StellaOps.SbomService.Tests/StellaOps.SbomService.Tests.csproj -v minimal -- --filter-class StellaOps.SbomService.Tests.ChangeTraceCompatibilityEndpointsTests` passed 3/3; `npx ng test --watch=false --ts-config tsconfig.spec.features.json --include=src/app/features/deploy-diff/services/deploy-diff.service.spec.ts --include=src/app/features/deploy-diff/components/deploy-diff-panel/deploy-diff-panel.component.spec.ts --include=src/app/features/deploy-diff/pages/deploy-diff.page.spec.ts --include=src/app/features/change-trace/change-trace-viewer.component.spec.ts` passed 30/30. | Developer |
+| 2026-03-09 | Rebuilt `sbomservice`, rebuilt and resynced the web bundle into `compose_console-dist`, then reran `node .\\src\\Web\\StellaOps.Web\\scripts\\live-frontdoor-changed-surfaces.mjs`; live frontdoor verification passed for the repaired release-investigation routes and their recovery actions on `https://stella-ops.local`. | Developer |
+
+## Decisions & Risks
+- Decision: release-investigation routes are Releases-owned workspaces with canonical direct-load behavior rather than query-only leaf pages.
+- Risk: the current live stack has empty release/SBOM comparison projections, so the workspace must degrade cleanly when no comparison exists instead of pretending data is present.
+- Risk: other agents have unrelated dirty files in `src/Web/StellaOps.Web/` and platform services; only stage touched release-investigation files for the eventual commit.
+- Contract note: `/api/change-traces/*` is restored as a deterministic compatibility layer over lineage compare, not as a second persistent change-trace store.
+
+## Next Checkpoints
+- Implement the workspace/default-context contract and the SbomService compatibility API in this iteration.
+- Rebuild `sbomservice` and the web bundle, sync the web assets into `compose_console-dist`, rerun the focused Playwright sweep, and commit the scoped repair.