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:
master
2026-04-22 16:06:39 +03:00
parent ad77711ac2
commit 7943cfb3af
121 changed files with 10483 additions and 387 deletions

View 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.