250 lines
18 KiB
Markdown
250 lines
18 KiB
Markdown
# 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.
|