INTAKE-DESIGN-T2-6-SUCCESS-AND-UAT-MODULE.md

# Pilot Readiness, Role Walkthroughs & UAT Success Module (`T2-6 · UAT-PACK`)
> **Harley's Executive 2-Page Readout (0.5p Summary + 1.5p Full Design + Collapsible Glossary)** · **✅ Peer-Reviewed by Astra Extra High (`gpt-6-astra xhigh`) + Claude Opus 4.7 Extra High** · 16 Readiness Gates (R0..R13) · 6 Interactive Role Walkthroughs (C1..C6) · Reporter-Retest Issue Tracker
> **🔒 100% INTAKE & DESIGN GATES LOCKED BY OWNER (`App 0 -> App 6` · `2026-10-22 22:57 IST` — Ratified by `cfo@harleys.com`) · `G1 DESIGN GATE LOCKED & SIGNED OFF BY OWNER (2026-10-22 22:39 IST)` · STEP 2 & 3 BUILD EXECUTION ACTIVE (`App 0 ∥ App 1a -> App 1b -> App 2 -> Apps 3..6`)**
> - **`A1` (`R1` · `App 0 -> App 8` Finalization Sequence — LOCKED):** `App 0 (Shell, Sticky Filters FV-1..12, Bot O-048, CI/CD TC-1..14, Enablement EN-01..19) ∥ App 1a (Identity Spine SP0+SP1: hop.people, user_assignments, master_data_holders, 10 departments)` → `App 1b (People & HR Importer)` → `App 2 (Daily Store Ops, Kiosk & Outlet Summary OS-1..7)` → `App 3 (Legal & Compliance)` → `App 4 (Fixed Assets & Maint)` → `App 5 (Café Projects)` → `App 6 (7-Stage NPL)` → `App 7 (Cross-App UAT Gate)` → `App 8 (Post-Pilot Wave)`.
> - **`A2` (`BS-04 & BS-07` · Shift Swaps, Inter-Outlet Loans & Outlet Master Fields — LOCKED WITH OWNER REFINEMENT):** **"Outlet Manager / Cluster Manager should approve with visibility to City Head"** — Both intra-outlet shift swaps (`staff_shift_rosters`) and inter-outlet crew loans (`staff_inter_outlet_loans`) are approved by **Outlet Manager OR Cluster Manager (`approved_by_role IN ('outlet_manager', 'cluster_manager')`)**, and every approval automatically grants visibility and emits an audit-trail feed notification (`city_head_notified_at TIMESTAMPTZ`) to the **City Head (`city_head`)**. Locks all 12 core `outlets` master fields (`BS-07`).
> - **`A3` (`OV-6 & AD-1..4` · Multi-Outlet Team Rollup Scope — LOCKED):** Aggregate team follow-through counts and outlet rollups (`My Team AD-1..4`) are visible above Outlet Manager (`Cluster Manager`, `City Head`, `HOD`), with **zero individual employee stack-ranking leaderboards** (`Principle #3: Accountability without blame`).
> - **`A4` (`SK-14 / N-11 / OA-06 / OA-07` · Named Reviewers & Template Owners — LOCKED):** Seeds `hindi_reviewer`, `quality_reviewer`, `restricted_item_owner` (`OA-06`), and `fitout_template_owner` (`OA-07`) as configurable role slots inside `master_data_holders` so named individuals can be assigned/updated in the UI without blocking build.
> - **All Remaining App Pillars Combined Intake + Design Gates Locked (`22:57 IST`):** **(1) `App 0` Locked** (`FV-1..12` Sticky 5-Filter Set `Period, Cities, Type, Outlet, Brand`, Left-Rail Foot `Filters` + `280px` Docked Pane, Role-Published Views `R15`, `O-048` 7-Context Sticky Bot Chips); **(2) `App 3` (`Stop 1` Compliance) Locked** (Standalone 4-Pillar Legal App + Embedded `60s` Outlet-Only Inspector Mode hiding leases/litigation, `60/30/14/7d` Expiry Alerts `DF-4`, Masked Licence Numbers `CM-1`, ClamAV `'PENDING'`-default S3 Vault `CM-2`); **(3) `App 4 & App 5` (`Stop 2` Assets, Maintenance & Café Projects) Locked** (`1,982` QR Fixed Assets, `>40% WDV` Repair-vs-Replace CFO Gate, 6-State Maintenance with 2nd-Person Store Operator Verify, 9-Gate Café Projects NSO with `Water TDS <= 80ppm` Boiler Gate, 4-Photo Site GRN & Gate 6 Auto-Asset Minting); **(4) `App 6` (`Stop 3` 7-Stage NPL) Locked** (`L1..L7` single named owner per gate, CK `<=90m` Blast Chill & Probe `<=+5°C` Cold-Chain Gate, First-10-Orders Open-Box Rider Gate, 5-Axis Rollout Adoption Roll-Up, Stage 7 `30/60/90d` Margin Kill/Keep Gate).

