chore(docs+devops): cross-module doc sync + sprint archival moves + compose updates
Bundled pre-session doc + ops work: - docs/modules/**: sync across advisory-ai, airgap, cli, excititor, export-center, findings-ledger, notifier, notify, platform, router, sbom-service, ui, web (architectural + operational updates) - docs/features/**: updates to checked excititor vex pipeline, developer workspace, quick verify drawer - docs top-level: README, quickstart, API_CLI_REFERENCE, UI_GUIDE, code-of-conduct/TESTING_PRACTICES updates - docs/qa/feature-checks/: FLOW.md + excititor state update - docs/implplan/: remaining sprint updates + new Concelier source credentials sprint (SPRINT_20260422_003) - docs-archived/implplan/: 30 sprint archival moves (ElkSharp series, misc completed sprints) - devops/compose: .env + services compose + env example + router gateway config updates File-level granularity preserved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
87
docs/qa/console-ui-traversal-map.md
Normal file
87
docs/qa/console-ui-traversal-map.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# Console UI Traversal Map
|
||||
|
||||
## Purpose
|
||||
- Translate the approved "release with confidence" product framing into the current Stella Ops Console surface.
|
||||
- Give QA and implementers a route-by-route map of what must be traversed, what is only an alias, and what already looks weak or broken.
|
||||
- Keep the next pass grounded in runtime truth, not in older navigation specs or planned-only screen inventories.
|
||||
|
||||
## Evidence Base
|
||||
- Product framing: `docs/product/release-with-confidence-product-card.md`
|
||||
- Route ownership: `src/Web/StellaOps.Web/src/app/app.routes.ts`
|
||||
- Sidebar ownership model: `src/Web/StellaOps.Web/src/app/core/navigation/navigation.config.ts`
|
||||
- Runtime evidence: authenticated local-source sweep captured on 2026-04-21 in `src/Web/StellaOps.Web/output/playwright/console-surface-scan.json`
|
||||
|
||||
## Product Standard
|
||||
- Stella is not a generic dashboard collection. The Console exists to answer: what is being released, why it is safe enough, what evidence backs that decision, and what action an operator should take next.
|
||||
- A Console page is only acceptable when it preserves release/evidence context, makes ownership clear, and exposes truthful next actions.
|
||||
- Hidden uncertainty, ambiguous aliases, and page shells with weak identity are product defects because they increase operator error under release pressure.
|
||||
|
||||
## Canonical Surface
|
||||
|
||||
| Family | Canonical entry routes | Tabs or route variants observed | What the page family must prove |
|
||||
| --- | --- | --- | --- |
|
||||
| Home | `/` | none captured in the sweep | Daily operating state and the first truthful next action. |
|
||||
| Release Control | `/environments/overview`, `/releases`, `/releases/deployments`, `/releases/bundles`, `/releases/promotions`, `/releases/approvals` | `/releases/approvals` tabs: Pending, Approved, Rejected, Expiring, My Team | Release identity, promotion state, approval state, and bundle truth. |
|
||||
| Release Policies | `/ops/policy/packs`, `/ops/policy/governance`, `/ops/policy/vex`, `/ops/policy/simulation` | Shared policy tabs: Release Policies, Governance, VEX & Exceptions, Simulation, Audit. Additional VEX and Simulation local tabs are visible. | Policy gates, VEX conflict handling, simulation, and auditability of release decisions. |
|
||||
| Security | `/security/images`, `/security/risk`, `/security/advisory-sources`, `/triage/artifacts` | `/security/images/*` tabs: Summary, Findings, SBOM, Reachability, VEX, Evidence | Security posture must stay attached to release truth and evidence, not float as disconnected findings. |
|
||||
| Evidence | `/evidence/overview`, `/evidence/audit-log`, `/evidence/verify-replay`, `/evidence/exports`, `/evidence/capsules` | Audit-style tabs observed on `/evidence/overview` and `/evidence/capsules`: All Events, Timeline, Correlations, Exports, Bundles. Replay tabs observed on `/evidence/verify-replay`. | Evidence lookup, replay, export, and proof packaging for audit and re-verification. |
|
||||
| Ops | `/ops/operations/jobengine`, `/ops/operations/feeds-airgap`, `/ops/operations/doctor`, `/ops/scripts`, `/ops/operations/audit` | JobEngine tabs: Runs, Schedules, Workers. Audit tabs: All Events, Timeline, Correlations, Exports, Bundles | Operator workflows, execution health, feed freshness, and background control-plane truth. |
|
||||
| Setup and Admin | `/setup`, `/setup/integrations`, `/setup/trust-signing`, `/setup/identity-providers`, `/setup/tenant-branding`, `/console-admin/*` | Trust Signing tabs: Signing Keys, Trusted Issuers, Certificates, Audit | Identity, trust, integrations, branding, and admin controls that let the Console be safely operated. |
|
||||
|
||||
## Current Route And Handoff Findings
|
||||
|
||||
### Stable, route-backed surfaces from the 2026-04-21 pass
|
||||
- `/releases`, `/releases/deployments`, `/releases/bundles`, `/releases/promotions`, and `/releases/approvals` all rendered with stable titles and page-specific headings.
|
||||
- `/ops/policy/governance`, `/ops/policy/vex`, and `/ops/policy/simulation` rendered as a coherent tab family and visibly cross-linked to sibling routes.
|
||||
- `/security/images/summary` rendered with the expected security tabs and explicit empty-state guidance telling the operator to select a release.
|
||||
- `/evidence/verify-replay` rendered a distinct replay surface with headings for replay request and determinism verification.
|
||||
- `/ops/operations/jobengine`, `/ops/operations/audit`, `/ops/scripts`, `/setup`, `/setup/trust-signing`, and `/setup/identity-providers` rendered distinct route-backed surfaces with recognizable titles.
|
||||
|
||||
### Alias and ownership behavior that QA must treat carefully
|
||||
- `/security/images` canonicalizes to `/security/images/summary`. That is acceptable if the page identity remains "Image Security" and the tabs preserve the security evidence context.
|
||||
- `/setup/trust-signing` canonicalizes to `/setup/trust-signing/keys`. That is acceptable if the page identity remains trust and signing, not just "keys".
|
||||
- `/evidence/overview` currently lands on `/ops/operations/audit`.
|
||||
- `/evidence/capsules` currently lands on `/ops/operations/audit?tab=all-events`.
|
||||
- Those Evidence-to-Audit collapses may be intentional consolidation, but today they weaken the standalone Evidence surface and must be reviewed against product intent.
|
||||
|
||||
### Weak identity surfaces from the current runtime pass
|
||||
- `/`
|
||||
- `/environments/overview`
|
||||
- `/ops/policy/packs`
|
||||
- `/security/advisory-sources`
|
||||
- `/triage/artifacts`
|
||||
- `/evidence/exports`
|
||||
- `/ops/operations/feeds-airgap`
|
||||
- `/ops/operations/doctor`
|
||||
- `/setup/integrations`
|
||||
- `/setup/tenant-branding`
|
||||
|
||||
These routes resolved and often had route titles, but the automated pass extracted little or no page-level heading/CTA identity from the main surface. In the next QA pass, treat them as "weak identity" pages and verify whether the problem is:
|
||||
- truly missing page identity,
|
||||
- card-based content without a stable top-level heading,
|
||||
- lazy-loading or state timing,
|
||||
- or a page shell that is present but not communicating ownership clearly enough.
|
||||
|
||||
### Confirmed route defect
|
||||
- `curl -k -I https://127.0.0.1:4400/console-admin/tenants` returned `302 Found` with `location: https://127.0.0.1/console-admin/tenants`.
|
||||
- The redirect drops the dev-server port. Browser navigation then fails with `net::ERR_CONNECTION_REFUSED`.
|
||||
- Treat `/console-admin/*` and `/console/admin/*` as an active route defect in local-source verification until the redirect/base-url behavior is fixed.
|
||||
|
||||
### Harness caveat that affects future QA
|
||||
- The comment in `src/Web/StellaOps.Web/e2e/fixtures/auth.fixture.ts` says the app reads `window.__stellaopsTestSession` during bootstrap.
|
||||
- In the current app, the auth guard trusts `AuthSessionStore`, which restores from the persisted session keys `stellaops.auth.session.full`, `stellaops.auth.session.info`, and the `stellaops:wasEverAuth` latch.
|
||||
- Local-source QA should seed the real persisted session keys. Do not rely on the outdated fixture comment as the source of truth.
|
||||
|
||||
### Stale spec caveat
|
||||
- Older E2E navigation expectations still assume a standalone Evidence sidebar group.
|
||||
- The current navigation config intentionally routes Evidence contextually and consolidates audit entry under Ops.
|
||||
- Any future UI regression claims must be judged against the current navigation contract, not against the retired sidebar grouping.
|
||||
|
||||
## Next-Pass Traversal Order
|
||||
1. Release Control and Release Policies
|
||||
2. Security
|
||||
3. Evidence
|
||||
4. Ops
|
||||
5. Setup and Admin
|
||||
|
||||
This order matches product risk. Release truth and policy truth come first, because those surfaces determine whether Stella can release with confidence at all.
|
||||
Reference in New Issue
Block a user