Add enterprise appliance experience Phase 1 foundation
This commit is contained in:
Jino Jose committed
1 parent
b3eec34158
commit
ebaa2e7219
69 files changed
+6832
-18
No files matched your search
@@ -0,0 +1,36 @@
|
||||
# Specification Quality Checklist: Enterprise Appliance Experience Hardening
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: 2026-07-12
|
||||
**Feature**: [spec.md](../spec.md)
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No `[NEEDS CLARIFICATION]` markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
## Notes
|
||||
|
||||
- Validation completed on 2026-07-12.
|
||||
- Revalidated after five clarification decisions on 2026-07-12; all 16 items remain passing.
|
||||
- The clarification pass is complete and the specification is ready for `$speckit-plan`.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Customer Experience Contract
|
||||
|
||||
This contract defines observable behaviour. Exact endpoint paths may remain compatible with existing
|
||||
routes or be introduced additively during implementation.
|
||||
|
||||
## Common Response State
|
||||
|
||||
Every customer-facing state-bearing response provides:
|
||||
|
||||
- canonical `state` and `severity`;
|
||||
- `observed_at` and explicit freshness when not live;
|
||||
- plain-language `summary` and customer impact;
|
||||
- stable non-secret `code` for support correlation;
|
||||
- ordered `next_actions`, filtered by authorization;
|
||||
- `correlation_id` when an operation or failure is involved.
|
||||
|
||||
Raw exceptions, stack traces, signed license material, credentials, tokens, document content, and
|
||||
secret-bearing command output MUST NOT appear.
|
||||
|
||||
## Readiness Interface
|
||||
|
||||
The readiness interface returns the ApplianceReadiness model. It MUST distinguish:
|
||||
|
||||
- product/API unreachable from a degraded dependent capability;
|
||||
- licensed from provisioned, hardware-supported, and currently available;
|
||||
- ready from stale last-known-ready;
|
||||
- customer impact from technical diagnostic detail.
|
||||
|
||||
Phase 1 may extend the existing readiness-report route additively. Existing fields remain until all
|
||||
packaged consumers move to the versioned contract.
|
||||
|
||||
## Operation Interface
|
||||
|
||||
Supported behaviours:
|
||||
|
||||
1. **Create/acknowledge**: validates authorization, prerequisites, conflicts, scope, and confirmation.
|
||||
2. **Read**: returns durable current state by operation ID after refresh, restart, or session change.
|
||||
3. **List**: returns role-filtered recent and active operations.
|
||||
4. **Act**: exposes only valid retry/resume/cancel/recovery actions for the current state.
|
||||
|
||||
Creation MUST be idempotent for duplicate customer submissions within the defined request window.
|
||||
Conflicting operations return a customer-facing explanation and reference the blocking operation.
|
||||
Every operation interface enforces server-side authorization and is tested for both permitted and
|
||||
denied roles. Removal additionally exposes retained/deleted data categories and preserves backups by
|
||||
default unless a separately confirmed policy explicitly requires deletion.
|
||||
|
||||
## Error Contract
|
||||
|
||||
Errors provide status, stable `code`, plain-language `message`, `affected_scope`, safe
|
||||
`remediation`, and optional `correlation_id`. Validation errors identify fields without discarding
|
||||
other valid setup progress. Authorization errors do not reveal protected resource existence.
|
||||
|
||||
## Entitlement Contract
|
||||
|
||||
Customer-facing output uses Workstation and Server S/M/L/Max labels. Compatibility identifiers may
|
||||
appear only in authorized diagnostics. Every capability state identifies one primary reason:
|
||||
licensed, not licensed, not provisioned, unsupported by hardware, degraded, or unavailable.
|
||||
|
||||
## Audit Contract
|
||||
|
||||
Every privileged, security-sensitive, licensing, configuration, and lifecycle action records actor,
|
||||
time, category, redacted scope, result, and correlation ID. Secret values and signed payloads are
|
||||
never recorded. Denied and failed actions are auditable where safe.
|
||||
|
||||
## Accessibility Contract
|
||||
|
||||
- All functionality is operable by keyboard with visible focus and logical order.
|
||||
- Dynamic status and validation feedback is programmatically announced without stealing focus.
|
||||
- Labels, instructions, errors, and confirmations are programmatically associated.
|
||||
- Status and severity never rely on colour alone.
|
||||
- Content supports required contrast, zoom, reflow, and reduced-motion behaviour.
|
||||
- Acceptance requires automated and representative manual WCAG 2.2 AA evidence.
|
||||
|
||||
## Release Evidence Contract
|
||||
|
||||
Each phase records source revision, package/ISO identity and checksum, test environment, product
|
||||
configuration, validation results, known limitations, pilot findings, resolutions, and joint approval
|
||||
from product ownership and delivery/support.
|
||||
@@ -0,0 +1,114 @@
|
||||
# Data Model: Enterprise Appliance Experience Hardening
|
||||
|
||||
## ApplianceReadiness
|
||||
|
||||
Customer-facing aggregate of appliance state.
|
||||
|
||||
| Field | Rules |
|
||||
|---|---|
|
||||
| `schema_version` | Required contract version |
|
||||
| `state` | One of loading, empty, ready, degraded, failed, restricted, unavailable, stale |
|
||||
| `severity` | info, warning, critical |
|
||||
| `observed_at` | UTC timestamp for underlying observation |
|
||||
| `freshness_seconds` | Non-negative age at response time |
|
||||
| `summary` | Plain-language customer impact |
|
||||
| `affected_capabilities` | Customer-facing capability identifiers, not raw service names |
|
||||
| `next_actions` | Ordered safe actions with required role and action kind |
|
||||
| `checks` | Component/capability observations using the same state contract |
|
||||
| `entitlement` | Reference to current EntitlementState summary |
|
||||
|
||||
State precedence: failed/critical impact outranks degraded; stale MUST be reported when freshness is
|
||||
outside the defined check window even if the previous observation was ready.
|
||||
|
||||
## Operation
|
||||
|
||||
Durable record for installation and consequential or long-running actions.
|
||||
|
||||
| Field | Rules |
|
||||
|---|---|
|
||||
| `id` | Stable opaque identifier |
|
||||
| `correlation_id` | Stable across API, audit, logs, and support evidence |
|
||||
| `kind` | setup, install, backup, restore, upgrade, restart, remove, reconcile, diagnostic_export, other |
|
||||
| `actor_id` / `actor_name` | Authenticated actor or explicit system/installer identity |
|
||||
| `scope` | Redacted description of affected appliance resources |
|
||||
| `state` | requested, validating, queued, running, awaiting_reboot, succeeded, failed, cancelled, recovery_required |
|
||||
| `progress_percent` | 0–100 only when meaningful; otherwise omitted |
|
||||
| `progress_label` | Plain-language current phase |
|
||||
| `requested_at`, `started_at`, `updated_at`, `finished_at` | UTC timestamps |
|
||||
| `result_code` | Stable non-secret machine-readable result |
|
||||
| `customer_message` | Plain-language outcome and impact |
|
||||
| `recovery_actions` | Safe retry/resume/rollback/restore/restart/escalate actions |
|
||||
| `metadata` | Allowlisted, versioned, non-secret details only |
|
||||
|
||||
Transitions are monotonic except explicit retry, which creates a new Operation linked to its parent.
|
||||
Terminal states are succeeded, failed, cancelled, and recovery_required. Concurrent conflicting
|
||||
operations MUST be rejected or queued with an explanation.
|
||||
|
||||
Removal operation metadata includes an allowlisted retained-data inventory, deleted-data categories,
|
||||
backup preservation status, and rollback limitations; it never includes protected content values.
|
||||
|
||||
## EntitlementState
|
||||
|
||||
| Field | Rules |
|
||||
|---|---|
|
||||
| `category` | workstation or server |
|
||||
| `commercial_label` | Workstation or Server S/M/L/Max |
|
||||
| `compatibility_tier` | workstation or starter/basic/pro/max; not primary customer text |
|
||||
| `license_state` | valid, missing, expired, invalid, mismatch, other stable states |
|
||||
| `licensed_capabilities` | Capability keys from signed entitlement evaluation |
|
||||
| `provisioned_capabilities` | Derived from install record and deployed roles |
|
||||
| `hardware_capabilities` | Derived from feasibility evidence |
|
||||
| `available_capabilities` | Current intersection adjusted for runtime health |
|
||||
| `observed_at` | UTC evaluation time |
|
||||
|
||||
The model MUST distinguish why a capability is unavailable: commercial entitlement, provisioning,
|
||||
hardware, or current runtime condition.
|
||||
|
||||
## AuditEvent
|
||||
|
||||
| Field | Rules |
|
||||
|---|---|
|
||||
| `id` | Monotonic appliance-local identifier |
|
||||
| `occurred_at` | UTC timestamp |
|
||||
| `actor_id` / `actor_name` | Actor identity when known |
|
||||
| `action_category` | Stable category rather than secret-bearing free text |
|
||||
| `scope` | Redacted affected resource |
|
||||
| `result` | success, failure, denied, partial |
|
||||
| `correlation_id` | Links to Operation and support evidence |
|
||||
| `detail` | Allowlisted, redacted context |
|
||||
|
||||
## SupportEvidencePackage
|
||||
|
||||
Logical export; raw secret-bearing files are excluded by default.
|
||||
|
||||
| Field | Rules |
|
||||
|---|---|
|
||||
| `package_id` | Opaque identifier |
|
||||
| `created_at` / `created_by` | UTC time and authorized actor |
|
||||
| `product_identity` | Product category, commercial label, version/build identity |
|
||||
| `entitlement_summary` | Status and capability summary without signed payload or key |
|
||||
| `readiness_snapshot` | ApplianceReadiness contract |
|
||||
| `operations` | Selected redacted Operation records |
|
||||
| `audit_events` | Selected redacted AuditEvent records |
|
||||
| `component_evidence` | Allowlisted health/version/status data |
|
||||
| `redaction_report` | Categories excluded or transformed |
|
||||
| `checksum` | Integrity checksum of the completed export |
|
||||
|
||||
## GuidanceItem
|
||||
|
||||
| Field | Rules |
|
||||
|---|---|
|
||||
| `id` | Stable local identifier |
|
||||
| `journey` | setup, readiness, administration, recovery, support |
|
||||
| `trigger_state` | Optional state or result code |
|
||||
| `required_role` | Minimum role permitted to execute actions |
|
||||
| `title`, `summary`, `steps` | Plain-language local guidance |
|
||||
| `action_kind` | navigate, retry, resume, rollback, restore, restart, escalate |
|
||||
| `version` | Guidance revision aligned to packaged product |
|
||||
|
||||
## Relationships
|
||||
|
||||
- ApplianceReadiness references one current EntitlementState and zero or more active Operations.
|
||||
- Operation produces AuditEvents and may be included in a SupportEvidencePackage.
|
||||
- SupportEvidencePackage contains snapshots, never live mutable references.
|
||||
- GuidanceItems are selected by journey, state, role, and result code.
|
||||
@@ -0,0 +1,46 @@
|
||||
# Phase 1 Evidence Manifest
|
||||
|
||||
**Status**: Test foundation established; runtime implementation not yet accepted.
|
||||
|
||||
## Source
|
||||
|
||||
- Git revision: record at validation time
|
||||
- Working-tree status: record at validation time
|
||||
- Feature: `001-enterprise-experience`
|
||||
- Product coverage: one representative Workstation and one representative Server
|
||||
|
||||
## Required Evidence
|
||||
|
||||
| Gate | Evidence | Status |
|
||||
|---|---|---|
|
||||
| Specification | Requirements checklist 16/16 | Complete |
|
||||
| Test foundation | Isolated Python, browser, deployment and fixture guidance | Complete |
|
||||
| Migration | Versioned migration and rollback design | Complete |
|
||||
| Backend contracts | State, error, operation, audit, authorization and entitlement tests | Complete |
|
||||
| Browser journeys | Setup, interruption, readiness and WCAG evidence | Pending |
|
||||
| Workstation | Clean install and recovery evidence | Pending |
|
||||
| Server | Clean install and recovery evidence | Pending |
|
||||
| Package provenance | Source-to-package and ISO checksum evidence | Pending |
|
||||
| Pilot | Controlled pilot evidence | Not authorized |
|
||||
| Approval | Product owner plus delivery/support | Pending |
|
||||
|
||||
## Review Boundary
|
||||
|
||||
The test harness adds only `tests/` and specification evidence files. It does not require runtime
|
||||
product changes. Runtime work begins only after the harness and contract tests are reviewable.
|
||||
|
||||
## Foundational Contract Evidence
|
||||
|
||||
- Versioned, idempotent schema migration creates durable operations and audit correlation fields.
|
||||
- Newer unsupported schemas are rejected before feature mutation.
|
||||
- Customer-state and error envelopes expose stable, non-secret fields.
|
||||
- Operation kinds and idempotency constraints are durable in SQLite.
|
||||
- New operation creation requires an administrator identity server-side.
|
||||
- Structured and text audit detail tests redact secret categories.
|
||||
- Canonical and deployed license helpers are byte-identical.
|
||||
- Isolated backend contract suite passed using synthetic in-memory SQLite on 2026-07-12.
|
||||
|
||||
## Artifact Record
|
||||
|
||||
Record source revision, ISO/package path, build timestamp, size, SHA-256, included portal/backend/
|
||||
installer revisions, environment, results, known limitations, and reviewer for each candidate.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Phase 1 Provenance Check — Partial
|
||||
|
||||
**Checked**: 2026-07-12
|
||||
|
||||
## Source State
|
||||
|
||||
- Local repository HEAD before uncommitted Phase 1 work: `b3eec341586551023b05db7a82bf19446186c768`
|
||||
- Phase 1 implementation is currently uncommitted and therefore has no immutable release revision.
|
||||
- Working tree contains the intended Spec Kit, test, backend, installer and portal changes plus the
|
||||
pre-existing unrelated untracked `how-it-flows.gif`.
|
||||
|
||||
## Local ISO Evidence
|
||||
|
||||
| Path | Size | SHA-256 | Result |
|
||||
|---|---:|---|---|
|
||||
| `cezen-ai-ubuntu2204.iso` | 0 bytes | `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` | Placeholder; invalid evidence |
|
||||
| `autoinstall/cezen-ai-ubuntu2204.iso` | 0 bytes | `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` | Placeholder; invalid evidence |
|
||||
|
||||
No local Workstation ISO artifact exists. Build scripts remain separate for Server and Workstation.
|
||||
|
||||
## Build-Host Check
|
||||
|
||||
Authenticated read-only verification succeeded against `cezen@172.16.10.145` at
|
||||
`/home/cezen/aipackage/cgit`. No remote state changed.
|
||||
|
||||
| Artifact | Size | Timestamp (UTC) | SHA-256 |
|
||||
|---|---:|---|---|
|
||||
| `autoinstall/cezen-ai-ubuntu2204.iso` | 2,136,397,824 bytes | 2026-07-09 05:52:52 | `bb2d0ab26c34f179dba9e34e8610d8a17763f8d2e38f948900509bfb8fd83b5d` |
|
||||
| `cezen-ai-ubuntu2204.iso` | 2,136,397,824 bytes | 2026-07-09 05:53:40 | `bb2d0ab26c34f179dba9e34e8610d8a17763f8d2e38f948900509bfb8fd83b5d` |
|
||||
|
||||
No `cezen-ai-workstation-ubuntu2204.iso` artifact exists in either checked build-host location.
|
||||
The host is Ubuntu with approximately 8.0 GB free on `/`; capacity must be monitored during rebuild.
|
||||
The existing Server ISO predates the uncommitted Phase 1 implementation and is not valid provenance
|
||||
evidence for this feature.
|
||||
|
||||
## Remaining Evidence
|
||||
|
||||
- After explicit sync/rebuild authorization, sync the accepted source and build Server and Workstation
|
||||
artifacts from that exact revision.
|
||||
- Prove the artifact contains the accepted portal, backend, installer, deployment and license copies.
|
||||
- Complete representative Workstation and Server install/recovery journeys.
|
||||
|
||||
T036, T037 and T038 remain incomplete.
|
||||
|
||||
## Authorized Rebuild Results — 2026-07-12
|
||||
|
||||
Current uncommitted source was synchronized to `/home/cezen/aipackage/cgit` with Git metadata,
|
||||
credentials, caches, unrelated `how-it-flows.gif`, and existing ISO binaries excluded. Both builds
|
||||
completed and their internal `md5sum.txt` manifests verified successfully.
|
||||
|
||||
| Artifact | Size | Timestamp (UTC) | SHA-256 |
|
||||
|---|---:|---|---|
|
||||
| `autoinstall/cezen-ai-ubuntu2204.iso` | 2,136,397,824 bytes | 2026-07-12 06:37:08 | `b7ba156e9eae6de5595fa85354468836d582db093d1c3cb85eceb9caaca5dfcf` |
|
||||
| `autoinstall/cezen-ai-workstation-ubuntu2204.iso` | 2,136,399,872 bytes | 2026-07-12 06:39:55 | `46c0ec277a711e7075082e362bcf5f5882812e8cbf9baf6ca35c4b5afc68e171` |
|
||||
|
||||
The older root-level `cezen-ai-ubuntu2204.iso` remains unchanged with SHA-256
|
||||
`bb2d0ab26c34f179dba9e34e8610d8a17763f8d2e38f948900509bfb8fd83b5d`; it MUST NOT be confused with
|
||||
the rebuilt Server artifact.
|
||||
|
||||
### Provenance limitation
|
||||
|
||||
Both online installer images clone `https://cgit.cezentech.com/jinojose/aipackage.git` during first
|
||||
boot. The Phase 1 implementation is still uncommitted and unpushed, so the rebuilt ISO boot layer is
|
||||
current but a real install would still pull the older remote package. T038 cannot pass until the
|
||||
accepted source is committed/pushed and artifact/source evidence is rechecked. T036–T037 also remain
|
||||
pending real representative installs.
|
||||
@@ -0,0 +1,26 @@
|
||||
# SQLite Migration and Rollback Procedure
|
||||
|
||||
## Rules
|
||||
|
||||
1. Read the current schema version before application startup writes new data.
|
||||
2. Create a verified pre-migration backup of the database and required companion state.
|
||||
3. Apply sequential idempotent migrations in one exclusive transaction where SQLite permits.
|
||||
4. Record the new version only after all statements and validation checks succeed.
|
||||
5. On failure, roll back the transaction, preserve the original database and record a redacted error.
|
||||
6. Never downgrade destructively. Restore the pre-migration backup when rollback requires an older
|
||||
application version.
|
||||
|
||||
## Validation
|
||||
|
||||
- Fresh database reaches the latest version.
|
||||
- Each supported previous version upgrades exactly once.
|
||||
- Re-running the migration is a no-op.
|
||||
- Interrupted/failed migration leaves a usable prior database or verified recovery copy.
|
||||
- Existing users, sessions, audit history, licensing state, settings and supported customer data
|
||||
remain readable.
|
||||
- Backup compatibility is checked before any restore mutation.
|
||||
|
||||
## Rollback Evidence
|
||||
|
||||
Record source and target schema versions, backup path/checksum, start/end time, result, correlation ID,
|
||||
validation outcome, and recovery action without storing secrets or customer content.
|
||||
@@ -0,0 +1,171 @@
|
||||
# Implementation Plan: Enterprise Appliance Experience Hardening
|
||||
|
||||
**Branch**: `001-enterprise-experience` | **Date**: 2026-07-12 | **Spec**: [spec.md](spec.md)
|
||||
|
||||
**Input**: Feature specification from `specs/001-enterprise-experience/spec.md`
|
||||
|
||||
## Summary
|
||||
|
||||
Harden Nexus One AI through three independently accepted phases: setup/readiness, daily
|
||||
administration, and recovery/support. Preserve the current static portal, FastAPI management API,
|
||||
SQLite appliance data, shell/Ansible installer, and license compatibility model. Introduce shared
|
||||
experience contracts for truthful states, durable operations, redacted support evidence, consistent
|
||||
entitlements, accessibility, and release provenance rather than replacing the product architecture.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: Python 3.11; browser-native HTML/CSS/JavaScript; Bash; Ansible YAML
|
||||
|
||||
**Primary Dependencies**: FastAPI 0.111+, Uvicorn 0.29+, python-jose, passlib/bcrypt, psutil,
|
||||
APScheduler, Nginx, systemd, Ansible, Ubuntu autoinstall
|
||||
|
||||
**Storage**: SQLite at `/opt/cezen/data/cezen.db`; JSON appliance records under `/opt/cezen`;
|
||||
filesystem backups under `/opt/cezen/backups`; systemd journal and install logs
|
||||
|
||||
**Testing**: Python unit/contract tests to be added around backend state and redaction; browser
|
||||
journey and accessibility checks; shell/static validation; Ansible syntax checks; clean-install,
|
||||
upgrade, interruption, backup/restore, pilot, and packaged-artifact verification
|
||||
|
||||
**Target Platform**: Nexus One AI Workstation and Server appliances on Ubuntu 22.04, accessed through
|
||||
supported desktop browsers on customer-controlled networks
|
||||
|
||||
**Project Type**: On-premises appliance package containing a static web portal, management API,
|
||||
installer, deployment automation, system services, and ISO build paths
|
||||
|
||||
**Performance Goals**: Readiness visible within 10 seconds of portal entry under normal appliance
|
||||
conditions; local navigation feedback within 1 second; operation acknowledgement within 2 seconds;
|
||||
progress freshness appropriate to the underlying operation and never presented as live when stale
|
||||
|
||||
**Constraints**: Restricted/offline operation after installation; existing `starter/basic/pro/max`
|
||||
compatibility identifiers; Workstation remains outside the Server tier ladder; no fabricated runtime
|
||||
state; secrets excluded from diagnostics; WCAG 2.2 AA; safe migration of existing SQLite appliances;
|
||||
no unsupported HA or recovery claims
|
||||
|
||||
**Scale/Scope**: Approximately 60 static portal pages, one large FastAPI service, two first-boot
|
||||
interfaces, four Server tiers plus Workstation packaging, multiple Ansible roles, and three ISO build
|
||||
paths. Phase 1 is limited to setup/readiness on one representative Workstation and one representative
|
||||
Server configuration.
|
||||
|
||||
## Constitution Check
|
||||
|
||||
*GATE: Passed before Phase 0 and re-checked after Phase 1 design.*
|
||||
|
||||
- **Enterprise experience — PASS**: The spec and UI contract define primary, loading, empty, ready,
|
||||
degraded, failed, restricted, stale, and recovery states with consistent terminology.
|
||||
- **Lifecycle safety — PASS**: Operation state is durable; setup, interruption, backup/restore,
|
||||
upgrade, retry, resume, rollback, and escalation responsibilities are explicitly mapped.
|
||||
- **Security and audit — PASS**: Existing server-side authorization is preserved; new audit and
|
||||
support-evidence contracts require redaction, actor, scope, result, and correlation identifiers.
|
||||
- **Entitlement and packaging — PASS**: The plan preserves internal identifiers, keeps Workstation
|
||||
separate, and requires portal/API/installer/Ansible/documentation/ISO consistency evidence.
|
||||
- **Evidence — PASS**: Quickstart validation distinguishes static, local, deployed, live-appliance,
|
||||
pilot, and release-artifact evidence.
|
||||
|
||||
Post-design re-check: PASS. No constitutional exception is required.
|
||||
|
||||
## Phased Design
|
||||
|
||||
### Phase 1 — Setup and Readiness
|
||||
|
||||
1. Establish canonical customer-facing state, severity, entitlement, operation, and error vocabulary.
|
||||
2. Make browser and console setup persist non-secret progress and expose safe resume/retry behaviour.
|
||||
3. Replace process-local install status as the sole truth with a durable operation record.
|
||||
4. Normalize readiness into a customer-impact view with freshness and actionable next steps.
|
||||
5. Align Workstation and representative Server setup/readiness behaviour.
|
||||
6. Validate WCAG 2.2 AA, clean install, interruption, restricted-network guidance, and artifact
|
||||
provenance before pilot.
|
||||
|
||||
### Phase 2 — Daily Administration
|
||||
|
||||
1. Introduce shared portal presentation helpers for status, errors, operations, entitlement, and
|
||||
accessible announcements while retaining static delivery.
|
||||
2. Apply the common shell and state contract first to dashboard, appliance, health, licensing,
|
||||
users/security, models, and knowledge journeys.
|
||||
3. Remove fabricated production examples or label them explicitly as samples.
|
||||
4. Provide a unified operations history for consequential and long-running actions.
|
||||
5. Add role-aware orientation and locally available contextual guidance.
|
||||
6. Complete the daily-administration portions of entitlement consistency and guided handover.
|
||||
|
||||
### Phase 3 — Recovery and Support
|
||||
|
||||
1. Model backup, restore, restart, upgrade, removal, diagnostic export, and escalation as authorized,
|
||||
durable operations.
|
||||
2. Add redacted support-evidence generation and correlation across API, audit, install, and service
|
||||
state.
|
||||
3. Define recovery preconditions, customer impact, confirmation, progress, outcome, and next action.
|
||||
4. Validate upgrade/interruption/rollback paths and controlled pilot results before general release.
|
||||
|
||||
Entitlement consistency is a cross-cutting workstream spanning all three delivery phases. Guided
|
||||
handover is accepted within Delivery Phase 2. These workstreams do not create additional delivery
|
||||
phases or alter the approved order.
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
specs/001-enterprise-experience/
|
||||
├── spec.md
|
||||
├── plan.md
|
||||
├── research.md
|
||||
├── data-model.md
|
||||
├── quickstart.md
|
||||
├── contracts/
|
||||
│ └── customer-experience-contract.md
|
||||
└── checklists/
|
||||
└── requirements.md
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```text
|
||||
autoinstall/
|
||||
├── websetup/server.py # browser setup and current process-local install state
|
||||
├── firstboot-setup.sh # console setup flow
|
||||
├── user-data* # ISO-specific first-boot entrypoints
|
||||
└── build-iso*.sh # Workstation/Server ISO build paths
|
||||
|
||||
cezen-portal/
|
||||
├── branding.js # shared branding/entitlement behaviour
|
||||
├── auth.js # session and role enforcement
|
||||
├── style.css # shared design/accessibility primitives
|
||||
├── index.html # primary landing experience
|
||||
├── appliance.html # readiness, license, audit, backup/restore
|
||||
├── health.html # subsystem health experience
|
||||
└── *.html # remaining administration and user journeys
|
||||
|
||||
ansible/roles/cezen-backend/
|
||||
├── files/main.py # API, SQLite model, audit, readiness, backups
|
||||
├── files/cezen_license.py # deployed entitlement helper
|
||||
├── files/cezen-api.service # runtime contract
|
||||
└── tasks/main.yml # backend deployment
|
||||
|
||||
ansible/roles/cezen-nginx/ # static portal deployment and routing
|
||||
scripts/cezen_license.py # canonical source entitlement helper
|
||||
scripts/cezen-backup.sh # appliance backup/restore utility
|
||||
install.sh # phase orchestration and install record
|
||||
ansible/{starter,entry,pro,max}.yml # Server deployment profiles
|
||||
```
|
||||
|
||||
**Structure Decision**: Extend the existing appliance package in place. Keep the static portal and
|
||||
single management service for this initiative; extract shared modules only where needed to enforce
|
||||
one state/operation contract. Treat `scripts/cezen_license.py` as the canonical entitlement source
|
||||
and keep deployed copies synchronized through explicit verification.
|
||||
|
||||
## Migration and Compatibility Strategy
|
||||
|
||||
- Additive SQLite changes MUST use idempotent migrations executed before new reads/writes; startup
|
||||
`CREATE TABLE IF NOT EXISTS` alone is insufficient for column evolution.
|
||||
- Existing endpoints remain compatible during each phase. New envelope fields are additive until all
|
||||
packaged portal consumers migrate.
|
||||
- Existing install and license JSON fields remain readable. New operation/progress data is separate
|
||||
and excludes raw signed license payloads.
|
||||
- Existing backups remain restorable; schema version and compatibility are checked before mutation.
|
||||
- Removal preserves backups by default, explicitly inventories retained/deleted data, and records the
|
||||
limits of rollback before confirmation.
|
||||
- Portal, API, installer, canonical/deployed license helpers, Ansible roles, docs, and ISO contents are
|
||||
compared during release validation.
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
No constitutional violations require justification.
|
||||
@@ -0,0 +1,115 @@
|
||||
# Validation Quickstart: Enterprise Appliance Experience Hardening
|
||||
|
||||
This guide defines the evidence path for implementation. Commands are representative and MUST be
|
||||
updated to the final test tooling before acceptance.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
- Clean checkout of the intended source revision.
|
||||
- One representative Nexus One AI Workstation target.
|
||||
- One representative Nexus One AI Server target with a valid supported tier.
|
||||
- Test licenses for valid, missing/staging, expired, invalid-signature, and mismatch states.
|
||||
- At least 10 representative administrator participants across internal validation and pilot.
|
||||
- A minimum 20-case customer-correctable failure corpus covering all specified failure categories.
|
||||
- Ability to simulate network, service, storage, and reboot interruption safely.
|
||||
- Supported desktop browser plus keyboard-only and representative assistive-technology setup.
|
||||
- Controlled pilot approval and rollback plan.
|
||||
|
||||
Never use production customer secrets or content in validation fixtures.
|
||||
|
||||
## 2. Static and Local Validation
|
||||
|
||||
1. Run Python syntax and focused unit/contract tests for readiness, entitlement, operation transitions,
|
||||
audit redaction, backup compatibility, and error envelopes.
|
||||
2. Run shell syntax checks for changed installer and ISO scripts.
|
||||
3. Run Ansible syntax checks for every affected Workstation/Server deployment path.
|
||||
4. Run portal checks for broken navigation, legacy naming, placeholder/sample data, inaccessible names,
|
||||
keyboard traps, contrast, and invalid markup.
|
||||
5. Confirm canonical and deployed license helpers produce identical entitlement results for the test
|
||||
matrix.
|
||||
6. Verify allowed and denied roles for every new operation, recovery, removal, diagnostic, and
|
||||
support-evidence interface.
|
||||
7. Run readiness, navigation-feedback, and operation-acknowledgement timing trials against SC-014,
|
||||
SC-015, and SC-016 and record conditions, sample count, and percentile results.
|
||||
|
||||
Expected outcome: all checks pass; any intentionally retained sample content is explicitly labelled;
|
||||
no signed license payload, token, credential, or customer content appears in outputs.
|
||||
|
||||
## 3. Phase 1 Clean-Install Journeys
|
||||
|
||||
Run the following on both the representative Workstation and Server:
|
||||
|
||||
1. Start from the supported clean image or installation baseline.
|
||||
2. Complete browser setup with valid network, customer, license, product/tier, and component choices.
|
||||
3. Repeat the supported console setup path.
|
||||
4. Verify progress survives browser refresh, session change, and setup-service restart.
|
||||
5. Verify the resulting readiness view identifies product, entitlement, freshness, degraded states,
|
||||
and correct next actions.
|
||||
6. Confirm locally available setup and recovery guidance works without public internet access.
|
||||
|
||||
Expected outcome: the administrator reaches a truthful ready or explicitly degraded state without
|
||||
undocumented intervention; Workstation never appears as a Server tier.
|
||||
|
||||
## 4. Phase 1 Failure and Recovery Matrix
|
||||
|
||||
For each applicable setup stage, simulate invalid input, network loss, service failure, storage
|
||||
shortage, license failure, interruption before reboot, interruption after reboot, and stale status.
|
||||
|
||||
Verify:
|
||||
|
||||
- completed safe steps and non-secret inputs are retained;
|
||||
- the operation has one durable identity and truthful lifecycle state;
|
||||
- duplicate/conflicting submissions are prevented;
|
||||
- error text explains impact and safe retry/resume/recovery/escalation;
|
||||
- audit and diagnostic evidence share the correlation ID;
|
||||
- no raw exception or secret appears in the customer experience.
|
||||
|
||||
## 5. Accessibility Validation
|
||||
|
||||
On every changed setup and portal page:
|
||||
|
||||
1. Complete the primary and failure-recovery journey using keyboard only.
|
||||
2. Verify focus order, visible focus, modal/confirmation behaviour, and return focus.
|
||||
3. Verify status, progress, errors, and completion are announced appropriately.
|
||||
4. Check contrast, non-colour cues, zoom/reflow, accessible names, headings, and landmarks.
|
||||
5. Run the selected automated WCAG checks and manually review failures or unsupported criteria.
|
||||
|
||||
Expected outcome: no unresolved WCAG 2.2 Level A or AA failure at phase acceptance.
|
||||
|
||||
## 6. Upgrade and Backup Compatibility
|
||||
|
||||
1. Create a verified backup from the supported pre-feature appliance version.
|
||||
2. Upgrade or reconfigure using the planned migration path.
|
||||
3. Confirm existing authentication, users, audit history, licensing, settings, and supported customer
|
||||
data remain usable.
|
||||
4. Exercise backup and restore with schema compatibility checks and a pre-restore safety snapshot.
|
||||
5. Interrupt the operation at safe test points and verify documented recovery.
|
||||
6. Exercise removal in a disposable environment; verify explicit retained/deleted data inventory,
|
||||
backup preservation, authorization, audit evidence, interruption outcome, and rollback limits.
|
||||
|
||||
Expected outcome: no silent data loss; incompatible restore is blocked before mutation; recovery
|
||||
evidence is sufficient for support.
|
||||
|
||||
## 7. Package and ISO Provenance
|
||||
|
||||
For each delivery candidate, record:
|
||||
|
||||
- source revision and working-tree status;
|
||||
- portal, backend, installer, Ansible, entitlement helper, and local guidance versions;
|
||||
- ISO/package filename, build time, size, and SHA-256 checksum;
|
||||
- proof that the artifact contains the accepted source copies;
|
||||
- successful representative boot/install journey.
|
||||
|
||||
Expected outcome: a release is never called current based only on source state or filename.
|
||||
|
||||
## 8. Pilot and Acceptance
|
||||
|
||||
1. Complete internal evidence review on Workstation and Server.
|
||||
2. Deploy only to approved controlled-pilot environments using the rollback plan.
|
||||
3. Capture task completion, recovery results, accessibility findings, support effort, and customer
|
||||
feedback without collecting protected content.
|
||||
4. Resolve and revalidate all critical customer-safety, task-completion, entitlement, and recovery
|
||||
findings.
|
||||
5. Obtain recorded joint approval from product ownership and delivery/support.
|
||||
|
||||
Only then is the phase eligible for general release.
|
||||
@@ -0,0 +1,94 @@
|
||||
# Research: Enterprise Appliance Experience Hardening
|
||||
|
||||
## Decision 1: Evolve the Existing Architecture
|
||||
|
||||
**Decision**: Retain the static portal, FastAPI management API, SQLite appliance store, shell/Ansible
|
||||
installer, Nginx, and systemd deployment model.
|
||||
|
||||
**Rationale**: The current architecture already exposes authentication, audit, readiness, entitlement,
|
||||
backup/restore, health, and installation flows. Enterprise quality depends first on consistent state,
|
||||
durability, recovery, and validation—not a framework rewrite that would expand risk.
|
||||
|
||||
**Alternatives considered**: Rebuild the portal as a single-page application; split the backend into
|
||||
services; adopt an external workflow engine. Deferred because none is required to satisfy Phase 1.
|
||||
|
||||
## Decision 2: Use Durable Operations as the Cross-Surface Backbone
|
||||
|
||||
**Decision**: Represent installation and later consequential actions as durable operation records
|
||||
with lifecycle, progress, actor, scope, timestamps, result, recovery action, and correlation ID.
|
||||
|
||||
**Rationale**: Browser setup currently keeps install status in process memory, while the API runs
|
||||
multiple workers and appliance actions can outlive sessions or processes. A durable record provides
|
||||
one truth for refresh, restart, audit, diagnostics, and support.
|
||||
|
||||
**Alternatives considered**: Continue process-local status; infer progress exclusively from logs; add
|
||||
a separate message broker. Process-local status is not recoverable, logs are not a stable customer
|
||||
contract, and a broker is unnecessary for the current appliance scale.
|
||||
|
||||
## Decision 3: Define One Customer-Facing State Vocabulary
|
||||
|
||||
**Decision**: Normalize state into `loading`, `empty`, `ready`, `degraded`, `failed`, `restricted`,
|
||||
`unavailable`, and `stale`, with severity, freshness, impact, and next action.
|
||||
|
||||
**Rationale**: Existing pages use several incompatible labels and colour treatments. A shared contract
|
||||
prevents each page from inventing meaning and supports accessibility and acceptance tests.
|
||||
|
||||
**Alternatives considered**: Preserve page-specific vocabularies; expose raw service states. Both
|
||||
produce inconsistent customer meaning and leak implementation concepts.
|
||||
|
||||
## Decision 4: Keep Entitlement Logic Canonical and Additive
|
||||
|
||||
**Decision**: Preserve Workstation separation and Server compatibility identifiers. Treat
|
||||
`scripts/cezen_license.py` as canonical and verify parity with installer/backend deployed copies.
|
||||
|
||||
**Rationale**: The repository already documents the separation and copies license helpers into more
|
||||
than one runtime location. Replacing identifiers would create avoidable upgrade and license risk.
|
||||
|
||||
**Alternatives considered**: Rename internal tiers; merge Workstation into the Server ladder; allow
|
||||
each surface to derive its own mapping. Rejected for compatibility and drift risk.
|
||||
|
||||
## Decision 5: Introduce Explicit SQLite Schema Evolution
|
||||
|
||||
**Decision**: Use versioned, idempotent database migrations for new operation/support-evidence fields
|
||||
and tables, with pre-change backup and compatibility checks.
|
||||
|
||||
**Rationale**: The backend creates many tables directly during startup. New enterprise lifecycle data
|
||||
must be safely introduced on existing customer appliances and included in backup/restore validation.
|
||||
|
||||
**Alternatives considered**: Add only new tables through startup creation; replace SQLite; reset data
|
||||
on upgrade. Startup creation lacks controlled evolution, replacement is disproportionate, and reset is
|
||||
unacceptable for customer appliances.
|
||||
|
||||
## Decision 6: Shared Portal Primitives Without Immediate Framework Migration
|
||||
|
||||
**Decision**: Add shared browser-native helpers and CSS primitives for states, operations, errors,
|
||||
focus, announcements, confirmation, and entitlement rather than rewriting all pages at once.
|
||||
|
||||
**Rationale**: The portal is a large static HTML/JavaScript surface already deployed by file sync.
|
||||
Shared primitives enable phased adoption and reduce visual/behavioural drift with minimal packaging
|
||||
change.
|
||||
|
||||
**Alternatives considered**: Full portal rewrite; page-by-page independent cleanup. A rewrite conflicts
|
||||
with phased risk reduction; independent cleanup preserves inconsistency.
|
||||
|
||||
## Decision 7: WCAG 2.2 AA Requires Automated and Manual Evidence
|
||||
|
||||
**Decision**: Combine automated checks with manual keyboard, focus, status-announcement, zoom/reflow,
|
||||
and representative assistive-technology journeys.
|
||||
|
||||
**Rationale**: Automated checks cannot prove complete accessibility, especially for dynamic status,
|
||||
error recovery, and consequential operations.
|
||||
|
||||
**Alternatives considered**: Automated checks only; informal review; AAA. The first two are
|
||||
insufficient for formal AA acceptance; AAA exceeds the approved scope.
|
||||
|
||||
## Decision 8: Release Through Evidence Gates
|
||||
|
||||
**Decision**: Require internal evidence, controlled pilot evidence, joint product and delivery/support
|
||||
approval, then general release; validate both source revision and packaged artifact identity.
|
||||
|
||||
**Rationale**: Installation and recovery changes need customer-like appliance evidence, while the
|
||||
repository contains multiple source and ISO delivery surfaces that can diverge.
|
||||
|
||||
**Alternatives considered**: Direct general release after local tests; UI-only acceptance; checksum
|
||||
without journey validation. Each leaves a material enterprise-appliance risk untested.
|
||||
@@ -0,0 +1,356 @@
|
||||
# Feature Specification: Enterprise Appliance Experience Hardening
|
||||
|
||||
**Feature Branch**: `main`
|
||||
|
||||
**Created**: 2026-07-12
|
||||
|
||||
**Status**: Draft
|
||||
|
||||
**Input**: User description: "Make Nexus One AI a top-notch customer experience that feels like an enterprise appliance."
|
||||
|
||||
## Clarifications
|
||||
|
||||
### Session 2026-07-12
|
||||
|
||||
- Q: Should enterprise-experience hardening ship as phases or as one complete redesign? → A: Phased
|
||||
rollout: setup/readiness first, daily administration second, recovery/support third.
|
||||
- Q: Which product configurations must Phase 1 cover? → A: One representative Workstation and one
|
||||
representative Server configuration.
|
||||
- Q: How should each phase progress to general release? → A: Internal validation, then a controlled
|
||||
customer pilot, then general release.
|
||||
- Q: Who approves completion of each phase? → A: Product owner and delivery/support jointly approve.
|
||||
- Q: What accessibility standard applies to customer-facing setup and portal experiences? → A:
|
||||
WCAG 2.2 Level AA.
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
|
||||
### User Story 1 - Confident First-Time Setup (Priority: P1)
|
||||
|
||||
As a customer administrator, I can move from first boot through a validated, ready-to-use Nexus One
|
||||
AI appliance without needing undocumented knowledge or encountering contradictory product, tier, or
|
||||
license information.
|
||||
|
||||
**Why this priority**: Installation is the customer's first direct experience of the product and a
|
||||
failed or ambiguous setup prevents every later outcome.
|
||||
|
||||
**Independent Test**: A representative administrator can complete setup on a supported appliance,
|
||||
understand every decision, recover from correctable input or service failures, and reach a clearly
|
||||
identified ready state using only product-provided guidance.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a supported new appliance, **When** the administrator completes setup with valid inputs,
|
||||
**Then** each step explains its purpose, validates before commitment, preserves previous choices,
|
||||
and ends with an accurate readiness summary and next actions.
|
||||
2. **Given** invalid network, customer, license, tier, or component input, **When** validation fails,
|
||||
**Then** the administrator sees a plain-language explanation beside the affected decision and can
|
||||
correct it without restarting the entire journey.
|
||||
3. **Given** installation is interrupted or a required component fails, **When** the administrator
|
||||
returns to the appliance, **Then** the product shows the last reliable state, customer impact,
|
||||
diagnostic reference, and safe resume or recovery action.
|
||||
4. **Given** hardware or licensing prevents a tier or component selection, **When** options are shown,
|
||||
**Then** unavailable choices are explained using customer-facing product names and no unsupported
|
||||
configuration can be committed accidentally.
|
||||
|
||||
---
|
||||
|
||||
### User Story 2 - Coherent Daily Administration (Priority: P1)
|
||||
|
||||
As an authorized administrator, I can understand appliance health, capacity, licensing, security,
|
||||
users, models, knowledge, and operational work from one coherent product experience.
|
||||
|
||||
**Why this priority**: Daily confidence depends on the portal behaving as a unified control plane,
|
||||
not a collection of disconnected pages and tools.
|
||||
|
||||
**Independent Test**: An administrator can identify overall appliance state, locate the five most
|
||||
common administrative tasks, complete each task, and interpret success or failure without external
|
||||
guidance.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a healthy appliance, **When** the administrator signs in, **Then** the landing experience
|
||||
presents current readiness, important alerts, capacity context, license/support state, and the
|
||||
highest-value next actions without fabricated or stale status.
|
||||
2. **Given** the administrator moves between portal areas, **When** equivalent concepts or actions
|
||||
appear, **Then** naming, navigation, status severity, interaction, and confirmation patterns remain
|
||||
consistent.
|
||||
3. **Given** an operation is long-running, **When** it starts, progresses, completes, or fails,
|
||||
**Then** its state remains discoverable and the administrator is not left uncertain whether the
|
||||
action occurred.
|
||||
4. **Given** an empty, loading, restricted, partially available, or failed state, **When** a page is
|
||||
viewed, **Then** the state is distinguishable, truthful, and accompanied by an appropriate action.
|
||||
|
||||
---
|
||||
|
||||
### User Story 3 - Safe Operations and Recovery (Priority: P1)
|
||||
|
||||
As an appliance operator or support engineer, I can diagnose and recover common operational problems
|
||||
without exposing secrets, damaging customer data, or relying on source-code knowledge.
|
||||
|
||||
**Why this priority**: Enterprise trust is established during failure and recovery, not only during
|
||||
normal operation.
|
||||
|
||||
**Independent Test**: A trained operator can use product-provided health, audit, diagnostic, backup,
|
||||
and recovery guidance to resolve or escalate representative failures with a complete evidence trail.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** one or more services are degraded, **When** the operator reviews system status,
|
||||
**Then** the product distinguishes customer impact from technical detail and identifies safe checks,
|
||||
recovery actions, and escalation evidence.
|
||||
2. **Given** a backup, restore, upgrade, restart, or other consequential action, **When** it is
|
||||
requested, **Then** prerequisites, scope, expected disruption, confirmation, progress, result, and
|
||||
rollback or recovery guidance are available.
|
||||
3. **Given** diagnostics are generated, **When** they are viewed or exported, **Then** secrets and
|
||||
protected customer content are excluded while timestamps, correlation details, and relevant state
|
||||
remain sufficient for support.
|
||||
4. **Given** a privileged or security-sensitive action occurs, **When** audit history is reviewed,
|
||||
**Then** it identifies who acted, what category of change occurred, when it occurred, the result,
|
||||
and the affected scope without recording secret values.
|
||||
5. **Given** an authorized administrator needs to remove appliance software, **When** removal is
|
||||
requested, **Then** retained and deleted data, service impact, prerequisites, confirmation,
|
||||
progress, result, rollback limits, and recovery or escalation guidance are explicit.
|
||||
|
||||
---
|
||||
|
||||
### User Story 4 - Predictable Product Entitlements (Priority: P2)
|
||||
|
||||
As a customer or Cezen delivery team member, I see capabilities that accurately match the purchased
|
||||
Nexus One AI product, licensed tier, provisioned components, and supported hardware.
|
||||
|
||||
**Why this priority**: Contradictions between sales labels, licenses, installation options, portal
|
||||
capabilities, and documentation undermine confidence and create field-support failures.
|
||||
|
||||
**Independent Test**: Representative Workstation and Server S/M/L/Max configurations show the correct
|
||||
labels, permitted actions, explanatory restrictions, and matching documentation throughout setup and
|
||||
daily administration.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** any supported product and tier, **When** product identity or entitlement is displayed,
|
||||
**Then** customer-facing labels are consistent while internal compatibility identifiers remain
|
||||
hidden unless diagnostically necessary.
|
||||
2. **Given** a capability is not licensed, provisioned, supported by hardware, or currently available,
|
||||
**When** the customer encounters it, **Then** the product distinguishes those causes and provides
|
||||
the appropriate commercial, provisioning, hardware, or recovery next action.
|
||||
3. **Given** a package or release is prepared, **When** its customer experience is accepted,
|
||||
**Then** installer, portal, backend behaviour, deployment roles, documentation, and delivery
|
||||
artifact agree on product names and capability boundaries.
|
||||
|
||||
---
|
||||
|
||||
### User Story 5 - Guided Evaluation and Handover (Priority: P2)
|
||||
|
||||
As a customer evaluator or newly assigned administrator, I can understand what the appliance is,
|
||||
verify that it is ready, discover its key capabilities, and find authoritative help without a live
|
||||
Cezen walkthrough.
|
||||
|
||||
**Why this priority**: A polished enterprise product must remain understandable after the sales or
|
||||
delivery team leaves.
|
||||
|
||||
**Independent Test**: A representative evaluator can identify product purpose, current readiness,
|
||||
licensed capabilities, key first tasks, help resources, and support evidence within ten minutes.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a newly provisioned appliance, **When** an evaluator first enters the portal, **Then** the
|
||||
experience provides role-appropriate orientation without blocking experienced users.
|
||||
2. **Given** a user needs help, **When** contextual and central help are accessed, **Then** guidance
|
||||
matches the current product terminology and points to safe, relevant actions.
|
||||
3. **Given** the appliance is operating in a restricted network, **When** help or diagnostics are
|
||||
needed, **Then** essential guidance remains locally available and external dependencies are clearly
|
||||
identified.
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- Browser refresh, session expiry, duplicate submission, or navigation during a long-running action.
|
||||
- Power, network, storage, GPU, or dependent-service loss during setup or maintenance.
|
||||
- License missing, malformed, expired, hardware-bound incorrectly, or valid for a different tier.
|
||||
- Appliance provisioned above or below current license or hardware capability.
|
||||
- Partial installation where some tools are intentionally omitted and others failed unexpectedly.
|
||||
- Empty system, first user, no models, no documents, no audit events, and no historical health data.
|
||||
- Multiple simultaneous administrators attempting conflicting consequential operations.
|
||||
- Clock drift or unavailable time source affecting licenses, certificates, logs, and audit ordering.
|
||||
- Insufficient storage or capacity discovered before and during a consequential operation.
|
||||
- Diagnostic export requested when protected customer documents or secrets are present.
|
||||
- Upgrade or restart interrupted after state changes but before completion is recorded.
|
||||
- Removal interrupted after services or data have been changed but before completion is recorded.
|
||||
- Portal information is temporarily older than the underlying appliance state.
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: The product MUST provide a continuous, understandable journey from first boot to a
|
||||
verified ready state.
|
||||
- **FR-002**: The product MUST present a unified view of overall readiness, degraded conditions,
|
||||
important alerts, capacity context, license/support state, and actionable next steps.
|
||||
- **FR-003**: Every customer-facing status MUST distinguish at least loading, empty, ready, degraded,
|
||||
failed, restricted, and unavailable states when those states are possible.
|
||||
- **FR-004**: Every customer-correctable error MUST explain the problem, affected scope, and safe next
|
||||
action without exposing implementation-only codes as the primary message.
|
||||
- **FR-005**: Long-running and consequential operations MUST expose initiation, progress, completion,
|
||||
failure, and recovery state that remains discoverable after navigation or session interruption.
|
||||
- **FR-006**: Consequential operations MUST identify prerequisites, scope, expected disruption, and
|
||||
recovery implications before confirmation.
|
||||
- **FR-007**: The product MUST prevent accidental duplicate or conflicting consequential operations.
|
||||
- **FR-008**: Navigation, product terminology, severity levels, interaction patterns, confirmations,
|
||||
and feedback MUST be consistent across customer-facing areas.
|
||||
- **FR-009**: Customer-visible operational values MUST identify their freshness or last-observed time
|
||||
when they are not guaranteed to be live.
|
||||
- **FR-010**: The product MUST provide contextual help for setup, licensing, health, models, knowledge,
|
||||
users, security, backup, restore, upgrade, and recovery journeys.
|
||||
- **FR-011**: Essential setup, operational, recovery, and escalation guidance MUST remain available on
|
||||
the appliance without requiring public internet access.
|
||||
- **FR-012**: Role restrictions MUST be explained without revealing protected data or presenting
|
||||
controls that appear usable but always fail.
|
||||
- **FR-013**: Privileged, security-sensitive, licensing, configuration, and lifecycle actions MUST
|
||||
create an audit record containing actor, time, action category, affected scope, and outcome.
|
||||
- **FR-014**: Diagnostic views and exports MUST omit secrets, credentials, license payloads, and
|
||||
protected customer content by default.
|
||||
- **FR-015**: Support evidence MUST include enough timestamps, correlation details, product identity,
|
||||
entitlement state, and component health to reproduce or escalate a reported issue.
|
||||
- **FR-016**: The product MUST accurately distinguish licensed, provisioned, hardware-supported, and
|
||||
currently available capability states.
|
||||
- **FR-017**: Workstation and Server S/M/L/Max naming and capabilities MUST remain consistent across
|
||||
setup, portal, documentation, support evidence, and release artifacts.
|
||||
- **FR-018**: The product MUST provide a concise first-use orientation and a persistent route to
|
||||
authoritative help without obstructing returning users.
|
||||
- **FR-019**: Every release affecting customer journeys MUST identify all changed surfaces and verify
|
||||
that the packaged delivery contains the accepted versions.
|
||||
- **FR-020**: Known degraded capabilities MUST be visible to affected users and MUST NOT be represented
|
||||
as healthy or complete.
|
||||
- **FR-021**: The product MUST preserve customer-entered setup data and completed safe steps when a
|
||||
recoverable interruption occurs.
|
||||
- **FR-022**: Recovery actions MUST clearly distinguish safe retry, resume, rollback, restore, restart,
|
||||
and escalation choices when applicable.
|
||||
- **FR-023**: Delivery MUST use three independently accepted phases in this order: setup and readiness,
|
||||
daily administration, then recovery and support. Each phase MUST satisfy its applicable quality gates
|
||||
before the next phase is accepted.
|
||||
- **FR-024**: Phase 1 acceptance MUST include one representative Workstation configuration and one
|
||||
representative Server configuration; shared behaviour MUST pass on both, while tier-specific
|
||||
behaviour MUST be explicitly identified for later matrix coverage.
|
||||
- **FR-025**: Each phase MUST pass internal validation and a controlled customer pilot before general
|
||||
release. Pilot findings that affect customer safety, task completion, entitlement accuracy, or
|
||||
recovery MUST be resolved and revalidated before promotion.
|
||||
- **FR-026**: Phase acceptance MUST require recorded joint approval from the product owner and an
|
||||
accountable delivery/support representative after reviewing customer-experience and operational
|
||||
evidence.
|
||||
- **FR-027**: Customer-facing setup and portal journeys MUST conform to WCAG 2.2 Level AA, including
|
||||
keyboard operation, focus visibility, semantic structure, accessible names, contrast, status
|
||||
announcements, error identification, and non-colour status cues.
|
||||
- **FR-028**: Appliance software removal MUST be an authorized, auditable, durable operation that
|
||||
identifies retained and deleted data, requires explicit confirmation, protects backups by default,
|
||||
and provides truthful completion, rollback-limit, recovery, and escalation outcomes.
|
||||
- **FR-029**: Every new operation, recovery, removal, diagnostic, and support-evidence interface MUST
|
||||
enforce server-side authorization and MUST be covered by allowed-role and denied-role tests.
|
||||
|
||||
### Enterprise Appliance Requirements *(mandatory)*
|
||||
|
||||
- **EA-001 Customer Experience**: All primary journeys and their empty, loading, restricted, degraded,
|
||||
failure, and recovery states MUST use consistent Nexus One AI language and actionable guidance.
|
||||
- **EA-002 Security & Audit**: Authorization MUST be enforced for every privileged action; audit and
|
||||
diagnostics MUST retain useful evidence while excluding secret values and protected content.
|
||||
- **EA-003 Lifecycle & Recovery**: Setup, configuration, restart, upgrade, backup, restore, and
|
||||
interruption behaviour MUST define safe preconditions, progress, outcomes, and recovery paths.
|
||||
- **EA-004 Entitlement & Packaging**: Workstation and Server tier behaviour MUST remain consistent with
|
||||
licensed, provisioned, and hardware-supported capabilities across every delivery surface.
|
||||
- **EA-005 Operability**: Health, diagnostics, logs, local help, and escalation evidence MUST support
|
||||
customer-controlled and restricted-network operation.
|
||||
|
||||
### Key Entities
|
||||
|
||||
- **Appliance Readiness**: Overall customer-relevant state, affected capabilities, freshness, alerts,
|
||||
and next actions.
|
||||
- **Operation**: A consequential or long-running activity with actor, scope, lifecycle state, progress,
|
||||
result, and recovery options.
|
||||
- **Entitlement State**: Product category, commercial tier, licensed capabilities, provisioned
|
||||
components, hardware support, and current availability.
|
||||
- **Support Evidence Package**: Redacted product identity, timestamps, correlation information,
|
||||
entitlement summary, health state, and relevant operational history.
|
||||
- **Audit Event**: Actor, time, action category, affected scope, outcome, and correlation reference,
|
||||
excluding protected values.
|
||||
- **Guidance Item**: Locally available contextual instructions associated with a journey, state, or
|
||||
recovery action.
|
||||
|
||||
## Success Criteria *(mandatory)*
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: At least 90% of representative first-time administrators complete supported setup and
|
||||
reach a verified ready state without undocumented assistance.
|
||||
- **SC-002**: At least 90% of representative administrators can identify overall appliance health,
|
||||
license state, and the correct next action for a degraded condition within two minutes.
|
||||
- **SC-003**: At least 95% of customer-correctable failures tested provide an accurate explanation and
|
||||
a successful safe recovery path without restarting the entire journey.
|
||||
- **SC-004**: The five most common administrative tasks can each be located within three navigation
|
||||
decisions and completed without external documentation by at least 90% of representative users.
|
||||
- **SC-005**: 100% of tested privileged, security-sensitive, licensing, configuration, and lifecycle
|
||||
actions produce the required audit evidence without secret values.
|
||||
- **SC-006**: 100% of representative Workstation and Server tier test cases display consistent product
|
||||
names and capability boundaries across setup, portal, help, and release acceptance evidence.
|
||||
- **SC-007**: All tested consequential operations retain or recover a truthful final state after page
|
||||
refresh, session expiry, or simulated interruption.
|
||||
- **SC-008**: A trained operator can diagnose, safely recover, or prepare a complete escalation package
|
||||
for each agreed common failure scenario within 15 minutes.
|
||||
- **SC-009**: No accepted release contains placeholder content, dead controls, unexplained primary
|
||||
error codes, fabricated production values, or customer-visible legacy product naming.
|
||||
- **SC-010**: Every accepted customer-facing release has traceable evidence for primary journeys,
|
||||
failure states, entitlement boundaries, recovery impact, and packaged artifact identity.
|
||||
- **SC-011**: Phase 1 produces passing setup and readiness evidence on both one representative
|
||||
Workstation and one representative Server configuration.
|
||||
- **SC-012**: Every general release has recorded internal-validation and controlled-pilot evidence,
|
||||
with no unresolved critical customer-safety, task-completion, entitlement, or recovery findings.
|
||||
- **SC-013**: All customer-facing setup and portal pages changed by a phase pass automated checks and
|
||||
representative manual keyboard and assistive-technology checks for WCAG 2.2 Level AA conformance,
|
||||
with no unresolved Level A or Level AA failures at acceptance.
|
||||
- **SC-014**: Under normal representative appliance conditions, readiness is displayed within 10
|
||||
seconds of portal entry in at least 95% of measured trials.
|
||||
- **SC-015**: Local navigation provides visible feedback within 1 second in at least 95% of measured
|
||||
interactions on supported browsers.
|
||||
- **SC-016**: Consequential-operation submission provides acknowledgement or a validation result
|
||||
within 2 seconds in at least 95% of measured trials under normal appliance conditions.
|
||||
|
||||
### Verification Evidence *(mandatory)*
|
||||
|
||||
- **Static/local evidence**: Terminology, navigation, state coverage, authorization, redaction, audit,
|
||||
entitlement, accessibility, and journey checks defined per affected surface.
|
||||
- **Deployment evidence**: A clean supported installation plus upgrade or reconfiguration from a
|
||||
representative existing appliance, including interruption and recovery scenarios.
|
||||
- **Live-appliance evidence**: Role-based setup and daily-administration journeys on representative
|
||||
Workstation and Server configurations, with healthy, empty, restricted, degraded, and failed states.
|
||||
- **Release artifact evidence**: Recorded source revision, package identity, build time, checksum, and
|
||||
confirmation that accepted portal, service, deployment, help, and entitlement content is included.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- This feature hardens the existing Nexus One AI product rather than replacing its architecture.
|
||||
- The first release targets current supported desktop browsers used on the customer network.
|
||||
- Existing authentication, product categories, Server tier identifiers, licensing rules, and customer
|
||||
data remain authoritative unless a later specification explicitly changes them.
|
||||
- The work includes the first-boot setup and customer portal plus the supporting operational behaviour
|
||||
necessary to make those journeys truthful.
|
||||
- Delivery is phased: setup/readiness first, daily administration second, and recovery/support third;
|
||||
this ordering does not remove cross-phase consistency requirements.
|
||||
- Public internet access cannot be assumed after installation.
|
||||
- Exact capacity and performance thresholds will be set per product/tier during planning using
|
||||
validated hardware and workload evidence.
|
||||
- The delivery team will identify the most common administrative tasks and failure scenarios from
|
||||
product telemetry where available, support history, and field experience before acceptance testing.
|
||||
- Percentage-based administrator outcomes use at least 10 representative participants across internal
|
||||
validation and controlled pilot; results report the participant count and product configuration.
|
||||
- The customer-correctable failure corpus contains at least 20 representative cases across input,
|
||||
entitlement, network, service, storage, interruption, and stale-state categories.
|
||||
- Audit completeness is measured against a reviewed inventory of every privileged,
|
||||
security-sensitive, licensing, configuration, lifecycle, removal, and support-evidence action.
|
||||
- Mobile-native applications, a complete visual rebrand, new commercial tiers, and replacement of
|
||||
underlying third-party tools are outside this feature unless separately specified.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Introducing new commercial product categories or changing purchased entitlement definitions.
|
||||
- Replacing underlying AI, observability, notebook, or document-processing tools solely for visual
|
||||
consistency.
|
||||
- Claiming high availability, redundancy, offline model availability, or recovery objectives that the
|
||||
deployed product has not been designed and validated to provide.
|
||||
- Implementing feature changes during this specification phase.
|
||||
@@ -0,0 +1,249 @@
|
||||
# Tasks: Enterprise Appliance Experience Hardening
|
||||
|
||||
**Input**: Design documents from `specs/001-enterprise-experience/`
|
||||
|
||||
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`,
|
||||
`contracts/customer-experience-contract.md`, `quickstart.md`
|
||||
|
||||
**Tests**: Required by the constitution and specification. Contract, journey, accessibility,
|
||||
deployment, recovery, and artifact-evidence tasks are included.
|
||||
|
||||
**Organization**: Tasks are grouped by user story. Phase 1 product delivery consists of Setup,
|
||||
Foundational, and User Story 1; later story phases remain separately acceptable increments.
|
||||
|
||||
## Format: `[ID] [P?] [Story] Description`
|
||||
|
||||
- **[P]**: Can proceed in parallel because it targets independent files after prerequisites pass.
|
||||
- **[Story]**: Maps directly to the numbered user story in `spec.md`.
|
||||
- Every implementation task names its expected repository path.
|
||||
|
||||
## Phase 1: Setup and Verification Infrastructure
|
||||
|
||||
**Purpose**: Establish safe migration, testing, accessibility, and packaging evidence before product
|
||||
behaviour changes.
|
||||
|
||||
- [x] T001 Create the Phase 1 evidence manifest template in `specs/001-enterprise-experience/evidence/phase1-manifest.md`
|
||||
- [x] T002 [P] Add Python test configuration and fixtures for isolated appliance data in `tests/conftest.py`
|
||||
- [x] T003 [P] Add browser journey and accessibility test configuration in `tests/browser/README.md`
|
||||
- [x] T004 [P] Add shell and Ansible validation commands to `tests/deployment/README.md`
|
||||
- [x] T005 Document the SQLite schema-version and rollback procedure in `specs/001-enterprise-experience/migrations.md`
|
||||
- [x] T006 Record the supported pre-feature appliance baseline and restore fixture requirements in `tests/fixtures/README.md`
|
||||
- [x] T007 Verify no product code changes are required to create the test harness and capture the review in `specs/001-enterprise-experience/evidence/phase1-manifest.md`
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Foundational Customer-Experience Contracts
|
||||
|
||||
**Purpose**: Implement shared contracts that block all customer-journey work.
|
||||
|
||||
**Critical**: No user story implementation begins until these tasks pass review.
|
||||
|
||||
- [x] T008 Add idempotent schema-version and migration runner tests in `tests/backend/test_migrations.py`
|
||||
- [x] T009 Implement additive SQLite schema-version and migration support in `ansible/roles/cezen-backend/files/main.py`
|
||||
- [x] T010 Add customer-state, error-envelope, entitlement-reason, redaction, and allowed/denied-role contract tests in `tests/backend/test_experience_contracts.py`
|
||||
- [x] T011 Implement versioned customer-state and error-envelope helpers in `ansible/roles/cezen-backend/files/main.py`
|
||||
- [x] T012 Add durable Operation lifecycle, transition, conflict, idempotency, and server-side authorization tests in `tests/backend/test_operations.py`
|
||||
- [x] T013 Implement the Operation store and lifecycle rules in `ansible/roles/cezen-backend/files/main.py`
|
||||
- [x] T014 Add audit correlation and secret-redaction tests in `tests/backend/test_audit_redaction.py`
|
||||
- [x] T015 Extend audit helpers with allowlisted detail and correlation IDs in `ansible/roles/cezen-backend/files/main.py`
|
||||
- [x] T016 [P] Create shared accessible state, alert, operation, and confirmation styles in `cezen-portal/style.css`
|
||||
- [x] T017 [P] Create shared browser helpers for state rendering, freshness, errors, focus, and announcements in `cezen-portal/experience.js`
|
||||
- [x] T018 [P] Add canonical customer-facing product and entitlement vocabulary in `cezen-portal/branding.js`
|
||||
- [x] T019 Synchronize canonical license logic into the deployed backend copy and add parity verification in `tests/backend/test_license_parity.py`
|
||||
- [x] T020 Verify the foundational contract against `specs/001-enterprise-experience/contracts/customer-experience-contract.md` and record results in `specs/001-enterprise-experience/evidence/phase1-manifest.md`
|
||||
|
||||
**Checkpoint**: Durable operations, safe migrations, redacted audit evidence, and shared accessible
|
||||
presentation contracts are independently verified.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: User Story 1 — Confident First-Time Setup (Priority: P1) — Phase 1 MVP
|
||||
|
||||
**Goal**: A customer administrator completes or safely resumes setup and reaches a truthful readiness
|
||||
state on both a representative Workstation and Server.
|
||||
|
||||
**Independent Test**: Complete browser and console setup with valid, invalid, interrupted, stale,
|
||||
restricted-network, Workstation, and Server scenarios; refresh or restart during installation and
|
||||
verify the same durable operation, accurate readiness, and safe next action remain available.
|
||||
|
||||
### Tests for User Story 1
|
||||
|
||||
- [x] T021 [P] [US1] Add browser setup validation, duplicate-submit, refresh, interruption, and 2-second acknowledgement timing tests in `tests/browser/test_setup_journey.py`
|
||||
- [x] T022 [P] [US1] Add console setup valid, invalid-license, and resume scenario tests in `tests/deployment/test_firstboot_setup.py`
|
||||
- [x] T023 [P] [US1] Add readiness state, freshness, entitlement-reason, remediation, and 10-second display timing tests in `tests/backend/test_readiness.py`
|
||||
- [x] T024 [P] [US1] Add WCAG 2.2 AA automated and manual-check definitions for setup/readiness in `tests/accessibility/phase1-checklist.md`
|
||||
- [x] T025 [P] [US1] Add Workstation-versus-Server setup matrix fixtures in `tests/fixtures/setup-matrix.json`
|
||||
|
||||
### Implementation for User Story 1
|
||||
|
||||
- [x] T026 [US1] Persist non-secret browser setup progress and durable installation operation state in `autoinstall/websetup/server.py`
|
||||
- [x] T027 [US1] Replace process-local-only progress rendering with resumable operation polling and accessible announcements in `autoinstall/websetup/server.py`
|
||||
- [x] T028 [US1] Preserve safe completed steps and expose retry, resume, reboot, recovery, and escalation outcomes in `autoinstall/firstboot-setup.sh`
|
||||
- [x] T029 [US1] Align browser and console setup labels, validation, Workstation separation, and Server tier reasons across `autoinstall/websetup/server.py` and `autoinstall/firstboot-setup.sh`
|
||||
- [x] T030 [US1] Extend readiness aggregation with canonical state, severity, freshness, customer impact, affected capabilities, and next actions in `ansible/roles/cezen-backend/files/main.py`
|
||||
- [x] T031 [US1] Update the appliance readiness UI to consume the versioned contract and shared experience helpers in `cezen-portal/appliance.html`
|
||||
- [x] T032 [US1] Update the primary landing readiness experience to show truthful current or stale state and highest-value next actions in `cezen-portal/index.html`
|
||||
- [x] T033 [US1] Update health rendering to distinguish unreachable, degraded dependency, unavailable capability, and stale observation in `cezen-portal/health.html`
|
||||
- [x] T034 [US1] Add local setup, interruption, readiness, and escalation guidance in `cezen-portal/quickstart.html` and `cezen-portal/troubleshooting.html`
|
||||
- [x] T035 [US1] Add schema migration, operation recovery, and portal deployment steps to `ansible/roles/cezen-backend/tasks/main.yml` and `ansible/roles/cezen-nginx/tasks/main.yml`
|
||||
- [ ] T036 [US1] Verify clean install, interruption, restricted-network guidance, and WCAG evidence on a representative Workstation and record it in `specs/001-enterprise-experience/evidence/workstation-phase1.md`
|
||||
- [ ] T037 [US1] Verify clean install, interruption, restricted-network guidance, and WCAG evidence on a representative Server and record it in `specs/001-enterprise-experience/evidence/server-phase1.md`
|
||||
- [ ] T038 [US1] Verify source-to-package and source-to-ISO provenance for all Phase 1 surfaces and record checksums in `specs/001-enterprise-experience/evidence/phase1-manifest.md`
|
||||
|
||||
**Checkpoint**: User Story 1 and product Phase 1 pass internal evidence review on Workstation and
|
||||
Server and are eligible for controlled pilot, not yet general release.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Delivery Phase 2 — User Story 2: Coherent Daily Administration (Priority: P1)
|
||||
|
||||
**Goal**: Administrators understand current appliance state and complete common daily tasks through a
|
||||
consistent, truthful control-plane experience.
|
||||
|
||||
**Independent Test**: A representative administrator locates and completes the five agreed common
|
||||
tasks within three navigation decisions, with consistent loading, empty, ready, degraded, failed,
|
||||
restricted, unavailable, and stale behaviour.
|
||||
|
||||
- [ ] T039 [P] [US2] Define five administration journeys, at least 10 representative participants, and acceptance scoring in `tests/browser/daily-administration.md`
|
||||
- [ ] T040 [P] [US2] Add shared navigation, 1-second feedback timing, status, error, operation, and freshness browser tests in `tests/browser/test_daily_administration.py`
|
||||
- [ ] T041 [US2] Apply the common navigation and state shell to dashboard and appliance journeys in `cezen-portal/dashboard.html` and `cezen-portal/appliance.html`
|
||||
- [ ] T042 [US2] Apply the common operation and entitlement contract to model and knowledge journeys in `cezen-portal/models-admin.html` and `cezen-portal/knowledge.html`
|
||||
- [ ] T043 [US2] Apply role-aware restriction, error, and confirmation behaviour to users and security journeys in `cezen-portal/users.html` and `cezen-portal/security.html`
|
||||
- [ ] T044 [US2] Expose role-filtered recent and active durable operations in `ansible/roles/cezen-backend/files/main.py` and `cezen-portal/appliance.html`
|
||||
- [ ] T045 [US2] Audit all remaining portal pages for placeholder, fabricated, loading, empty, degraded, dead-control, and legacy-name states and record findings in `specs/001-enterprise-experience/evidence/portal-audit.md`
|
||||
- [ ] T046 [US2] Resolve accepted portal-audit findings in affected files under `cezen-portal/`
|
||||
- [ ] T047 [US2] Validate the five administration journeys and WCAG 2.2 AA evidence and record results in `specs/001-enterprise-experience/evidence/phase2-administration.md`
|
||||
|
||||
**Checkpoint**: User Story 2 passes independent task-completion and accessibility acceptance.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Delivery Phase 3 — User Story 3: Safe Operations and Recovery (Priority: P1)
|
||||
|
||||
**Goal**: Operators diagnose, recover, or escalate common failures using safe actions and redacted,
|
||||
correlated evidence.
|
||||
|
||||
**Independent Test**: For each agreed failure, an operator reaches safe recovery or produces a
|
||||
complete redacted escalation package within 15 minutes.
|
||||
|
||||
- [ ] T048 [P] [US3] Add authorized/denied backup, restore, restart, upgrade, removal, conflict, and interruption tests in `tests/backend/test_recovery_operations.py`
|
||||
- [ ] T049 [P] [US3] Add support-evidence authorization, allowlist, redaction, and checksum tests in `tests/backend/test_support_evidence.py`
|
||||
- [ ] T050 [US3] Model backup, restore, and removal as authorized durable operations with preconditions and recovery outcomes in `ansible/roles/cezen-backend/files/main.py`
|
||||
- [ ] T051 [US3] Add versioned redacted support-evidence generation in `ansible/roles/cezen-backend/files/main.py`
|
||||
- [ ] T052 [US3] Add safe operation progress, removal inventory, recovery, and diagnostic-export experiences in `cezen-portal/appliance.html`
|
||||
- [ ] T053 [US3] Align command-line backup/restore evidence and implement backup-preserving removal in `scripts/cezen-backup.sh` and `scripts/cezen-remove.sh`
|
||||
- [ ] T054 [US3] Add locally available recovery and escalation playbooks in `cezen-portal/troubleshooting.html`
|
||||
- [ ] T055 [US3] Validate the 20-case failure corpus, backup/restore/removal compatibility, interruption, authorization, and 15-minute escalation outcomes in `specs/001-enterprise-experience/evidence/phase3-recovery.md`
|
||||
|
||||
**Checkpoint**: User Story 3 passes independent recovery, redaction, correlation, and support evidence
|
||||
acceptance.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Cross-Cutting Workstream — User Story 4: Predictable Product Entitlements (Priority: P2)
|
||||
|
||||
**Goal**: Workstation and Server customers see capability states that accurately distinguish license,
|
||||
provisioning, hardware, and runtime causes.
|
||||
|
||||
**Independent Test**: The agreed Workstation and Server S/M/L/Max matrix produces consistent labels,
|
||||
permitted actions, restrictions, and help across setup, portal, backend, deployment, and artifacts.
|
||||
|
||||
- [ ] T056 [P] [US4] Expand valid, missing, expired, mismatch, hardware, and provisioning entitlement fixtures in `tests/fixtures/entitlement-matrix.json`
|
||||
- [ ] T057 [P] [US4] Add cross-copy and cross-surface entitlement matrix tests in `tests/backend/test_entitlement_matrix.py`
|
||||
- [ ] T058 [US4] Return distinct licensed, provisioned, hardware-supported, and currently available reasons in `ansible/roles/cezen-backend/files/main.py`
|
||||
- [ ] T059 [US4] Render commercial labels and reason-specific next actions consistently in `cezen-portal/branding.js` and `cezen-portal/appliance.html`
|
||||
- [ ] T060 [US4] Align installer and deployment role capability decisions in `install.sh`, `autoinstall/firstboot-setup.sh`, and `ansible/{starter,entry,pro,max}.yml`
|
||||
- [ ] T061 [US4] Verify documentation and packaged artifacts against the entitlement matrix in `specs/001-enterprise-experience/evidence/entitlement-matrix.md`
|
||||
|
||||
**Checkpoint**: User Story 4 passes the full product/tier consistency matrix.
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Delivery Phase 2 Workstream — User Story 5: Guided Evaluation and Handover (Priority: P2)
|
||||
|
||||
**Goal**: Evaluators and new administrators understand readiness, licensed capabilities, first tasks,
|
||||
local help, and support evidence within ten minutes.
|
||||
|
||||
**Independent Test**: A representative evaluator completes the agreed discovery script without a live
|
||||
Cezen walkthrough or public internet.
|
||||
|
||||
- [ ] T062 [P] [US5] Define evaluator and new-administrator discovery scripts in `tests/browser/handover-journey.md`
|
||||
- [ ] T063 [US5] Add role-aware first-use orientation and persistent local help entry points in `cezen-portal/index.html` and `cezen-portal/quickstart.html`
|
||||
- [ ] T064 [US5] Align local FAQ and glossary with current product, entitlement, readiness, and recovery terms in `cezen-portal/faq.html` and `cezen-portal/glossary.html`
|
||||
- [ ] T065 [US5] Add packaged product/build identity and authoritative support references in `cezen-portal/about.html`
|
||||
- [ ] T066 [US5] Validate the ten-minute restricted-network handover journey and record results in `specs/001-enterprise-experience/evidence/phase4-handover.md`
|
||||
|
||||
**Checkpoint**: User Story 5 passes independent evaluation and handover acceptance.
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Pilot, Release, and Cross-Cutting Quality
|
||||
|
||||
**Purpose**: Prove the integrated appliance experience before general release.
|
||||
|
||||
- [ ] T067 Run full static, backend, authorization, timing, browser, accessibility, shell, and Ansible validation and record results in `specs/001-enterprise-experience/evidence/release-candidate.md`
|
||||
- [ ] T068 Verify upgrade, rollback, backup/restore, and interruption from the supported prior appliance baseline in `specs/001-enterprise-experience/evidence/release-candidate.md`
|
||||
- [ ] T069 Verify final source revision, packaged copies, ISO identity, build time, size, and SHA-256 checksums in `specs/001-enterprise-experience/evidence/release-candidate.md`
|
||||
- [ ] T070 Conduct the approved controlled customer pilot and record non-sensitive findings in `specs/001-enterprise-experience/evidence/pilot.md`
|
||||
- [ ] T071 Resolve and revalidate all critical customer-safety, task-completion, entitlement, recovery, and WCAG findings in `specs/001-enterprise-experience/evidence/pilot.md`
|
||||
- [ ] T072 Obtain product-owner and delivery/support approval in `specs/001-enterprise-experience/evidence/release-approval.md`
|
||||
- [ ] T073 Review the complete Git diff and explicitly authorize or defer commit, push, deployment, ISO rebuild, and general release in `specs/001-enterprise-experience/evidence/release-approval.md`
|
||||
|
||||
---
|
||||
|
||||
## Dependencies and Execution Order
|
||||
|
||||
### Phase Dependencies
|
||||
|
||||
- Setup (T001–T007) has no product-code dependency.
|
||||
- Foundational contracts (T008–T020) depend on Setup and block every user story.
|
||||
- User Story 1 (T021–T038) depends on Foundational and is the Phase 1 MVP.
|
||||
- User Story 2 (T039–T047) depends on Foundational; its operation-history work depends on User Story 1.
|
||||
- User Story 3 (T048–T055) depends on Foundational and durable Operation support from User Story 1.
|
||||
- User Story 4 (T056–T061) depends on Foundational and can proceed after Phase 1 entitlement contracts stabilize.
|
||||
- User Story 5 (T062–T066) depends on accepted terminology and readiness behaviour from Stories 1 and 4.
|
||||
- User Story 4 is cross-cutting across Delivery Phases 1–3; User Story 5 is accepted within Delivery
|
||||
Phase 2. Neither creates an additional delivery phase.
|
||||
- Pilot/release (T067–T073) depends on the stories included in that release candidate.
|
||||
|
||||
### User Story Dependency Graph
|
||||
|
||||
```text
|
||||
Setup -> Foundation -> US1 Setup/Readiness (Phase 1 MVP)
|
||||
|-> US2 Daily Administration
|
||||
|-> US3 Recovery/Support
|
||||
|-> US4 Entitlement Matrix -> US5 Handover
|
||||
Selected accepted stories -> Pilot -> Joint Approval -> General Release Eligibility
|
||||
```
|
||||
|
||||
### Parallel Opportunities
|
||||
|
||||
- T002–T004 can run in parallel after T001.
|
||||
- T016–T019 can run in parallel after backend contract shapes stabilize.
|
||||
- T021–T025 can be authored in parallel before US1 implementation.
|
||||
- T036 and T037 can run in parallel on separate representative appliances after T026–T035.
|
||||
- Story-specific test authoring for US2, US3, and US4 can proceed in parallel after Foundation.
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Phase 1 MVP First
|
||||
|
||||
1. Complete T001–T020.
|
||||
2. Complete T021–T035 test-first for User Story 1.
|
||||
3. Validate Workstation and Server independently with T036–T038.
|
||||
4. Stop for internal evidence review and controlled-pilot authorization.
|
||||
5. Do not begin general release or later product phases automatically.
|
||||
|
||||
### Incremental Delivery
|
||||
|
||||
Each user story retains its own independent test and evidence checkpoint. Later story phases reuse the
|
||||
same state, operation, entitlement, accessibility, audit, and release contracts without changing
|
||||
their meaning.
|
||||
|
||||
## Notes
|
||||
|
||||
- Every task that changes behaviour is preceded by an applicable test or evidence definition.
|
||||
- Application files remain unchanged until `$speckit-implement` is explicitly authorized.
|
||||
- Existing untracked `how-it-flows.gif` is unrelated and MUST remain untouched.
|
||||
- Commit, push, deployment, ISO rebuild, pilot, and general release require explicit authorization at
|
||||
their respective gates.
|
||||
Reference in new issue
Block a user