---

## PART 1 · EXECUTIVE SUMMARY (0.5 PAGE)

### 1A. What We Are Building & Why
- Embeds the **Nanakramguda Accountability Pilot UAT & Customer Success Pack** (`/admin/success` + `/static/uat/index.html`) directly into OneOps & HOP.
- Governs **16 Pilot Readiness Gates (`R0`, `R0b`, `R0c`, `R1`..`R13`)** from Business Head decisions (`D1`–`D7`) and Admin Pre-Setup (`B1`) to ordered Super-Admin switch activation (`R12`) and 3 shadow days (`R13`).
- Provides **6 Interactive Phone/Kiosk Role Walkthroughs** (`own-phone.html`, `kiosk.html`, `kitchen.html`, `shift-manager.html`, `outlet-manager.html`, `cluster.html`) paired with step-by-step PASS/FAIL scripts **`C1`–`C6`** and 17 test personas (`UAT-01`..`UAT-17`, including `UAT-17` zero-access canary).
- Enforces a **Closed-Loop UAT Issue & Retest Lifecycle** (`New -> Triaged -> Fixed -> Retest -> Closed`) with 3 severity SLAs (`Stops work [1h]`, `Annoying [Next day]`, `Cosmetic [This week]`), **Reporter-Must-Retest** rule, Daily 10-Min Standing Check-In, and 10 Troubleshooting Runbooks (`E1`–`E10`).

### 1B. Personas & Access Scope
- **Ground Testers (`UAT-01` FOH, `UAT-02` Shift Lead, `UAT-07` BOH)**: Walk through role screens (`C1`–`C3`), tick PASS/FAIL, and report bugs via `More > Feedback`.
- **Managers & City Head (`UAT-03` Outlet Mgr, `UAT-05` Backup, `UAT-12` City Head)**: Execute Approvals, Needs-You queue, Day Summary, and Cluster Roll-Up (`C4`–`C6`).
- **Admin / Config Lead / Super Admin (`UAT-14`..`UAT-16`)**: Run `B1`/`B2` setup, chair the Daily 10-Min Standing Check-In, and flip switches in strict order (`engine -> tile -> verify -> own_phone -> kiosk -> nudges`).

### 1C. Owner Sign-Off Decisions Required
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:57 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** Approve **16-Step Readiness Gate (`R0`..`R13`)** and ordered Super-Admin switch sequence (`R12`) before 3-day café shadow run.
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:57 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** Approve **Reporter-Must-Retest Closure Rule** (an issue in `Retest` only moves to `Closed` when the original reporter confirms the fix).
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:57 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** Approve **UAT-17 Zero-Scope Canary Check** (`UAT-17` has no outlet assigned and must see zero data; any visible data is a P0 blocker).

