# 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. ## Installer Architecture Planning Tasks (Docs Only) - [x] T074 Extend this feature with the four-artifact release matrix and Workstation-first sequence. - [x] T075 Define zero-network, payload, signing, update, rollback, interruption, sizing, and evidence contracts in `contracts/installer-artifact-contract.md`. - [x] T076 Run and record fresh consistency analysis in `analysis/installer-release-consistency.md`. - [ ] T077 Approve signing ownership, custody, rotation, revocation, and expiry policy (B1). - [x] T078 Define canonical manifest/signature/compatibility schemas and test vectors (B2); named approval remains under T086. - [ ] T079 Approve representative Workstation hardware and immutable starter-model inventory (B3). - [x] T080 Define Online Universal Server acquisition endpoint classes, trust, resume, and failure contract (B4); production values and owner approval remain under T100. - [ ] T081 Resolve update rollback, offline license, payload inventory, lab, and evidence ownership decisions (B5-B8). - [x] T082 Re-run consistency analysis and pass Architecture-ready Gate 1; record explicitly that this does not authorize installer implementation or media building. - [ ] T083 After Offline Workstation passes Gates 1-5, amend the shared contract from evidence and authorize or defer Offline Server S/M planning. - [x] T084 Draft canonical artifact-manifest and detached-signature JSON Schemas. - [x] T085 Record repository-derived Workstation baseline and recommended signing/update/license decisions in `contracts/architecture-decisions.md`. - [ ] T086 Obtain named owner approval of the schemas, compatibility evaluation and completed immutable manifest/signature positive and negative test vectors. - [x] T087 Remove circular manifest self-digest and define deterministic compatibility evaluation and reason codes. - [x] T088 Add conspicuously non-production structural and compatibility test vectors. - [x] T089 Add dedicated Ed25519 test-key signature vectors, validator evidence, and examples for model, update, and trust artifacts. - [x] T090 Add a real Workstation Ed25519 positive vector, tamper/unknown-key negatives, and structural examples for model, update, and trust artifacts without retaining the private test key. - [x] T091 Add an automated Draft 2020-12 schema, Ed25519, and compatibility fixture validator. - [x] T092 Run the automated suite and record passing schema (Draft 2020-12), signature (4/4), and compatibility (12/12) evidence. - [x] T093 Sign all four artifact examples with one transient test key, verify each signature and tamper case, then delete the private key. - [x] T094 Verify official Workstation hardware architecture/specifications and immutable starter-model candidate revisions, digests, and licenses. - [x] T095 Confirm universal hardware-adaptive Workstation media per CPU architecture; GPU model/class does not create separate media or commercial tiers. - [ ] T096 Approve representative machines, firmware/Secure Boot, driver/CUDA/runtime pins, model redistribution/attribution, and measured file inventory. - [ ] T097 Decide later ARM64 DGX Spark media, prove a multi-architecture image, or remove DGX Spark support; validate AMD64 CPU-only, 8 GB, 24 GB, and 48 GB-or-higher profiles. - [x] T098 Exclude AMD GPU/ROCm/Strix Halo acceleration from the first Workstation release while retaining truthful CPU-only fallback on AMD64 hosts. - [x] T099 Draft the Online Universal Server endpoint, trust, acquisition, resume/cache, failure, rollback, and evidence contract. - [ ] T100 Obtain platform/security decisions for production endpoints, credential issuer, mirrors, proxy/customer CA, release channels, and retry/cache/SLA values. - [x] T101 Draft shared offline update ownership, update classes, checkpoints, activation, retention, health, interruption, and rollback policy grounded in current backup/migration behavior. - [ ] T102 Approve atomic switch/snapshot mechanisms, full backup inventory/SLA, prior-version window, disk quota, driver/kernel recovery, health window, and break-glass authority. - [x] T103 Draft zero-network license import, activation, staging, clock, expiry, binding/rehost, revocation, interruption and evidence policy. - [ ] T104 Approve staging/expiry matrices, clock tolerance, device identity/rehost, revocation ages and license/artifact trust ownership; remove optional binding enforcement and authorization use of staging tier defaults during implementation. - [x] T105 Produce repository-derived four-artifact payload boundaries, role matrix, exact-digest deduplication rules, sizing worksheet and media-capacity evidence policy. - [ ] T106 Resolve every payload object/version/digest/license, build and measure each artifact, reconcile extracted media, and approve the Server L/Max split justification. - [x] T107 Define offline lab isolation, attempted-network capture, physical hardware, interruption/security matrix, evidence package, independent review and stop/retry rules. - [ ] T108 Assign named lab/reviewer owners, exact hardware/topology/tools/schedule/evidence storage, then execute and independently review the required clean and failure runs. - [x] T109 Draft artifact naming/version/channel, SPDX 3.0.1 SBOM, in-toto v1.2/SLSA v1.2 provenance, reproducibility, retention, support cadence and withdrawal policy. - [ ] T110 Approve lifecycle formats/toolchain, publication/archive locations, retention/privacy periods, supported-version/backport window, cadence/EOL and named owners. - [x] T111 Define model-pack quarantine, content-addressed sharing, dependency, activation, uninstall, garbage-collection, entitlement-change and redistribution-license behavior (B10). - [ ] T112 Approve model-store mechanisms, quotas/retention, customer-data handling, license continuity/rehost rules, withdrawal authority, GC policy and named owners; execute Gate 5 lifecycle vectors. - [x] T113 Define release trust domains, key roles, dual-control custody, signing handoff/receipts, rotation, offline trust distribution, revocation and emergency recovery contract (B1). - [ ] T114 Name signing/trust owners and alternates; approve hardware/custody/backup, key and overlap lifetimes, revocation age, offline time, compromised-root recovery, emergency authority and ceremony evidence; execute signing acceptance vectors. - [x] T115 Define installer release assets, adversaries, trust boundaries, threat/control register, security invariants, abuse/interruption tests and residual risks for Gate 1. - [ ] T116 Obtain Security/Platform/Release/Product/Support approval of the threat model, assign every residual risk and execute/link the minimum control evidence. - [x] T117 Consolidate all Gate 1 decisions, accountable roles, acceptable outcomes, dependencies and evidence requirements into an approval dossier. - [x] T118 Obtain Cezen Technologies approval-record IDs for G1-01 through G1-30, retain authorized human attribution in restricted evidence, allocate open evidence to its proper downstream gate, and record Gate 1 pass without authorizing implementation implicitly. - [x] T120 Adopt Cezen Technologies as the visible accountable organization while preserving authorized-person attribution and separation-of-duties proof in restricted approval evidence. - [x] T121 Record Cezen Technologies approval `CT-G1-2026-001` for G1-12 AMD64/NVIDIA/CPU-fallback scope and G1-17 later separate ARM64/DGX Spark identity; retain G1-13–G1-16 as evidence-open. - [x] T122 Record Cezen Technologies approval `CT-G1-2026-002` for G1-08–G1-11 artifact schemas, compatibility, identity/provenance and immutable publication/withdrawal direction; retain production tooling, archive and retention evidence gaps. - [x] T123 Record Cezen Technologies approval `CT-G1-2026-003` for G1-01–G1-07 trust domains, custody/rotation/revocation/recovery direction, threat controls and required platform-security baseline; retain operational values, assignments and executed evidence gaps. - [x] T124 Record Cezen Technologies approval `CT-G1-2026-004` for G1-18–G1-24 online acquisition, update/checkpoint/rollback and offline license/binding/rehost direction; retain production values, mechanisms and executed evidence gaps. - [x] T125 Record Cezen Technologies approval `CT-G1-2026-005` for G1-25–G1-30 model lifecycle, customer-data preservation, lab/evidence methods, acceptance inventory and Server L/Max deferral; retain operational values, assignments and executed evidence gaps. - [x] T126 Record Cezen Technologies approval `CT-G1-2026-006` for the G1-13 CPU-only/sub-threshold, NVIDIA 8 GB, 24 GB and 48 GB-or-higher profile matrix without claiming unavailable physical-machine evidence. - [x] T127 Derive a coherent G1-14 runtime candidate from repository and official evidence; identify the driver 550/CUDA 12.4, declared CUDA 12.6 and vLLM CUDA 12.8.1 contradiction; propose R570/CUDA 12.8.1-compatible branch baseline with immutable-lock and physical-test gates. - [x] T128 Record Cezen Technologies approval `CT-G1-2026-007` for the G1-14 Ubuntu 22.04.5/R570/CUDA 12.8.1/vLLM 0.10.2 runtime direction and CPU independence; retain exact locks and physical/rollback evidence gaps. - [x] T129 Record Cezen Technologies approval `CT-G1-2026-008` for the G1-15 pinned Phi-3 Mini, Nomic Embed Text v1.5 and Microsoft Phi-3 Mini starter set and license/hardware boundaries; retain packaged file/digest/notice and redistribution evidence gaps. - [x] T130 Record Cezen Technologies approval `CT-G1-2026-009` for the G1-16 Offline Workstation payload inclusion/exclusion boundary; retain resolved signed inventory, exact size/digest/license, reconciliation and measurement evidence gaps. - [x] T131 Audit Gate 1 closure against the normative gate definition and allocate every open item and C1-C7 contradiction to Gates 2-6 or deferred Server planning. - [ ] T132 Under separately authorized scope, complete the Gate 2 immutable inventory, concrete mechanisms/policy values, restricted operator/lab assignments and implementation plan for Offline Workstation. - [x] T133 Inspect build host 172.16.10.144, confirm no active legacy build, quarantine the 30 GB legacy workspace, create a clean workspace, synchronize the current source/spec snapshot and record deterministic source/host evidence without starting a build. - [x] T134 Add an immutable Offline Workstation payload-lock contract and fail-closed preflight, block the legacy mutable acquisition path, add dependency-free tests, and prove on the build host that unresolved input creates no staging/artifact output. - [x] T135 Add and run connected resolver increment 001 for a deterministic source archive and six Linux/AMD64 OCI manifests, prove source reproducibility, record registry drift/unresolved licenses and keep artifacts empty. - [x] T136 Add and run an isolated empty-status APT resolver, expand 26 requested packages to 487 exact measured `.deb` objects, retain repository-snapshot/license/NVIDIA closure gaps, and prove no package installation or artifact creation occurred. - [x] T137 Add and run a Python 3.11 wheel-only resolver against combined inputs; record its fail-closed bcrypt/Chroma result and prove the failed run produced no candidate lock, wheel payload or artifact. - [x] T138 Reconcile the apparent dependency conflict against the real Ansible/runtime boundaries, preserve separate backend/Chroma/platform environments, resolve 363 exact wheel objects without changing either constraint, and retain the candidate lock and zero-artifact evidence. - [x] T139 Derive the CUDA 12.8 Python ML pins from authoritative vLLM 0.10.2 wheel metadata, resolve Torch 2.8.0/Torchaudio 2.8.0/Torchvision 0.23.0 into a fresh 361-object candidate, prove zero CUDA 13 objects and retain zero-artifact evidence. - [ ] T140 Validate the pinned stack on approved R570/CUDA 12.8.1 GPU profiles and an NVIDIA-independent CPU-only profile; complete index-origin/resolver-report approval, license/notices, profile-aware installation and clean disconnected Python 3.11 install/import evidence. - [x] T141 Prove network-disabled Python 3.11 installation/import for the backend, ChromaDB and platform wheelhouses; prove CPU tensor execution with CUDA hidden and supplemental CUDA 12.8 execution on the build host RTX 3050/Open Driver 595.58.03, retaining hashed logs and zero-artifact evidence. - [x] T142 Define exactly-one CPU/NVIDIA Python runtime profile selection, add exact CPU/cu128 wheel identities and a fail-closed validator, assemble a 196-wheel CPU-only selection with zero GPU objects, and prove disconnected CPU-only installation/import/tensor execution. - [ ] T143 Integrate signed profile membership with the future installer hardware detector, pre-mutation journal, resume and rollback path; test unsupported/failed detection, interrupted selection, attempted profile change and tampered/ambiguous membership. - [x] T144 Add a non-mutating fail-closed profile-selection planner and test hardware fallback, NVIDIA readiness, structural membership, start/resume, active-operation exclusion, rollback-before-change and new-operation-after-rollback semantics; retain build-host vectors and zero-artifact evidence. - [x] T145 Define a closed profile-membership verification-receipt schema, replace the planner's bare verification boolean with manifest/envelope/key/trust/policy/namespace/profile/verifier binding, and prove production rejection plus explicit structural-test acceptance. - [ ] T146 Implement the production Ed25519/trust-policy verifier and atomic fsync/rename profile journal/checkpoint writer; prove stale-generation, torn-write, power-loss, tamper and recovery behavior before installer integration. - [x] T147 Implement and test the isolated atomic profile journal writer with locking, generation CAS, digest chaining, immutable identity, checkpoint-before-install transition, mode 0600, file/directory fsync and atomic rename; retain stale-writer/tamper/transition evidence without claiming checkpoint creation or power-loss proof. - [x] T148 Implement the production-shaped Ed25519 profile-membership verifier with canonical manifest digest, namespace, key purpose/environment/status, fingerprint and policy enforcement; prove positive/tamper/wrong-environment behavior with ephemeral test keys without claiming production signing evidence. - [x] T149 Implement and test an isolated hashed Python-environment checkpoint with original-absence handling, file/directory/symlink inventory, same-filesystem fsync/atomic replacement, pre-restore verification and failed-tree quarantine; retain exact restore evidence without claiming crash or live-path coverage. - [x] T150 Add gated test-only crash injection and deterministic restore recovery; prove pre/post checkpoint publication and post-quarantine/post-activation forced-process termination outcomes on disposable build-host trees without claiming physical power-loss durability. - [x] T151 Compose receipt, planner, exact profile validation, atomic journal and checkpoint into a non-mutating preparation flow; prove invalid payload leaves no state and valid strict-CPU preparation reaches idempotent `checkpoint_ready` without package mutation. - [x] T152 Implement the isolated offline Python profile executor with checkpoint-ready enforcement, no-index install, profile health checks, fsynced atomic activation and rollback transitions; prove strict-CPU install to `installed` plus dependency-failure rollback on disposable targets. - [x] T153 Add gated post-activation executor termination and recovery-only handling; prove a full disconnected CPU environment crash restores the exact checkpoint, quarantines the activated environment and records generation-5 `rolled_back`. - [x] T154 Strengthen NVIDIA health to require CUDA availability plus synchronized device execution, then prove full disconnected `nvidia-cu128` install/health/atomic activation to `installed` on the build-host RTX 3050 without claiming the R570 or 24/48 GB matrix. - [x] T155 Run fresh consistency audit Pass 4, reconcile C1-C7 against executed Gate 2 evidence, correct stale authority/TBD statements, and publish exact remaining readiness blockers without claiming an artifact or Gate 2 pass. - [x] T156 Replace the stale offline README build sequence with one authoritative operator flow that classifies resolver/profile/checkpoint/install stages, marks bundle/ISO assembly blocked, defines mandatory stop conditions and forbids release claims from disposable evidence. - [x] T157 After external-action quota reset, synchronize the complete current source/spec snapshot to the clean build host, run all 27 remote deployment tests including Ed25519, hash the suite log and reconfirm zero artifact entries. - [x] T158 Prove full disconnected `nvidia-cu128` post-activation process-crash rollback on the RTX 3050: restore the exact checkpoint, preserve the executable CUDA environment in quarantine, record generation-5 `rolled_back`, and retain zero-artifact evidence. - [x] T159 Add the boot-safe profile recovery dispatcher and prove a strict-CPU post-activation crash is recovered by a separate fresh network-disabled container invocation; verify terminal idempotence, exact checkpoint restore, quarantine retention and zero artifacts without claiming an actual reboot or power-loss test. - [x] T160 Convert the build host from DHCP to the same observed persistent static address, then prove a fresh strict-CPU interrupted operation recovers during a controlled OS reboot; retain the exact-path mismatch negative vector, remove the temporary boot unit, and keep physical power-loss and production integration claims open. - [x] T161 Prove bounded strict-CPU target byte and inode exhaustion in separate executable network-disabled tmpfs vectors with independent reserved journal/checkpoint capacity; require real `ENOSPC`, unchanged original target, generation-5 terminal rollback, read-only re-verification and zero artifacts. - [x] T162 Add a direct bounded post-activation service-health probe boundary and prove a full disconnected strict-CPU activation whose probe observes the new environment then exits non-zero restores the checkpoint, quarantines the activated environment and records generation-5 rollback with zero artifacts. - [x] T163 Model the intended model/vector/API/proxy dependency graph with uniquely named disposable systemd units; prove explicit ordering/requirements, a 3-sample 12-check semantic health window and vector-failure `OnFailure` rollback, then remove every temporary unit and record the non-compliant real-unit wiring as an open blocker. - [x] T164 Design candidate production API/Chroma/activation-health/rollback units plus nginx ordering drop-in and active-operation environment contract under the spec; validate syntax and dependency cycles on systemd 249 using `/tmp`-only executable stubs without installing/reloading units, and retain missing real executables/nginx/security scoring as blockers. - [x] T165 Implement the isolated deterministic loopback-only activation health-window tool with canonical atomic evidence and stable exits; prove consecutive ready, explicitly allowed optional degradation, timeout, malformed response, non-loopback rejection and HTTP-503 rollback-trigger behavior in unit tests and a network-disabled integration container. - [x] T166 Add a monotonic total-window deadline and signed per-component systemd restart ceilings; prove deterministic deadline/storm tests plus real isolated systemd vectors that reject an impossible next sample and eight-restart storm with exit 23 before HTTP, then remove all temporary units. - [x] T119 Run fresh consistency audit pass 2, reconcile task/decision counts, verify JSON parsing and document that remaining payload-size TBDs require build evidence outside docs-only scope. T077-T083 are planning/evidence gates, not authorization to change installer code or build media. ## 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.