Jino Jose a2ee7247d5 Fix Phase 1 server validation defects

2026-07-13 05:30:39 +05:30

18 KiB

Raw Permalink Blame History

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.

T001 Create the Phase 1 evidence manifest template in specs/001-enterprise-experience/evidence/phase1-manifest.md
T002 [P] Add Python test configuration and fixtures for isolated appliance data in tests/conftest.py
T003 [P] Add browser journey and accessibility test configuration in tests/browser/README.md
T004 [P] Add shell and Ansible validation commands to tests/deployment/README.md
T005 Document the SQLite schema-version and rollback procedure in specs/001-enterprise-experience/migrations.md
T006 Record the supported pre-feature appliance baseline and restore fixture requirements in tests/fixtures/README.md
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.

T008 Add idempotent schema-version and migration runner tests in tests/backend/test_migrations.py
T009 Implement additive SQLite schema-version and migration support in ansible/roles/cezen-backend/files/main.py
T010 Add customer-state, error-envelope, entitlement-reason, redaction, and allowed/denied-role contract tests in tests/backend/test_experience_contracts.py
T011 Implement versioned customer-state and error-envelope helpers in ansible/roles/cezen-backend/files/main.py
T012 Add durable Operation lifecycle, transition, conflict, idempotency, and server-side authorization tests in tests/backend/test_operations.py
T013 Implement the Operation store and lifecycle rules in ansible/roles/cezen-backend/files/main.py
T014 Add audit correlation and secret-redaction tests in tests/backend/test_audit_redaction.py
T015 Extend audit helpers with allowlisted detail and correlation IDs in ansible/roles/cezen-backend/files/main.py
T016 [P] Create shared accessible state, alert, operation, and confirmation styles in cezen-portal/style.css
T017 [P] Create shared browser helpers for state rendering, freshness, errors, focus, and announcements in cezen-portal/experience.js
T018 [P] Add canonical customer-facing product and entitlement vocabulary in cezen-portal/branding.js
T019 Synchronize canonical license logic into the deployed backend copy and add parity verification in tests/backend/test_license_parity.py
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

T021 [P] [US1] Add browser setup validation, duplicate-submit, refresh, interruption, and 2-second acknowledgement timing tests in tests/browser/test_setup_journey.py
T022 [P] [US1] Add console setup valid, invalid-license, and resume scenario tests in tests/deployment/test_firstboot_setup.py
T023 [P] [US1] Add readiness state, freshness, entitlement-reason, remediation, and 10-second display timing tests in tests/backend/test_readiness.py
T024 [P] [US1] Add WCAG 2.2 AA automated and manual-check definitions for setup/readiness in tests/accessibility/phase1-checklist.md
T025 [P] [US1] Add Workstation-versus-Server setup matrix fixtures in tests/fixtures/setup-matrix.json

Implementation for User Story 1

T026 [US1] Persist non-secret browser setup progress and durable installation operation state in autoinstall/websetup/server.py
T027 [US1] Replace process-local-only progress rendering with resumable operation polling and accessible announcements in autoinstall/websetup/server.py
T028 [US1] Preserve safe completed steps and expose retry, resume, reboot, recovery, and escalation outcomes in autoinstall/firstboot-setup.sh
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
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
T031 [US1] Update the appliance readiness UI to consume the versioned contract and shared experience helpers in cezen-portal/appliance.html
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
T033 [US1] Update health rendering to distinguish unreachable, degraded dependency, unavailable capability, and stale observation in cezen-portal/health.html
T034 [US1] Add local setup, interruption, readiness, and escalation guidance in cezen-portal/quickstart.html and cezen-portal/troubleshooting.html
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)
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

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

Complete T001–T020.
Complete T021–T035 test-first for User Story 1.
Validate Workstation and Server independently with T036–T038.
Stop for internal evidence review and controlled-pilot authorization.
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.

18 KiB Raw Permalink Blame History Unescape Escape