### 1D. Direct Navigation & Live Pre-Signed-In Routes
- [📋 Jump to Part 2: Full Intake, Domain Design & Industry Benchmarks](#part-2--full-intake--domain-object-design-15-pages) | [📖 Jump to Part 3: Glossary, DDL & Corpus Appendix](#part-3--glossary-schema-ddl--corpus-appendix)
- 🟢 **Local :8000 Success & UAT Hub**: `http://localhost:8000/admin/success`
- 🟢 **Interactive UAT Pack (index.html)**: `http://localhost:8000/static/uat/index.html`
- 🟢 **6 Role Walkthroughs**: `http://localhost:8000/static/uat/walkthrough/index.html`
- 🟢 **Staging HOP Success**: `https://test.hop.harleys.com/admin/success`

---

## PART 2 · FULL INTAKE & DOMAIN OBJECT DESIGN (1.5 PAGES)

### 2A. Core User Journeys & Functional Intake Rules

| Journey / Flow | Actor & Trigger | System Action & Hard Gate Rule |
| :--- | :--- | :--- |
| **1. Pre-Pilot Readiness & Setup (`R0`–`R8`, `B1`/`B2`)** | Business Head / Admin / Config Lead | Completes `R1`–`R4` (`READY` now: phone sign-in, kiosk check-in basics, people/roles/help-line, paper checklist photos) and `R5`–`R8` (`B2`: Outlet journeys, Pilot roles, Kiosk approve-on-phone, Lead check-in confirmation). |
| **2. Interactive Role Walkthrough & Script Execution (`C1`–`C6`)** | Testers (`UAT-01`..`UAT-17`) | Testers preview their role in `/static/uat/walkthrough/index.html` (10 min), then execute `C1` (FOH Own Phone), `C2` (Shared Kiosk + Peer Check), `C3` (BOH Fridge Reading + Flag + All-or-Nothing Handover), `C4` (Shift Mgr Approvals + Needs-You + Day Summary), `C5` (Outlet Mgr Late/Reopen/Scope), `C6` (City Head Roll-Up & Escalation). |
| **3. In-App Bug Capture & Severity Triage (`Section D`)** | Any Tester -> Admin | Submitted via `More > Feedback > Bug` (or WhatsApp backup on Kiosk/offline); triaged daily into `Stops work` (1h SLA), `Annoying` (Next day), or `Cosmetic` (This week). |
| **4. Daily 10-Min Standing Check-In & Reporter Retest** | Admin (Chair) + Outlet Mgr + Testers | Standing 10-min café huddle reviews `Stops work` & `Retest` queue; fixed items return to the original reporter (`Retest -> Closed` or back to `New`). |

### 2B. Underlying Domain Objects & How They Work Together

```text
[Readiness Gate (R0..R13 + B1/B2 Setup)] ──► [6 Role Walkthroughs + Scripts C1..C6 (UAT-01..UAT-17)]
                                                            │
                                           (PASS/FAIL Tick or More > Feedback)
                                                            ▼
[Daily 10-Min Standing Check-In] ◄── [UAT Issue Tracker (New -> Triaged -> Fixed -> Retest -> Closed by Reporter)]
```

| Domain Object (`Table`) | Primary Key & Scope | Key Attributes & Constraints | Cross-Object Handshake |
| :--- | :--- | :--- | :--- |
| `uat.readiness_gates` | `gate_id (R0..R13)` | `what`, `who`, `where`, `how_long`, `status` (`READY` / `NOT YET`), `depends_on`, `setup_step` (`B1`/`B2`) | Tracks prerequisite chain from `R1`–`R4` (ready now) through `R12` (switches ON) to `R13` (3 shadow days) |
| `uat.test_personas` | `uat_code (UAT-01..UAT-17)` | `login_email`, `persona_role`, `in_pilot_scope`, `assigned_scripts` (`C1`..`C6`) | Maps 7 active pilot personas (`UAT-01/02/03/05/07/12/17`) + 10 non-pilot/setup accounts (`UAT-04..16`) |
| `uat.script_runs` | `run_id (script_code, step_no)` | `tester_id`, `device` (`own_phone`/`kiosk`), `verdict` (`PASS`/`FAIL`), `screenshot_s3_key` | Records step-level execution across `C1` (10 steps), `C2` (8), `C3` (8), `C4` (10), `C5` (8), `C6` (7) |
| `uat.issue_tracker` | `issue_id (UAT-001..)` | `reporter`, `role`, `device`, `script_step`, `severity`, `status`, `retested_by_reporter`, `closed_date` | Enforces `New -> Triaged -> Fixed -> Retest -> Closed` with mandatory reporter re-verification |
| `uat.troubleshooting_runbooks` | `runbook_id (E1..E10)` | `problem_title`, `ground_action`, `admin_resolution` | 10 instant café runbooks (Sign-in, Unapproved check-in, Locked PIN, Missing step, Draft Hindi, Offline paper fallback, Kiosk renewal, Self-check block, Lost phone) |

### 2C. State Machines & Operational Guardrails
- **UAT Issue Lifecycle & Severity SLAs (`Section D`)**: <code>New</code> &rarr; <code>Triaged</code> &rarr; <code>Fixed</code> &rarr; <code>Retest</code> (by original reporter) &rarr; <code>Closed</code>.<br><strong>SLAs:</strong> <code>Stops work</code> = Same hour &middot; <code>Annoying</code> = Next day &middot; <code>Cosmetic</code> = This week.
- **Super Admin Ordered Switch Activation (`R12` / `B2`)**: Only after Owner sign-off (`S5`), Super Admin switches ON in strict sequence:<br><code>1. engine</code> &rarr; <code>2. tile</code> &rarr; <code>3. verify screen</code> &rarr; <code>4. own phone</code> &rarr; <code>5. Kiosk</code> &rarr; <code>6. nudges</code>.

### 2D. Global F&B / Patisserie / Enterprise Industry Benchmarks & Hostile Peer Review Verdict (`Astra Extra High` + `Opus 4.7 Extra High`)

| Global Benchmark / Peer Reviewer | Standard / Gate Adopted | How Harley's OneOps / HOP Enforces It |
| :--- | :--- | :--- |
| **Enterprise Retail Pilot Readiness Gate (`R0..R13`)** | **16 Pre-Flight Readiness Checks Before Outlet Cutover** | Validates seed parity, RBAC matrix, WhatsApp webhook health, photo upload pipeline, and escalation cron before Nanakramguda / Jubilee Hills pilot sign-off. |
| **Role-Scoped Interactive UAT (`C1..C6` & `UAT-01..17`)** | **Reporter-Retest Lock & 10 Operational Runbooks** | Provides 1-click role walkthroughs (`Staff, Shift Manager, Outlet Manager, Area Manager, HQ Admin, Founder`) and enforces Reporter-Retest verification before closing any UAT defect. |
| **Hostile Peer Review Verdict (`Astra XHigh` + `Opus 4.7`)** | **✅ APPROVED — DETERMINISTIC PILOT GATE** | Verified live `/static/uat/index.html` and `/admin/success` parity. |

### 2F. Universal HOP Nudge & Accountability Framework Compliance Contract (`acct-*` / `O-022` / `O-045`)

| HOP Accountability Pillar | Constitutional Rule (`acct-*` / `O-022` / `O-045`) | How Every Checklist & Gate in This Module Enforces It |
| :--- | :--- | :--- |
| **1. Single Named Accountable Owner (`person_id`)** | Zero shared role/committee ownership (`NOT NULL REFERENCES hop.people`) | Every stage gate, checklist item, repair ticket, and store readiness step binds to exactly **1 named human (`person_id`)** who signs with their 4-digit User PIN (`O-022`). |
| **2. Deterministic Escalation Ladder & Timers** | `Named Owner (T-24h) -> HOP Nudge #1 + Shift/Store Mgr (T-6h / +15m) -> HOP Nudge #2 + Cluster Mgr (T-2h / +30m) -> City Head / COO / CFO Hard Gate Lock (T-0)` | Persists durable WhatsApp + in-app delivery receipts in `accountability_nudges`; automatically freezes the downstream gate (`LOCKED_NOT_ENABLED` / `GATE_BLOCKED`) at `T-0`. |
| **3. M3 Independent 2nd-Person Verification** | `✓ Confirm = I checked the work` (`verified_by_id != completed_by_id`) vs `↩ Return for correction` | Database `CHECK (m3_verified_by_id <> m3_completed_by_id)` prevents self-verification; selecting `↩ Return` requires a mandatory reason, increments `revision_count++`, and fires an instant re-nudge. |
| **4. Structured `✕ Cannot` 6-Reason Chips + Upstream Re-Routing** | `CK Crate Short` · `Cold-Chain Excursion` · `Packaging Missing` · `POS SKU Missing` · `Equipment Down` · `Staff Shortage` | Selecting a `✕ Cannot` chip + 1 evidence photo records an immutable `BLOCKED` receipt for the frontline operator and **automatically transfers accountability + HOP Nudge upstream** to the `L3 CK`, `L4 Logistics`, `L5 POS`, or `Procurement/MEP` Named Owner. |
| **5. Snooze Cap (`Max 2`) & `O-045` Evidence Proportionality** | `snooze_count <= 2` (`+15m` then `+30m`) + End-of-Sequence Checklist Proof (`SK-16`) | Hard-caps snoozes at 2 before escalating to Cluster Manager; routine checklists use 1-tap ticks + ONE end-of-sequence summary photo, restricting selfies + 4-digit PIN strictly to Critical/M3, Repair Closure, and Attendance/Spot Audits. |

---

## PART 3 · GLOSSARY, SCHEMA DDL & CORPUS APPENDIX

<details>
<summary><strong>📖 3A. Domain Glossary & Canonical Definitions (Click to Expand)</strong></summary>

| Term / Code | Canonical Definition in Harley's OneOps / HOP |
| :--- | :--- |
| **R1–R4 vs R5–R13 (`readiness.csv`)** | `R1`–`R4` are `READY` today (sign-in, existing Kiosk check-in, Admin pre-setup `B1`, paper checklist photos); `R5`–`R13` unlock after build & Owner sign-off (`B2`). |
| **Peer Check / Self-Check Guardrail (`C2 Step 7`, `E9`)** | Kiosk and shift steps requiring verification cannot be approved by the same person who performed them ('You cannot check your own work'). |
| **All-or-Nothing Handover (`C3 Step 6–7`)** | When BOH/FOH staff offer open steps at shift change, the incoming colleague accepts the entire open bundle atomically. |
| **UAT-17 Safety Canary** | Dedicated test login (`uat-17@example.invalid`) with zero outlet assignment; if it sees any outlet data, it is immediately flagged as a Critical security defect. |
| **Reporter-Must-Retest Rule** | No bug can be marked `Closed` by engineers or Admin alone; the ground tester who reported it must re-run the step and confirm. |

</details>

<details>
<summary><strong>🗄️ 3B. PostgreSQL Schema DDL & Constraints (Click to Expand)</strong></summary>

```sql
CREATE SCHEMA IF NOT EXISTS uat;
CREATE TABLE uat.readiness_gates (
    gate_id VARCHAR(16) PRIMARY KEY,
    what TEXT NOT NULL,
    who VARCHAR(120) NOT NULL,
    how_long VARCHAR(64) NOT NULL,
    status VARCHAR(24) NOT NULL DEFAULT 'NOT YET',
    test_script VARCHAR(16),
    depends_on VARCHAR(64),
    setup_step VARCHAR(64)
);
CREATE TABLE uat.issue_tracker (
    issue_id VARCHAR(24) PRIMARY KEY,
    reported_date DATE NOT NULL,
    reporter VARCHAR(80) NOT NULL,
    role VARCHAR(64) NOT NULL,
    device VARCHAR(32) NOT NULL,
    script_step VARCHAR(32) NOT NULL,
    what_happened TEXT NOT NULL,
    screenshot VARCHAR(128) NOT NULL,
    severity VARCHAR(24) NOT NULL CHECK (severity IN ('Stops work', 'Annoying', 'Cosmetic')),
    status VARCHAR(24) NOT NULL DEFAULT 'New' CHECK (status IN ('New', 'Triaged', 'Fixed', 'Retest', 'Closed')),
    owner VARCHAR(80),
    retested_by_reporter DATE,
    closed_date DATE
);
```

</details>

<details>
<summary><strong>📂 3C. Source Corpus Mapping & Automated Verification Suite (Click to Expand)</strong></summary>

| Source Folder / Artifact | Files / Rows | Target Domain Object | Gate Status |
| :--- | :--- | :--- | :--- |
| `master/uat/publish/index.html` | 1 master UAT portal (Sections A..E) | `uat.readiness_gates + uat.script_runs` | **100% MAPPED** |
| `master/uat/publish/readiness.csv` | 16 gates (R0, R0b, R0c, R1..R13) | `uat.readiness_gates` | **100% MAPPED** |
| `master/uat/publish/tracker.csv` | 13-column closed-loop bug ledger | `uat.issue_tracker` | **100% MAPPED** |
| `master/uat/publish/walkthrough/*.html` | 6 role walkthroughs (FOH, Kiosk, BOH, Shift, Outlet, Cluster) | `Static Interactive Walkthrough Suite` | **100% MAPPED** |

**Verification Evidence:** All 16 Readiness Gates (R0..R13), 6 Role Walkthroughs (C1..C6), 17 UAT Personas, and 10 Troubleshooting Runbooks (E1..E10) verified live.

</details>