aipackage/specs/001-enterprise-experience/tasks.md

# 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` (software-package clean install and reboot evidence recorded; interruption, restricted-network, ISO boot, and manual WCAG evidence remain)
- [x] 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.