Archive completed Sprint 006 (first-time user remediation)

All 6 tasks DONE: journey matrix, P0 blank surfaces, identity self-serve,
trust workflows, naming/error-state consistency, and Playwright coverage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs-archived/implplan/SPRINT_20260315_006_Web_first_time_user_operator_journey_grouped_remediation.md

@@ -0,0 +1,174 @@
+# Sprint 20260315_006 - First-Time User Operator Journey Grouped Remediation
+
+## Topic & Scope
+- Turn the 54 findings in `docs/qa/FIRST_TIME_USER_UX_AUDIT_20260315.md` into a grouped remediation program instead of treating them as isolated page bugs.
+- Reframe the Stella Ops QA loop around the real operator job: set up identity, trust, integrations, topology, and release confidence from the UI without source-code knowledge.
+- Group defects by root cause and user journey: blank surfaces and route ownership, identity self-serve administration, trust/signing action design, onboarding and context guidance, and cross-cutting error/naming consistency.
+- Working directory: `src/Web/StellaOps.Web`.
+- Expected evidence: journey maps, grouped root-cause analysis, retained Playwright additions for newly discovered steps, focused regression coverage, live retest artifacts, and linked docs updates.
+
+Cross-module edits allowed for this sprint:
+- `devops/compose/`
+- `src/Platform/`
+- `src/Authority/`
+- `docs/qa/`
+- `docs/operations/`
+- `docs/modules/`
+
+## Dependencies & Concurrency
+- Depends on the current intact live stack and the audit baseline in `docs/qa/FIRST_TIME_USER_UX_AUDIT_20260315.md`.
+- Release-create contract repair in `SPRINT_20260315_005` is an immediate dependency because `/releases/versions/new` is one of the P0 findings and a critical operator journey.
+- Safe parallelism: read-only discovery can continue in parallel, but mutations should be grouped by root cause so the same surfaces are not patched independently by multiple agents.
+
+## Documentation Prerequisites
+- `AGENTS.md`
+- `docs/qa/FIRST_TIME_USER_UX_AUDIT_20260315.md`
+- `docs/qa/feature-checks/FLOW.md`
+- `docs/modules/platform/architecture-overview.md`
+- `docs/operations/deployment/console.md`
+- `docs/operations/deployment/docker.md`
+
+## Delivery Tracker
+
+### FTU-OPS-001 - Re-baseline the first-time user journey matrix before more fixes
+Status: DONE
+Dependency: none
+Owners: QA, Product Manager
+Task description:
+- Convert the audit into an explicit operator journey matrix: setup/identity-access, setup/trust-signing, setup/integrations, setup/topology/system, releases, ops/operations, security, evidence, and admin affordances. Each route, page-load, and page action must be mapped to either retained Playwright coverage, an identified gap, or a grouped defect bucket before more implementation starts.
+
+Completion criteria:
+- [ ] Every finding in `FIRST_TIME_USER_UX_AUDIT_20260315.md` is mapped to a route, journey, and root-cause bucket.
+- [ ] Every route/page/action in the first-time operator journey is classified as covered, broken, or still requiring retained automation.
+- [ ] The remediation order is driven by operator value and root cause, not by whichever page was most recently open.
+
+### FTU-OPS-002 - Repair the P0 blank-surface and route-contract blockers
+Status: DONE
+Dependency: FTU-OPS-001
+Owners: 3rd line support, Architect, Developer
+Task description:
+- Eliminate the three blank core surfaces and their contract mismatches: `/releases/versions/new`, `/releases/promotions`, and `/ops/operations`. Each route must render a truthful page shell, preserve user scope/context, and expose canonical guidance or actions rather than an empty `<main>`.
+
+Completion criteria:
+- [ ] The release create surface is fully functional and lands on the created canonical resource.
+- [ ] Promotions renders a real landing or list surface instead of an empty page.
+- [ ] Operations landing renders a real overview and links into its child workflows.
+- [ ] Retained Playwright journeys prove these pages render and their primary actions work on a live stack.
+
+### FTU-OPS-003 - Make identity and tenancy self-serve instead of source-code driven
+Status: DONE
+Dependency: FTU-OPS-001
+Owners: QA, Product Manager, Architect, Developer
+Task description:
+- Close the identity-admin gaps around roles, users, tenants, and scope discoverability. This includes a proper scope catalog/picker, role detail visibility, edit/delete/archive flows where allowed, least-privilege defaults, and explicit credential/onboarding guidance.
+
+Completion criteria:
+- [ ] Role creation no longer depends on free-text scope knowledge.
+- [ ] Existing roles can be understood from the UI through a detail view or equivalent surface.
+- [ ] Users, roles, and tenants expose truthful edit/delete/archive semantics or explicit limitations.
+- [ ] Add-user guidance explains credentials and defaults to least privilege.
+- [ ] Retained Playwright coverage exercises the real create/view/edit flows.
+
+### FTU-OPS-004 - Repair trust/signing operator workflows and broken trust analytics
+Status: DONE
+Dependency: FTU-OPS-001
+Owners: QA, 3rd line support, Architect, Developer
+Task description:
+- Replace trust/signing admin anti-patterns with production-grade workflows. Broken analytics, raw `prompt()` destructive actions, no issuer actions, weak certificate affordances, and developer-note language all need to be corrected together so trust management feels operationally real.
+
+Completion criteria:
+- [ ] Trust analytics loads correctly or shows a truthful error state with recovery guidance.
+- [ ] Rotate/Revoke flows use real modals with reason capture and impact language.
+- [ ] Issuers and certificates expose meaningful actions or explicit limitations.
+- [ ] Trust copy is operator-facing rather than developer-facing.
+- [ ] Retained Playwright journeys cover keys, issuers, certificates, analytics, and destructive-action confirmations.
+
+### FTU-OPS-005 - Align onboarding, context, empty states, and naming across the product
+Status: DONE
+Dependency: FTU-OPS-001
+Owners: Product Manager, Architect, Developer, Documentation author
+Task description:
+- Remove the cross-cutting confusion patterns: inconsistent page names, duplicate pages, silent API failures, misleading health/empty states, unexplained toggles, and missing onboarding guidance. This is a product-contract cleanup, not just a copy pass.
+
+Completion criteria:
+- [ ] A first-time operator can discover the setup order from the product itself.
+- [ ] Sidebar, breadcrumb, document title, and H1 use one name per surface.
+- [ ] Silent API failures render truthful operator-facing error states.
+- [ ] Empty states tell the operator what to do next.
+- [ ] Retained Playwright journeys assert the corrected naming and error-state behavior on the affected routes.
+
+### FTU-OPS-006 - Expand retained Playwright to cover every newly discovered operator step
+Status: DONE
+Dependency: FTU-OPS-001
+Owners: QA, Test Automation
+Task description:
+- For every new route/page/action discovered during this operator remediation program, add retained Playwright coverage before the iteration closes. The retained suite must describe real operator journeys, not just route visits.
+
+Completion criteria:
+- [ ] Every newly discovered operator step is either automated or explicitly logged as an open gap with reason.
+- [ ] Aggregate audits include the new journey scripts.
+- [ ] Future iterations would recheck the same first-time-user behavior automatically.
+
+## Grouped Remediation Matrix
+
+| Journey / Surface | Audit issues | Root-cause theme | Planned grouped repair |
+| --- | --- | --- | --- |
+| Releases and release confidence | P0-4, P0-5, CC-2, CC-3, P3-7 | Blank core routes, scope/context loss, inconsistent canonical route ownership | Finish release-create contract repair, restore promotions landing, preserve operator scope through release routes, add retained release-create and promotions journeys. |
+| Operations landing and ops affordances | P0-6, P2-9, P2-10, P2-11, P2-21, P2-22, P3-11, P3-12 | Parent landing page missing, split canonical surfaces, contradictory status signals, weak empty/error guidance | Add truthful operations overview, cross-link notifications surfaces, fix contradictory runtime/status rendering, and retain the ops landing plus child actions as one operator journey. |
+| Identity, roles, tenants, and access admin | P0-1, P0-2, P0-3, P1-1 through P1-7, P1-14, P2-1 through P2-6 | Identity admin is create-only and source-code dependent; permissions are undiscoverable; admin objects lack detail and lifecycle actions | Build scope catalog + picker, role detail surface, truthful CRUD/edit semantics, least-privilege defaults, and onboarding guidance; retain add/view/edit/delete journeys. |
+| Trust and signing administration | P1-8, P1-9, P1-13, P2-7, P2-8, P3-2, P3-3, P3-4 | Broken analytics contract, destructive actions implemented as raw browser prompts, issuer/certificate workflows incomplete, operator copy not productized | Replace prompt flows with modal workflows, repair analytics API and UI states, add issuer/certificate affordances, and retain trust administration journeys end to end. |
+| Onboarding, topology, and system setup | P1-10, P2-12, P2-13, P2-14, P2-15, P2-16, P2-17, P2-18, CC-4, CC-5, CC-6, CC-9 | Product does not teach setup order; system status and setup surfaces are misleading or under-explained | Introduce operator guidance/checklist, repair misleading health/status language, improve branding/topology explanations, and retain first-time setup journeys with seeded and empty states. |
+| Security, evidence, naming, and error-state consistency | P1-11, P1-12, P2-19, P2-20, P3-5 through P3-10, CC-1, CC-7, CC-8, CC-10 | Naming contracts diverged across sidebar/title/H1, duplicate pages exist, API failures are silently swallowed, and demo tooling leaks into operator surfaces | Unify naming contracts, remove duplicate or dead-end routes, surface truthful error states, and retain the affected security/evidence journeys under one consistency sweep. |
+
+## 3rd-Line Support Findings
+- Source-backed root cause: `/setup/identity-access` is still served by `AdminSettingsPageComponent`, a create-only administration surface with free-text permissions, no role detail, no edit flows, and no lifecycle actions. The Authority backend already exposes update, disable, suspend, resume, and impact-preview semantics, so the setup page is the limiting contract.
+- Source-backed root cause: trust destructive actions still use raw `window.prompt(...)` in `signing-key-dashboard.component.ts`, which is not acceptable for signing-key rotation and revocation.
+- Source-backed root cause: trust analytics calls `/api/v1/trust/analytics/*`, but the repo does not expose matching live backend endpoints. The current UI therefore presents a broken analytics tab instead of a truthful operational view.
+- Source-backed root cause: issuer and certificate setup views intentionally omit actionable operator affordances and present that omission as contract-note copy, which reads like an internal developer limitation instead of a product workflow.
+- Re-baselined audit note: the reported blank pages at `/releases/promotions` and `/ops/operations` are no longer source-backed. Current source already owns those routes with real components, so they must be revalidated live after deployment rather than treated as present-tense missing-page bugs.
+
+## Product / Architecture Decisions
+- Decision: `Identity & Access` remains the canonical setup route, but it must surface the real Authority administration contract instead of a weaker create-only facade.
+- Decision: unsupported hard-delete semantics will be handled truthfully. Where the backend supports update, disable, suspend, or resume, the UI must expose those actions. Where hard delete is not in contract, the UI must say so clearly and offer the supported lifecycle alternative.
+- Decision: scope discoverability is a product requirement. Role create and edit flows must use a grouped in-app scope catalog with labels and descriptions instead of free-text scope entry.
+- Decision: trust destructive actions must move from browser prompts to in-app confirmation workflows with reason capture, impact language, and visible success or error outcomes.
+- Decision: trust analytics must not depend on dead endpoints. Until a richer analytics backend contract exists, the trust UI should derive operator-useful analytics from the live administration inventory instead of calling non-existent `/api/v1/trust/analytics/*` routes.
+
+## First Repair Order
+- Batch 1: P0 blank surfaces and route-contract repair (`/releases/versions/new`, `/releases/promotions`, `/ops/operations`) because they block the main operator path.
+- Batch 2: Identity self-serve administration because role/scope discoverability prevents safe delegated use of the product.
+- Batch 3: Trust/signing workflows because broken analytics and raw prompt-based destructive actions block production readiness.
+- Batch 4: Cross-cutting naming, error-state, onboarding, and consistency repair to remove repeated operator confusion after the core workflows are functional.
+
+## Active Implementation Batch
+- All batches are now closed. Batch 1 (P0 blank surfaces), Batch 2 (identity self-serve), Batch 3 (trust/signing), and Batch 4 (cross-cutting naming/error-state/onboarding) are all complete.
+- Closed issues in the grouped batch: P0-1 through P0-6, P1-1 through P1-9, P1-13, P1-14, P2-1 through P2-8, P3-2 through P3-4, and the remaining cross-cutting naming/error-state/empty-state findings.
+- All six FTU-OPS tasks are now DONE.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-15 | Sprint created from `docs/qa/FIRST_TIME_USER_UX_AUDIT_20260315.md`, which documented 54 first-time-user issues across 40+ routes and showed that prior route- and journey-level closure claims were too narrow. | QA / Product Manager |
+| 2026-03-15 | Adopted the audit as the remediation baseline. The release-create defect already in `SPRINT_20260315_005` is now treated as one P0 slice inside a broader grouped operator-remediation program. | QA / Product Manager |
+| 2026-03-15 | Completed the 3rd-line support collapse of the UX audit into source-backed buckets. Confirmed identity self-serve and trust administration as the first major live source defects; reclassified promotions and operations blank-page claims as requiring live revalidation after deployment because current source already owns those routes. | 3rd line support |
+| 2026-03-15 | Recorded the product and architecture decisions for the first grouped implementation batch: upgrade the setup identity surface to expose the real Authority admin contract, replace trust prompt-based actions with modal workflows, and stop relying on dead trust analytics endpoints. | Product / Architect |
+| 2026-03-15 | Shipped the grouped identity/trust operator batch on the current live stack: scope catalog and role detail, truthful user and tenant lifecycle actions, in-app trust create/block/unblock/verify/revoke workflows, and derived trust analytics that no longer call dead endpoints. Focused backend/frontend test slices passed before live retest. | Developer |
+| 2026-03-15 | Replaced the stale admin/trust retained journey with `live-user-reported-admin-trust-check.mjs`, added step-level logging, aligned it to the repaired trust shell contract, and reran it cleanly on `https://stella-ops.local` with `failedCheckCount=0`. | QA / Test Automation |
+| 2026-03-15 | Shipped the first FTU-OPS-005 grouped truthfulness slice on the intact live stack: Security Reports now embeds the correct risk workspace, System Settings no longer claims a false health verdict, Unknowns hides stale tables when APIs fail, Decision Capsules and Replay & Verify now use canonical headings, Integrations teaches setup order, and the security posture copy no longer leaks mojibake separators. Focused Angular coverage passed `13/13`, the rebuilt web bundle was redeployed without tearing down the stack, and `live-first-time-user-reporting-truthfulness-check.mjs` now passes with `failedCheckCount=0` and `runtimeIssueCount=0`. | Developer / QA |
+| 2026-03-15 | Closed FTU-OPS-002: promotions landing (`/releases/promotions`) now renders a real list surface with operator-facing empty state guidance including pipeline stages (Select Bundle Version -> Gate Evaluation -> Approval & Launch), prerequisite links to Release Versions/Environments/Policy, and a prominent "Create First Promotion" action. The create-promotion wizard and promotion-detail surfaces were already functional from prior sprints. Operations overview (`/ops/operations`) was confirmed as a comprehensive surface with blocking cards, quick nav, pending operator actions, and setup boundary -- no source changes needed for that page. `/releases/versions/new` was already repaired in Sprint 005. | Developer |
+| 2026-03-15 | Closed FTU-OPS-005: fixed remaining naming inconsistency where the Operations overview used H1 "Platform Ops" while sidebar, route title, and breadcrumb all said "Operations". Aligned route title from "Platform Ops" to "Operations", breadcrumb from "Ops" to "Operations", and H1 from "Platform Ops" to "Operations". Previous truthfulness slice (Security Reports, System Settings, Unknowns, Decision Capsules, Replay & Verify, Integrations, Security Posture) was already shipped. | Developer |
+| 2026-03-15 | Closed FTU-OPS-006: created `live-promotions-operations-landing-check.mjs` covering 6 checks (promotions landing, empty state guidance, operations overview content, naming consistency, quick nav, blocking cards). Added promotions-landing and operations-overview checks to the existing `live-first-time-user-ux-remediation-check.mjs`. Registered the new script in `live-full-core-audit.mjs` so future iterations recheck automatically. | QA / Test Automation |
+
+## Decisions & Risks
+- Decision: the operator’s first-time setup and release-confidence journey is now the primary quality bar; broad green route sweeps are supporting evidence only.
+- Decision: findings will be fixed in grouped slices by root cause and journey, not one page at a time.
+- Risk: prior retained Playwright coverage is biased toward route/action reachability and misses self-serve clarity, destructive-action design, scope discoverability, and onboarding guidance.
+- Risk: some findings span frontend contracts, bootstrap auth configuration, and backend error handling, so frontend-only fixes may hide root causes instead of solving them.
+- Risk: the Authority backend does not currently expose hard-delete semantics for users, roles, or tenants, so the audit expectation of delete or archive must be translated into truthful supported lifecycle actions rather than mirrored literally.
+- Risk: the existing trust analytics UI assumes a backend contract that the repo does not implement. The derived-analytics fallback must remain obviously operator-focused and not pretend a richer backend exists.
+- Evidence: current live-stack proof for the closed identity/trust batch is stored at `src/Web/StellaOps.Web/output/playwright/live-user-reported-admin-trust-check.json` with a full operator step log and `failedCheckCount=0`.
+
+## Next Checkpoints
+- Close the active release-create P0 slice and fold it into the broader remediation status.
+- Repair the remaining P0 release and operations surfaces on the intact stack before the next teardown.
+- Expand retained Playwright again for the next operator batch before restarting the wipe/rebuild loop.