← Back to Oven Command
INTAKE-DESIGN-T1-11-PEOPLE-ROSTER-LOANS.md

# Overall People Module: Dual-Entry Onboarding, 6-Category Doc Vault, 6-Outlet Presence Radar, Shift Roster, Crew Loans, Permanent Transfers, Offboarding & Staff Loans (`STOP 4 · T1-11 · EPIC-CAFE-PEOPLE-PRESENCE-MOBILITY + EPIC-CONFIG-ADMIN-PEOPLE-OUTLET · 629 STAFF`)
> **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** · ✅ Peer-Reviewed (Opus 4.7 Max + Astra Extra High) · Unifies PM-1..10 (HR Payroll Export Importer, DPDP Block-List, Central Master Data Holder Registry, 7+1 Depts / 95 Sub-Functions / 33+ Titles, Temporal Membership != Visibility, Non-Prod PII Masking) + T1-11 Full Lifecycle (Onboarding, 6-Cat Doc Vault, Presence Radar, Shift Roster, Temp Loans vs Perm Transfers, 5-Gate Offboarding)
> **🔒 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)` &rarr; `App 1b (People & HR Importer)` &rarr; `App 2 (Daily Store Ops, Kiosk & Outlet Summary OS-1..7)` &rarr; `App 3 (Legal & Compliance)` &rarr; `App 4 (Fixed Assets & Maint)` &rarr; `App 5 (Café Projects)` &rarr; `App 6 (7-Stage NPL)` &rarr; `App 7 (Cross-App UAT Gate)` &rarr; `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
- **Unifies Owner Pack 3 (`pkg3/people-module-2026-10-22` `PM-1..10`, `A127`, `A368`, `A369b`, `A568`, `A570`) with `T1-11` Café Presence & Mobility:** **(1) `PM-1` One Identity Record (`users / hop.people`, `H-000001..108` reserved, `hr_emp_no` unique) separated from Access (`user_assignments`)**—imports and HR screens can never grant access; **(2) `PM-2` Central Master Data Holder Registry (`master_data_holders`)** governing all 21 master domains (`Department, Sub-Function, Title, Grade, Runs-Shifts Mark, Person, Role, Placement, Cover, Phone, Access, Delegates, Outlets, Kiosks, PIN`); **(3) `PM-3` Seeded `7+1` Departments (`CEO/Corporate Office + Finance, Accounts, Ops & Legal, HR, Projects, Academy [L&D + R&D], Sales & Marketing`), `95` Sub-Functions & `33+` Title LOVs** (where Title proposes a persona and never grants access); **(4) `PM-4 & PM-5` 46-Column HR Payroll Export Reducer (`588` rows) & Dry-Run (`report_hash`) -> `APPLY` Importer with Stored Import Rounds (`people_import_rounds`) and Strict DPDP Block-List (`A570`: PAN, Aadhaar, Bank, IFSC, UAN, ESIC, Salary, DOB, Family, Address kept OUT of main app DB)**; **(5) `PM-6 & PM-7` Temporal `person_membership` (`EXCLUDE USING gist`) enforcing `Membership = Kiosk Roster` vs `Cover/Assignments = Management Visibility` via `access.for(user)`**; and **(6) `PM-10` Mandatory Non-Production Data-Copy PII Masking**.
- **Unifies Owner Pack 3 (`pkg3/people-module-2026-10-22` `PM-1..10`, `A127`, `A368`, `A369b`, `A568`, `A570`) with `T1-11` Café Presence & Mobility:** **(1) `PM-1` One Identity Record (`users / hop.people`, `H-000001..108` reserved, `hr_emp_no` unique) separated from Access (`user_assignments`)**—imports and HR screens can never grant access; **(2) `PM-2` Central Master Data Holder Registry (`master_data_holders`)** governing all 21 master domains (`Department, Sub-Function, Title, Grade, Runs-Shifts Mark, Person, Role, Placement, Cover, Phone, Access, Delegates, Outlets, Kiosks, PIN`); **(3) `PM-3` Seeded `7+1` Departments (`CEO/Corporate Office + Finance, Accounts, Ops & Legal, HR, Projects, Academy [L&D + R&D], Sales & Marketing`), `95` Sub-Functions & `33+` Title LOVs** (where Title proposes a persona and never grants access); **(4) `PM-4 & PM-5` 46-Column HR Payroll Export Reducer (`588` rows) & Dry-Run (`report_hash`) -> `APPLY` Importer with Stored Import Rounds (`people_import_rounds`) and Strict DPDP Block-List (`A570`: PAN, Aadhaar, Bank, IFSC, UAN, ESIC, Salary, DOB, Family, Address kept OUT of main app DB)**; **(5) `PM-6 & PM-7` Temporal `person_membership` (`EXCLUDE USING gist`) enforcing `Membership = Kiosk Roster` vs `Cover/Assignments = Management Visibility` via `access.for(user)`**; and **(6) `PM-10` Mandatory Non-Production Data-Copy PII Masking**.
- **Complete Synthesis of All People Backlog Sources (`EPIC-CONFIG-ADMIN-PEOPLE-OUTLET` `C36–C51` & `E1–E6` + `INTAKE-T1-11` + `CONTRACT-T1-11` + `PEOPLE-MODULE-DESIGN` `PEO1–PEO6`):** Unifies the 629-employee directory (`hop.people`, immutable `H-xxxxxx` codes), the **5-Tier Authority Matrix** (`Super Admin [Cap=3] / Admin / Config Lead / Store & Shift Manager / Kiosk Crew`), **E1–E6 UAT Trap Killers** (Single-Trip Onboarding, Unified Shift-Lead Truth, 10-Point Pre-Flight Readiness Banner, Session-Safe PIN Reset), and the **6 Multi-Outlet Café Presence & Mobility Pillars** into one cohesive module.
- **Full 5-Stage Employee Lifecycle (Manager OR HR Initiation at Every Boundary):** **(1) Dual-Entry Onboarding (`people_onboarding_cases`):** Store/Cluster Manager can initiate field onboarding on `/people` or Kiosk when a new hire walks in (`Name, Phone, Home Outlet, FOH/BOH Station, Shift A/B/C, Live Photo` -> mints `H-xxxxxx`, sets Kiosk PIN, and opens a **7-Day Document & Medical Collection Checklist** routed to HR), OR HR/Admin initiates via Single-Trip Sheet / Bulk CSV Dry-Run (`report_hash`) -> `APPLY`; **(2) Structured 6-Category Document Vault & Single Person Passport (`people_doc_vault` & `staff_skill_passports`):** S3 vault with DPDP Act 2023 masking (Managers see status chips; HR/Admin see PDFs/masked refs), enforcing a **Hard Roster/Loan Block on `FOOD_STATIONS` when Annual Medical (`FSSAI Form 4`) is `EXPIRED`**; **(3) Temporary Same-Day Crew Loans (`staff_inter_outlet_loans`) vs. Permanent 4-State Inter-Outlet Transfers (`people_transfer_requests`):** Distinguishes 1-day shift borrowing (`NAN -> JUB 14:00–22:00`, `home_outlet_code` unchanged) from permanent store/role transfers (`INITIATED -> RELIEVING_MANAGER_CLEARANCE -> RECEIVING_MANAGER_AND_HR_APPROVAL -> COMPLETED_ACTIVE`); **(4) Shift Assignment, Weekly Roster Grid (`Draft -> Publish`), Station Coverage Heat-Check (`RED/AMBER/GREEN`) & 1-Tap Sick-Call Cover Finder (`outlet_shifts`, `staff_roster_assignments`)** with Shops & Establishments guardrails (`<=9h/day, <=48h/wk, >=10h rest gap, <=6 consecutive days`); **(5) Manager- or HR-Initiated Offboarding & 5-Gate Exit Clearance (`people_offboarding_cases`):** Immediate Kiosk/Session Kill Switch, Uniform/Key M3 Clearance, Auto-Reassignment of Open Single-Owner Tasks & `L6/L7` NPL Layers, **Staff Loan `FnF Lien` Deduction Gate (`<=25%` EMI cap)**, and Rehire Eligibility Tag.
- **100% Compliant with HOP Nudge & Accountability Framework (`acct-*` / `O-022` / `O-045`):** Deterministic nudge ladders govern missing onboarding docs (`D+3, D+6, D+7`), expiring Medical/FoSTaC (`T-14d, T-7d, T-0`), unapproved loans/transfers (`+15m, +30m`), late check-ins (`T+0, +5m, +15m, +30m`), and stalled exit clearances.

### 1B. Personas & Access Scope
- **Store / Cluster Manager (`Rohit MGR-01`, `Arjun MGR-02`, `Jay CLM-01` — `/manager/presence`, `/manager/roster`, `/people`)**: Initiates walk-in field onboarding (`H-xxxxxx`), builds/publishes weekly `A/B/C/Split` shift rosters, views real-time Presence Radar & Station Coverage Heat-Check, uses **1-Tap Sick-Call Cover Finder**, initiates/approves **Temporary Crew Loans** OR **Permanent Store Transfers** (`Relieving / Receiving Clearance`), and initiates **Offboarding** (Resignation / Absconding `3x NO_SHOW` / Disciplinary) with M3 uniform/key verification.
- **HR Operations & Admin (`C36` Manage Rail — `/admin/people`, `/admin/people/roster`, `/admin/people/{ref}/passport`)**: Initiates Single-Trip or CSV Dry-Run (`report_hash`) -> `APPLY` onboarding, verifies the **6-Category Document Vault** (`Aadhaar Masked, PAN, Bank/UPI, UAN/ESIC/PT, FSSAI Form 4 Medical, FoSTaC, Offer/BGV`), approves permanent transfers (`primary_outlet_code` & cost center cutover), runs monthly `<=25%` EMI loan deductions, and executes **5-Gate FnF Exit Clearance**.
- **Super Admin (`Owner cfo@harleys.com` — Hard Cap = 3, `C51`)**: Sets user `TYPE` (`Staff / Config / Admin / Super Admin`), marks power roles, and clicks **`Login As` (`See as PERSON`)** on any row in `/admin/people` (read-only preview banner; never writes biometric presence events under a borrowed identity).
- **Café / Commissary Crew (`360px/390px` Kiosk & Phone)**: Unlocks Kiosk via 6-digit Outlet PIN (`O-022`), checks in/out/breaks via 4-digit User PIN + live selfie (valid at home outlet OR approved `LOANED_IN` outlet within `-30m` early margin), views own schedule/hours (zero shaming leaderboards per `T2-4` Dignity Rule), and e-signs Staff Loan `FnF Lien` consent.

### 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 **Dual-Entry Onboarding (`people_onboarding_cases`)** allowing **both Store/Cluster Managers (field walk-in) and HR/Admin (Single-Trip / CSV Dry-Run -> `APPLY`)** to initiate onboarding with a tracked **7-Day Document & Medical Collection Checklist**.
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:57 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** Approve the **6-Category S3 Document Vault & Single Person Passport (`people_doc_vault` & `staff_skill_passports`)** with DPDP masking, **Medical `EXPIRED` Hard Block on `FOOD_STATIONS`**, FoSTaC `1:25` gate, `T1-10` NPL badges, and `T1-13` Maintenance 2nd-Person Verifier authorization.
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:57 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** Approve **both Mobility Engines**: (a) **Temporary Same-Day Crew Loans (`staff_inter_outlet_loans`)** (`NAN -> JUB 14:00–22:00`, `home_outlet_code` unchanged, Dual-Manager or Cluster Manager approval + pro-rata P&L labor attribution) AND (b) **Permanent 4-State Inter-Outlet / Role Transfers (`people_transfer_requests`)** (`INITIATED -> RELIEVING_MANAGER_CLEARANCE -> RECEIVING_MANAGER_AND_HR_APPROVAL -> COMPLETED_ACTIVE`).
- [x] **[RATIFIED & LOCKED BY OWNER · 2026-10-22 22:57 IST — 100% INTAKE & DESIGN GATES LOCKED (App 0 -> App 6)]** Approve **Shift Templates (`Shift A/B/C/Split`), 7-Day Roster Grid (`Draft -> Publish`), Station Coverage Heat-Check (`RED/AMBER/GREEN`), 1-Tap Sick-Call Cover Finder**, and **Manager/HR-Initiated 5-Gate Offboarding & `<=25%` EMI / `FnF Lien` Clearance**.

### 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)
- 🟢 **J19 8-Frame People & Lifecycle Storyboard**: `/static/journeys/j19-people-roster-loans-loginas.html`
- 🟢 **Local :8000 People & Roster Console**: `http://localhost:8000/admin/people`
- 🟢 **Local :8000 Unified People Admin**: `http://localhost:8000/admin/people`
- 🟢 **Staging HOP People Console**: `https://test.hop.harleys.com/admin/people`

---

## 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 |
| :--- | :--- | :--- |
| **PPL-J01 · Dual-Entry Onboarding: Store Manager Field Initiate OR HR Single-Trip / CSV Dry-Run (`POST /api/people/onboarding`)** | Store/Cluster Manager OR HR/Admin | **Path A (Manager Field Initiate):** Store Manager enters `Name, Phone, Home Outlet (NAN), Department (FOH/BOH), Station, Default Shift (A/B/C), Live Photo` -> atomically mints `H-xxxxxx`, creates `user_assignments` row (unified shift-lead truth `E2`), triggers Kiosk 4-digit PIN setup (`J02`), and opens a **7-Day Document Collection Checklist** (`ONBOARDING_PROVISIONAL_7D`) with HOP Nudges to HR (`D+3, D+6, D+7`). **Path B (HR HQ Initiate):** Single-Trip Onboarding Sheet or Bulk CSV Upload (`Preview Diff -> report_hash -> typed APPLY`). |
| **PPL-J02 · 6-Category Document Collection & Single Person Passport Vault (`POST /api/people/{ref}/docs` & `/passport`)** | HR Ops / Admin (Edit) · Store Manager (Status Chips Only) | Collects and verifies 6 packet categories in `s3://harleys-people-vault/`: **(1) Identity & Bank KYC** (Masked Aadhaar `XXXX-XXXX-1234`, PAN, Verified Bank/UPI, Emergency Contact); **(2) Statutory Social Security** (`UAN`, `ESIC`, `PT`); **(3) Annual Medical Fitness (`FSSAI Form 4`)** (`VALID / EXPIRING_14D / EXPIRED` — **`EXPIRED` hard-blocks rostering or loaning into `FOOD_STATIONS`**); **(4) FSSAI FoSTaC (`Basic / Supervisor`)**; **(5) Offer Letter, BGV & Uniform/Locker Receipt**; **(6) Station Certifications (`ESPRESSO, PASTRY_FINISH, FOH_COUNTER, BOH_CONTINENTAL`), `T1-10` NPL Badges & `T1-13` Maintenance 2nd-Person Verifier Flag**. |
| **PPL-J03 · Shift Templates (`A/B/C/Split`), Weekly Roster Grid (`Draft -> Publish`) & Guardrails (`POST /api/people/roster/publish`)** | Outlet Manager / Cluster Manager | Configures per-outlet Shift Templates (`Shift A Opening 07:00–15:30`, `Shift B Mid 11:00–19:30`, `Shift C Closing 14:30–23:00`, `Split Shift`, `Week Off`, `Leave`) with break windows, 15m grace, and `station_min` JSONB. Evaluates **Shops & Establishments Guardrails** (`<=9h/day`, `<=48h/wk`, `>=10h` rest gap between Night Close and Morning Open, `<=6` consecutive days) + **Medical `EXPIRED` hard block** + **Station Coverage Heat-Check (`RED/AMBER/GREEN`)** before publishing. |
| **PPL-J04 · 6-Outlet Real-Time Presence Radar, Kiosk Punch Timeline & 1-Tap Sick-Call Cover Finder (`GET /api/people/presence`)** | Outlet crew (Kiosk) -> Shift/Outlet/Cluster Manager | Derives live state via pure function `derive_presence()` (`SCHEDULED -> DUE -> PRESENT -> ON_BREAK -> LATE -> ABSENT / NO_SHOW -> RELIEVED` + `LOANED_IN / LOANED_OUT`). Late check-in (`> shift_start + 15m`) triggers the 4-rung HOP Nudge ladder (`T+0, +5m, +15m, +30m`). Clicking **`[Find Cover]`** on an `ABSENT` row or `RED` station ranks unscheduled staff in the cluster who hold `CERTIFIED` station skill + `VALID` medical + weekly-hours headroom. |
| **PPL-J05 · Temporary Same-Day Inter-Outlet Crew Loan (`POST /api/people/loans` -> `/approve`)** | Requesting Outlet Mgr / Cluster Mgr (`NAN -> JUB 14:00–22:00`) | Borrows a crew member for **1 business date and time window** while `home_outlet_code` remains `NAN`. Approved by **Outlet Manager OR Cluster Manager (`approved_by_role IN ('outlet_manager', 'cluster_manager')`) with automatic visibility & audit feed notification to City Head (`city_head`, `A2 / BS-04` Owner Lock 22:39 IST)** (`approver_id <> person_id`). Upon approval, the person's 4-digit PIN + selfie check-in is valid **only at `JUB`'s Kiosk** (`starts_at - 30m` to `ends_at`), shows `Loaned from NAN`, marks `LOANED_OUT` at `NAN`, and **attributes pro-rata hourly labor cost to `JUB`'s P&L**. |
| **PPL-J06 · Permanent Inter-Outlet & Role Transfer Module (`POST /api/people/transfers` -> `/relieve` -> `/approve`)** | Store Manager / Cluster Manager / HR (`people_transfer_requests`) | Handles permanent store relocations (`NAN -> GACH`) or role promotions (`Staff -> Shift Lead`): **(1) `INITIATED`** (by Store Mgr, Cluster Mgr, or HR with `effective_date` & reason); **(2) `RELIEVING_MANAGER_CLEARANCE`** (current Store Mgr signs off handover of store keys/apron/pending tasks); **(3) `RECEIVING_MANAGER_AND_HR_APPROVAL`** (receiving Store Mgr + HR sign off); **(4) `COMPLETED_ACTIVE`** (atomically updates `primary_outlet_code`, ends old `user_assignments` row with `ended_at`, creates new assignment + cost-center binding, and re-homes future roster rows). |
| **PPL-J07 · Staff Loans (`<= 25%` Gross EMI Cap), Idempotent Payroll & Signed FnF Lien (`POST /api/people/staff-loans`)** | Employee -> HR / CFO -> Payroll Controller | Enforces Payment of Wages Act / Code on Wages `monthly_emi_inr <= 0.25 * monthly_gross_inr` (`check_25pct_emi_cap`), captures e-signed **Contractual FnF Set-Off & Lien Authorization**, and runs monthly deductions with `UNIQUE (loan_id, payroll_month)`. |
| **PPL-J08 · Manager- or HR-Initiated Offboarding & 5-Gate Exit Clearance (`POST /api/people/{id}/offboard`)** | Store/Cluster Manager (Resignation / `3x NO_SHOW` Absconding / Disciplinary) OR HR/Admin | Executes the deterministic **5-Gate Exit Pipeline**: **(Gate 1) Immediate Kiosk/Session Kill Switch** (revokes sessions in `<30s`, zeroes 4-digit PIN, stamps `ended_at` on `user_assignments` while preserving historical audit/task rows); **(Gate 2) Store Asset/Uniform/Key M3 Clearance** (Store Mgr sign-off); **(Gate 3) Automatic Single-Owner Task & NPL Layer (`L6/L7`) Reassignment Prompt** (prevents orphaned tasks/alerts); **(Gate 4) Staff Loan & Advance `FnF Lien` Zero-Balance Gate** (`HTTP 409 FNF_OUTSTANDING_LOAN_BLOCK` until recovered/set off); **(Gate 5) Relieving Letter & Rehire Eligibility Tag (`ELIGIBLE_FOR_REHIRE` vs `DO_NOT_REHIRE`)**. |

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

```text
END-TO-END PEOPLE, PRESENCE, MOBILITY & HR LIFECYCLE ARCHITECTURE (10 TABLES):
[1. Dual-Entry Onboarding (Store Mgr Field Initiate OR HR Single-Trip / CSV Dry-Run -> APPLY)] --> Mints immutable H-xxxxxx in [hop.people]
  --> [2. 6-Category S3 Doc Vault & Single Person Passport (people_doc_vault + staff_skill_passports: Medical Form 4 EXPIRED Blocks Food Stations!)]
  --> [3. Shift Templates (A/B/C/Split) & Weekly Roster Grid (outlet_shifts + staff_roster_assignments: <=9h/d, <=48h/wk, >=10h rest gap)]
  --> [4. 6-Outlet Presence Radar & Append-Only Punch Log (staff_presence_events + derive_presence() + 1-Tap Sick-Call Cover Finder)]
  +--> [5A. Temporary Same-Day Crew Loan (staff_inter_outlet_loans: Home Outlet Unchanged, Kiosk Re-Jailed for Window, Pro-Rata P&L Debit)]
  +--> [5B. Permanent 4-State Transfer (people_transfer_requests: INITIATED -> RELIEVING_MGR -> RECEIVING_MGR_HR -> Updates primary_outlet_code)]
  --> [6. Manager/HR-Initiated Offboarding & 5-Gate Exit (people_offboarding_cases: Kill Switch -> Uniform M3 -> Task Reassign -> Loan FnF Lien == ₹0)]
```

| Domain Object (`Table`) | Primary Key & Scope | Key Attributes & Constraints | Cross-Object Handshake |
| :--- | :--- | :--- | :--- |
| `hop.people & hop.user_assignments` | `id (PK `H-xxxxxx`), assignment_id (PK)` | person_code, full_name, phone, primary_outlet_code, department, role_key, scope_type, scope_value, starts_at, ended_at, reports_to, super_admin (Cap=3) | Canonical identity & effective-dated role/scope assignment (`E1`, `E2`, `PEO3`). |
| `people_onboarding_cases & people_doc_vault` | `case_id (PK), doc_id (PK), person_id (FK)` | initiated_by_role (`MANAGER_FIELD`/`HR_ADMIN`/`CSV_IMPORT`), provisional_deadline_7d, doc_category (6 categories), s3_object_key, sha256_hex, verification_status (`VALID`/`EXPIRING`/`EXPIRED`/`MISSING`), dpdp_masked_ref | Tracks Manager/HR onboarding and the 6-category S3 employee document packet. |
| `staff_skill_passports` | `person_id (PK/FK hop.people)` | station_certs_json (`ESPRESSO, PASTRY_FINISH, FOH_COUNTER, BOH_CONTINENTAL`), medical_fitness_status, medical_valid_until, fostac_level, fostac_valid_until, uan_esic_status, maint_verifier_authorized_by | Single Person Passport read by Roster, Loans, Stop 1 Compliance, Stop 2 Maintenance, and Stop 3 NPL. |
| `outlet_shifts & staff_roster_assignments` | `shift_id (PK), assignment_id (PK)` | outlet_code, shift_key (`MORNING`/`MID`/`CLOSING`/`SPLIT`), start_time, end_time, grace_minutes (15), station_min_json, business_date, active_outlet_code, state (`DRAFT`/`PUBLISHED`), guardrail_override_reason | Governs weekly roster grid, Shops & Establishments guardrails, and station coverage heat-check. |
| `staff_presence_events` | `event_id (PK), person_id (FK), outlet_code` | business_date, event_type (`CHECK_IN`/`BREAK_START`/`BREAK_END`/`CHECK_OUT`/`MARK_LATE`/`MARK_ABSENT`/`CORRECTION`), occurred_at, selfie_s3_key, corrects_event_id, clock_suspect | Append-only presence fact log driving `derive_presence()` and Attendance Summary CSV. |
| `staff_inter_outlet_loans & people_transfer_requests` | `loan_id (PK), transfer_req_id (PK)` | Loan: `home_outlet_code, to_outlet_code, loan_date, starts_at, ends_at, approval_mode, home_mgr_id, to_mgr_id, cluster_mgr_id`. Transfer: `from_outlet, to_outlet, new_role_key, effective_date, relieving_mgr_signed_by, receiving_mgr_signed_by, hr_approved_by, state` | Separates 1-day shift borrowing from permanent 4-state inter-outlet/role transfers. |
| `people_loans & people_offboarding_cases` | `loan_id (PK), offboard_id (PK)` | Loan: `principal_inr, monthly_emi_inr (<=25% gross), fnf_lien_signed_sha256, outstanding_balance_inr`. Offboard: `initiated_by_id, exit_type, session_killed_at, uniform_key_m3_cleared_by, tasks_reassigned_to_id, fnf_loan_recovered_bool, rehire_status` | Enforces `<=25%` EMI cap, idempotent payroll deductions, and 5-gate exit clearance. |

### 2C. State Machines & Operational Guardrails
- **1. Dual-Entry Onboarding & 6-Category Doc Vault (`ONB-S1`)**: <code>MANAGER_FIELD_INITIATED</code> (or <code>HR_SINGLE_TRIP / CSV_APPLY</code>) &rarr; <code>H_CODE_AND_KIOSK_PIN_ACTIVE</code> &rarr; <code>7D_DOC_AND_MEDICAL_COLLECTION</code> (HOP Nudges `D+3, D+6, D+7`) &rarr; <code>PASSPORT_VERIFIED</code> (Medical `EXPIRED` hard-blocks `FOOD_STATIONS`).
- **2. 6-Outlet Presence Radar & Station Heat-Check (`PRS-S2`)**: Derived via `derive_presence()`: <code>SCHEDULED</code> &rarr; <code>DUE</code> (15m grace) &rarr; <code>PRESENT</code> / <code>ON_BREAK</code> / <code>LATE</code> (4-rung HOP Nudge `T+0..+30m`) / <code>ABSENT</code> (<strong>1-Tap Sick-Call Cover Finder</strong>) &rarr; <code>RELIEVED</code>.
- **3. Temporary Crew Loan vs. Permanent Transfer (`MOB-S3`)**: <strong>Temp Loan (1-Day):</strong> <code>REQUESTED</code> &rarr; <code>APPROVED</code> (Cluster Mgr OR Both Store Mgrs) &rarr; <code>KIOSK_VALID_AT_RECEIVING_STORE</code> &rarr; <code>COMPLETED</code>.<br><strong>Perm Transfer:</strong> <code>INITIATED</code> &rarr; <code>RELIEVING_MGR_CLEARANCE</code> &rarr; <code>RECEIVING_MGR_AND_HR_APPROVAL</code> &rarr; <code>COMPLETED_ACTIVE</code> (Updates `primary_outlet_code`).
- **4. Manager/HR Offboarding & 5-Gate FnF Clearance (`OFF-S4`)**: <code>EXIT_INITIATED</code> (Mgr or HR) &rarr; <code>1_SESSION_AND_PIN_KILLED</code> &rarr; <code>2_UNIFORM_KEY_M3_CLEARED</code> &rarr; <code>3_TASKS_AND_NPL_REASSIGNED</code> &rarr; <code>4_LOAN_FNF_LIEN_SETTLED (Balance == ₹0)</code> &rarr; <code>5_RELIEVED_AND_REHIRE_TAGGED</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 |
| :--- | :--- | :--- |
| **Keka / Darwinbox & `EPIC-CONFIG-ADMIN-PEOPLE-OUTLET` (`C36–C51`, `E1–E6`)** | **Dual-Entry Onboarding (Store Manager Field Initiate OR HR Single-Trip / CSV Dry-Run -> `APPLY`) + 3-Layer Authority** | Eliminates Dash's 4-screen onboarding regret (`E1`) and dual shift-lead lists (`E2`): Store/Cluster Manager can initiate field onboarding on `/people` or Kiosk (generating `H-xxxxxx`, Kiosk PIN, and a 7-day HR Doc Checklist), while HR/Admin runs Single-Trip or CSV Dry-Run (`report_hash`) -> `APPLY`. |
| **DPDP Act 2023 & FSSAI Form 4 / FoSTaC Single Person Passport (`people_doc_vault`)** | **6-Category S3 Document Vault + Medical `EXPIRED` Hard Block on Food Stations + FoSTaC `1:25` Gate** | Tracks (a) Masked Identity/Bank KYC, (b) EPFO `UAN` / `ESIC` / `PT`, (c) Annual Medical Fitness (`FSSAI Form 4` — hard-blocks rostering/loaning onto `FOOD_STATIONS` when `EXPIRED`), (d) FoSTaC (`Basic/Supervisor`), (e) Offer/BGV/Uniform, and (f) Station Certifications + `T1-10` NPL Badges + `T1-13` Maintenance Verifier status. |
| **7shifts / Deputy / Fourth Hospitality & `CONTRACT-T1-11`** | **6-Outlet Real-Time Presence Radar + Shift Templates (`A/B/C/Split`) + 7-Day Roster Grid (`Draft -> Publish`) + Station Heat-Check + Sick-Call Cover Finder** | Derives live states (`SCHEDULED, DUE, PRESENT, ON_BREAK, LATE, ABSENT, RELIEVED, LOANED_IN/OUT`), enforces Shops & Establishments guardrails (`<=9h/day, <=48h/wk, >=10h rest gap, <=6 consecutive days`), shows `RED/AMBER/GREEN` station coverage, and provides 1-Tap Sick-Call Cover Finder. |
| **Pret A Manger / Multi-Unit Hospitality Mobility Standard** | **Temporary Same-Day Crew Loans (`staff_inter_outlet_loans`) vs. Permanent 4-State Inter-Outlet Transfers (`people_transfer_requests`)** | Separates same-day borrowing (`NAN -> JUB 14:00–22:00`, `home_outlet_code` unchanged, Dual-Manager or Cluster Manager approval + pro-rata P&L labor attribution) from permanent store/role transfers (`INITIATED -> RELIEVING_MANAGER_CLEARANCE -> RECEIVING_MANAGER_AND_HR_APPROVAL -> COMPLETED_ACTIVE`). |
| **Payment of Wages Act & 5-Gate Offboarding (`people_offboarding_cases`)** | **Manager/HR-Initiated Exit + Immediate Kiosk/Session Kill Switch + Task/NPL Reassign + `<=25%` EMI & Signed FnF Lien Gate** | Store/Cluster Manager or HR can initiate offboarding (Resignation, Absconding `3x NO_SHOW`, Disciplinary); runs 5-gate exit pipeline: (1) Kiosk PIN zeroed & session killed, (2) Uniform/Key/Badge M3 clearance, (3) Auto-reassignment of open tasks & `L6/L7` NPL ownership, (4) Staff Loan `FnF Lien` balance recovery, and (5) Relieving letter & rehire tag. |
| **HOP Nudge & Accountability Integration (`acct-*`) + Hostile Peer Review (`Astra XHigh` + `Opus 4.7`)** | **✅ APPROVED — COMPLETE BACKLOG SYNTHESIS (`EPIC-CONFIG-ADMIN` + `T1-11` + 5 LIFECYCLE PILLARS)** | Wires deterministic HOP nudge ladders on missing onboarding docs (`D+3, D+6, D+7`), expiring medical/FoSTaC (`T-14d, T-7d, T-0`), unapproved loans/transfers (`+15m, +30m`), late check-ins (`T+0, +5m, +15m, +30m`), and stalled exit clearances. |

### 2E. Complete People Backlog Synthesis (`EPIC-CONFIG-ADMIN C36–C51`, `E1–E6 Trap Killers`, `PEO1–PEO6` & 5 Lifecycle Pillars)

| Backlog Source / Pillar | Core Capabilities & Guardrails Synthesized | Target Table / Route |
| :--- | :--- | :--- |
| **1. Dual-Entry Onboarding (`E1`, `PEO5`)** | **Store/Cluster Manager Field Initiate** (`/people` or Kiosk walk-in -> mints `H-xxxxxx`, sets 4-digit Kiosk PIN, opens 7-day HR Doc Checklist with `D+3/D+6/D+7` HOP Nudges) **OR HR/Admin HQ Initiate** (Single-Trip Sheet & Bulk CSV Dry-Run `report_hash` -> `APPLY`). | `people_onboarding_cases` · `/admin/people` · `/people` |
| **2. 6-Category Doc Vault & Single Person Passport (`Pillar 4`)** | S3 Vault (`s3://harleys-people-vault/`) with DPDP masking (status chips for Managers; PDFs for HR/Admin): **(a)** Masked Aadhaar/PAN/Bank, **(b)** `UAN/ESIC/PT`, **(c)** **Annual Medical Form 4 (`EXPIRED` hard-blocks `FOOD_STATIONS`)**, **(d)** FoSTaC (`1:25`), **(e)** Offer/BGV/Uniform, **(f)** Station Certs + `T1-10` NPL Badges + `T1-13` Maint Verifier. | `people_doc_vault` · `staff_skill_passports` · `/admin/people/{ref}/passport` |
| **3. Shift Templates, 7-Day Roster Grid & Cover Finder (`Pillar 1, 3, 5`)** | Per-outlet `Shift A (07:00–15:30)`, `Shift B (11:00–19:30)`, `Shift C (14:30–23:00)`, `Split`, `Week Off`, `Leave`. Enforces `<=9h/day, <=48h/wk, >=10h rest gap, <=6 consecutive days`, `RED/AMBER/GREEN` station heat-check, `derive_presence()` 6-outlet radar, and **1-Tap Sick-Call Cover Finder**. | `outlet_shifts` · `staff_roster_assignments` · `staff_presence_events` · `/manager/presence` |
| **4. Temp Same-Day Crew Loans vs. Permanent 4-State Transfers (`Pillar 2`, `PEO3`)** | **Temp Loan (`staff_inter_outlet_loans`):** 1-day window (`NAN -> JUB 14:00–22:00`), `home_outlet_code` unchanged, Cluster Mgr or Dual-Store-Mgr approval, Kiosk re-jailed for window + pro-rata P&L labor attribution. **Permanent Transfer (`people_transfer_requests`):** `INITIATED -> RELIEVING_MGR_CLEARANCE -> RECEIVING_MGR_AND_HR_APPROVAL -> COMPLETED_ACTIVE` (updates `primary_outlet_code` & cost center). | `staff_inter_outlet_loans` · `people_transfer_requests` |
| **5. Manager/HR Offboarding, 5-Gate Exit & Staff Loans (`PEO6`)** | Initiated by Store/Cluster Mgr (`Resignation / 3x NO_SHOW Absconding / Disciplinary`) or HR: **(1)** Immediate Session/PIN Kill Switch, **(2)** Uniform/Key M3 Clearance, **(3)** Open Task & `L6/L7` NPL Reassignment, **(4)** **Staff Loan `<=25%` EMI & Signed `FnF Lien` Zero-Balance Gate**, **(5)** Relieving Letter & Rehire Tag. | `people_offboarding_cases` · `people_loans` · `people_loan_installments` |
| **6. 5-Tier Authority (`C36–C51`) & `E1–E6` UAT Trap Killers** | `Super Admin (Cap=3, Login As)` · `Admin` · `Config Lead` · `Store/Shift Mgr` · `Kiosk Crew (6-digit Outlet PIN + 4-digit User PIN)`. Unified Shift-Lead truth (`E2`), 10-Point Pre-Flight Readiness Banner (`E3`), Dependency-Guarded Switches (`E4`), Session-Safe PIN Reset (`E5`). | `hop.people` · `hop.user_assignments` · `/admin/switches` |

### 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 |
| :--- | :--- |
| **Dual-Entry Onboarding (`people_onboarding_cases`)** | Allows either an Outlet/Cluster Manager (when a new hire reports to the café floor) or HR/Admin (from HQ `/admin/people` or CSV Dry-Run -> `APPLY`) to create `H-xxxxxx` and trigger a tracked 7-day document collection workflow. |
| **Single Person Passport (`staff_skill_passports`)** | Unified employee capability & compliance record read by Roster, Loans, Compliance (`T1-8`), NPL (`T1-10`), and Maintenance (`T1-13`), holding station skills, Medical Form 4 validity, FoSTaC level, and DPDP-masked KYC statuses. |
| **Temporary Crew Loan vs. Permanent Transfer** | A **Temporary Loan** (`staff_inter_outlet_loans`) borrows a worker for one date/window without changing `home_outlet_code`; a **Permanent Transfer** (`people_transfer_requests`) moves `primary_outlet_code`, `user_assignments`, and cost center after Relieving Manager + Receiving Manager + HR sign-off. |
| **5-Gate Offboarding & `FnF Lien` Gate** | Exit pipeline initiated by Manager or HR that immediately kills Kiosk/web sessions, clears store uniform/keys (`M3`), reassigns open single-owner tasks, recovers any `people_loans` balance under the signed FnF Lien, and records rehire eligibility. |

</details>

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

```sql
-- STOP 4 OVERALL PEOPLE MODULE DDL (ONBOARDING, DOC VAULT, PASSPORT, SHIFTS, ROSTER, PRESENCE, LOANS, TRANSFERS, OFFBOARDING)
CREATE TABLE people_onboarding_cases (
    case_id UUID PRIMARY KEY,
    person_id INTEGER NOT NULL REFERENCES hop.people(id),
    initiated_by_person_id INTEGER NOT NULL REFERENCES hop.people(id),
    initiation_channel VARCHAR(24) NOT NULL CHECK (initiation_channel IN ('MANAGER_FIELD','HR_SINGLE_TRIP','CSV_DRYRUN_APPLY')),
    home_outlet_code TEXT NOT NULL REFERENCES hop.outlets(branch_code),
    assigned_station VARCHAR(32) NOT NULL,
    default_shift_key VARCHAR(24) NOT NULL,
    docs_due_date DATE NOT NULL DEFAULT (CURRENT_DATE + 7),
    doc_checklist_status VARCHAR(28) NOT NULL DEFAULT 'PROVISIONAL_7D_OPEN' CHECK (doc_checklist_status IN ('PROVISIONAL_7D_OPEN','VERIFIED_COMPLETE','OVERDUE_ESCALATED')),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE people_doc_vault (
    doc_id UUID PRIMARY KEY,
    person_id INTEGER NOT NULL REFERENCES hop.people(id),
    doc_category VARCHAR(32) NOT NULL CHECK (doc_category IN (
        'IDENTITY_BANK_KYC','EPFO_ESIC_PT','MEDICAL_FITNESS_FORM4','FOSTAC_CERT','OFFER_BGV_UNIFORM','SKILL_BADGE_CERT'
    )),
    masked_reference VARCHAR(64),
    s3_object_key VARCHAR(255) NOT NULL,
    sha256_hex CHAR(64) NOT NULL,
    valid_from DATE,
    valid_until DATE,
    status VARCHAR(20) NOT NULL DEFAULT 'VALID' CHECK (status IN ('VALID','EXPIRING_14D','EXPIRED','MISSING','REJECTED')),
    verified_by_hr_id INTEGER REFERENCES hop.people(id),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE staff_skill_passports (
    person_id INTEGER PRIMARY KEY REFERENCES hop.people(id),
    station_certs_json JSONB NOT NULL DEFAULT '{}'::jsonb,
    medical_fitness_status VARCHAR(16) NOT NULL DEFAULT 'MISSING' CHECK (medical_fitness_status IN ('VALID','EXPIRING','EXPIRED','MISSING')),
    medical_valid_until DATE,
    fostac_level VARCHAR(20) CHECK (fostac_level IN ('NONE','BASIC','SUPERVISOR')),
    fostac_valid_until DATE,
    kyc_bank_uan_esic_status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    maint_domains_json JSONB NOT NULL DEFAULT '[]'::jsonb,
    maint_second_person_verifier BOOLEAN NOT NULL DEFAULT FALSE,
    verifier_authorized_by INTEGER REFERENCES hop.people(id),
    CONSTRAINT check_verifier_not_self CHECK (verifier_authorized_by IS NULL OR verifier_authorized_by <> person_id)
);

CREATE TABLE people_transfer_requests (
    transfer_req_id UUID PRIMARY KEY,
    person_id INTEGER NOT NULL REFERENCES hop.people(id),
    initiated_by_id INTEGER NOT NULL REFERENCES hop.people(id),
    from_outlet_code TEXT NOT NULL REFERENCES hop.outlets(branch_code),
    to_outlet_code TEXT NOT NULL REFERENCES hop.outlets(branch_code) CHECK (from_outlet_code <> to_outlet_code),
    from_role_key VARCHAR(32) NOT NULL,
    to_role_key VARCHAR(32) NOT NULL,
    effective_date DATE NOT NULL,
    reason_note TEXT NOT NULL,
    relieving_mgr_cleared_by INTEGER REFERENCES hop.people(id),
    relieving_cleared_at TIMESTAMPTZ,
    receiving_mgr_approved_by INTEGER REFERENCES hop.people(id),
    hr_approved_by INTEGER REFERENCES hop.people(id),
    status VARCHAR(32) NOT NULL DEFAULT 'INITIATED' CHECK (status IN (
        'INITIATED','RELIEVING_MANAGER_CLEARANCE','RECEIVING_MANAGER_AND_HR_APPROVAL','COMPLETED_ACTIVE','REJECTED','CANCELLED'
    )),
    CONSTRAINT check_perm_transfer_gates CHECK (
        status <> 'COMPLETED_ACTIVE' OR (
            relieving_mgr_cleared_by IS NOT NULL AND receiving_mgr_approved_by IS NOT NULL AND hr_approved_by IS NOT NULL
        )
    )
);

CREATE TABLE people_offboarding_cases (
    offboard_id UUID PRIMARY KEY,
    person_id INTEGER NOT NULL REFERENCES hop.people(id),
    initiated_by_id INTEGER NOT NULL REFERENCES hop.people(id),
    exit_type VARCHAR(24) NOT NULL CHECK (exit_type IN ('RESIGNATION','ABSCONDING_3X_NOSHOW','DISCIPLINARY','CONTRACT_END')),
    last_working_date DATE NOT NULL,
    gate1_session_pin_killed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    gate2_uniform_key_cleared_by INTEGER REFERENCES hop.people(id),
    gate3_open_tasks_reassigned_to INTEGER REFERENCES hop.people(id),
    gate4_outstanding_loan_inr NUMERIC(12,2) NOT NULL DEFAULT 0.00,
    gate4_fnf_lien_settled BOOLEAN NOT NULL DEFAULT FALSE,
    gate5_rehire_eligibility VARCHAR(24) CHECK (gate5_rehire_eligibility IN ('ELIGIBLE_FOR_REHIRE','DO_NOT_REHIRE')),
    status VARCHAR(24) NOT NULL DEFAULT 'IN_CLEARANCE' CHECK (status IN ('IN_CLEARANCE','FNF_CLEARED_CLOSED')),
    CONSTRAINT check_five_gate_fnf_exit CHECK (
        status <> 'FNF_CLEARED_CLOSED' OR (
            gate2_uniform_key_cleared_by IS NOT NULL
            AND gate3_open_tasks_reassigned_to IS NOT NULL
            AND (gate4_outstanding_loan_inr = 0.00 OR gate4_fnf_lien_settled = TRUE)
            AND gate5_rehire_eligibility IS NOT NULL
        )
    )
);

-- ============================================================================
-- PM-1..10 (OWNER PACK 3: HR PAYROLL IMPORT, MASTER DATA HOLDERS & DPDP BLOCK)
-- + OPUS 4.7 MAX & ASTRA EXTRA HIGH CONCURRENCY / MEDICAL / EMI FIXES
-- ============================================================================
CREATE EXTENSION IF NOT EXISTS btree_gist;

-- PM-2: Central Master Data Holder Registry (Table-Driven Governance)
CREATE TABLE IF NOT EXISTS master_data_holders (
    master_key VARCHAR(48) PRIMARY KEY,
    display_label VARCHAR(80) NOT NULL,
    holder_role VARCHAR(32) NOT NULL,
    approver_role VARCHAR(32),
    ui_route VARCHAR(120) NOT NULL,
    audit_category VARCHAR(32) NOT NULL DEFAULT 'admin'
);

-- PM-4 & PM-5: HR Payroll Export Import Rounds with Strict DPDP Block-List Audit
CREATE TABLE IF NOT EXISTS people_import_rounds (
    round_id UUID PRIMARY KEY,
    report_hash CHAR(64) UNIQUE NOT NULL,
    import_mode VARCHAR(24) NOT NULL CHECK (import_mode IN ('CREATE_ONLY','OPT_IN_UPDATE_BY_EMP_NO')),
    source_filename VARCHAR(160) NOT NULL,
    total_rows SMALLINT NOT NULL CHECK (total_rows <= 1000),
    ok_rows_count SMALLINT NOT NULL,
    refused_rows_count SMALLINT NOT NULL,
    blocked_dpdp_columns_dropped TEXT[] NOT NULL DEFAULT '{}', -- e.g. {'Aadhar','PAN','Bank Account No','IFSC','UAN','Date of Birth','Address'}
    refused_row_numbers_json JSONB NOT NULL DEFAULT '[]'::jsonb, -- Row numbers + reasons ONLY; never names in logs!
    applied_by_person_id INTEGER NOT NULL,
    applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- PM-6 & PM-7: Temporal Placement & Membership (Membership = Kiosk Roster != Cover = Visibility)
CREATE TABLE IF NOT EXISTS person_membership (
    membership_id UUID PRIMARY KEY,
    person_id INTEGER NOT NULL REFERENCES hop.people(id),
    outlet_code VARCHAR(32) NOT NULL,
    membership_kind VARCHAR(20) NOT NULL CHECK (membership_kind IN ('HOME_PRIMARY','TEMP_LOAN')),
    valid_period TSTZRANGE NOT NULL,
    reason TEXT,
    approved_by_id INTEGER REFERENCES hop.people(id),
    written_by_id INTEGER NOT NULL REFERENCES hop.people(id),
    EXCLUDE USING gist (person_id WITH =, valid_period WITH &&) WHERE (membership_kind = 'HOME_PRIMARY')
);

-- Hostile Review Fix #1: Cross-Path Phone Deduplication & Lifecycle Version Lock
ALTER TABLE hop.people ADD COLUMN IF NOT EXISTS normalized_phone VARCHAR(16) UNIQUE;
ALTER TABLE hop.people ADD COLUMN IF NOT EXISTS name_hi VARCHAR(120); -- PM-9 Optional Hindi Display Name for Kiosk
ALTER TABLE hop.people ADD COLUMN IF NOT EXISTS lifecycle_version INTEGER NOT NULL DEFAULT 1;
-- H-000001..H-000108 reserved for Owner/Super Admin; sequence starts at H-000109 (C30)

-- Hostile Review Fix #2: Vault Uploads Default to PENDING_HR_REVIEW; Food Stations Require VALID Medical
ALTER TABLE people_doc_vault ALTER COLUMN verification_status SET DEFAULT 'PENDING_HR_REVIEW';
ALTER TABLE staff_roster_assignments ADD COLUMN IF NOT EXISTS medical_verified_valid_bool BOOLEAN NOT NULL DEFAULT FALSE;
ALTER TABLE staff_roster_assignments ADD CONSTRAINT check_food_station_requires_valid_medical
    CHECK (station_key NOT IN ('ESPRESSO','PASTRY_FINISH','FOH_COUNTER','BOH_CONTINENTAL') OR medical_verified_valid_bool = TRUE);

-- Hostile Review Fix #3: GiST Range Exclusion on Temporary Loans (Prevents Double-Booking by Cover Finder)
ALTER TABLE staff_inter_outlet_loans ADD CONSTRAINT exclude_overlapping_temp_loans
    EXCLUDE USING gist (person_id WITH =, tstzrange(starts_at, ends_at) WITH &&)
    WHERE (state IN ('REQUESTED','APPROVED_ACTIVE'));

-- Hostile Review Fix #4: Block Permanent Transfer Completion While Active/Future Temp Loans Exist
ALTER TABLE people_transfer_requests ADD COLUMN IF NOT EXISTS no_active_temp_loans_verified BOOLEAN NOT NULL DEFAULT FALSE;
ALTER TABLE people_transfer_requests ADD CONSTRAINT check_no_temp_loans_on_perm_cutover
    CHECK (state <> 'COMPLETED_ACTIVE' OR no_active_temp_loans_verified = TRUE);

-- Hostile Review Fix #5: Aggregate EMI <= 25% Gross & Reconciled Ledger Zero-Balance for Offboarding Gate 4
ALTER TABLE people_offboarding_cases ADD COLUMN IF NOT EXISTS gate3_reassignment_map_json JSONB NOT NULL DEFAULT '{}'::jsonb;
ALTER TABLE people_offboarding_cases ADD COLUMN IF NOT EXISTS gate4_reconciled_ledger_zero_bool BOOLEAN NOT NULL DEFAULT FALSE;


-- =============================================================================
-- G1 DESIGN GATE OWNER SIGN-OFF LOCK (2026-10-22 22:39 IST & 22:57 IST · 100% APP 0 -> APP 6 LOCKED)
-- =============================================================================
-- A2: Outlet Manager / Cluster Manager approves Shift Swaps & Inter-Outlet Loans with automatic visibility/notification to City Head
ALTER TABLE staff_shift_rosters
  ADD COLUMN IF NOT EXISTS swap_approved_by_id VARCHAR(32) REFERENCES users(id),
  ADD COLUMN IF NOT EXISTS swap_approved_by_role VARCHAR(32) CHECK (swap_approved_by_role IN ('outlet_manager', 'cluster_manager')),
  ADD COLUMN IF NOT EXISTS city_head_notified_at TIMESTAMPTZ,
  ADD COLUMN IF NOT EXISTS visible_to_city_head_bool BOOLEAN NOT NULL DEFAULT TRUE;

ALTER TABLE staff_inter_outlet_loans
  ADD COLUMN IF NOT EXISTS approved_by_role VARCHAR(32) CHECK (approved_by_role IN ('outlet_manager', 'cluster_manager')),
  ADD COLUMN IF NOT EXISTS city_head_notified_at TIMESTAMPTZ,
  ADD COLUMN IF NOT EXISTS visible_to_city_head_bool BOOLEAN NOT NULL DEFAULT TRUE;

-- A4: Seed configurable Governance & Reviewer slots in master_data_holders (SK-14, N-11, OA-06, OA-07)
INSERT INTO master_data_holders (domain_key, primary_department_key, holder_role_code, can_delegate_bool, description) VALUES
  ('hindi_reviewer',        'academy',        'hindi_reviewer',        TRUE, 'SK-14 / N-11 Kiosk Hindi Copy Reviewer-of-Record'),
  ('quality_reviewer',      'ops',            'quality_reviewer',      TRUE, 'BO-FB-TEMPLATES 16 Outlet Round Checklist Template Owner'),
  ('restricted_item_owner', 'ops',            'restricted_item_owner', TRUE, 'OA-06 Compliance Restricted-Item & Statutory Schedule Owner'),
  ('fitout_template_owner', 'projects',       'fitout_template_owner', TRUE, 'OA-07 Cafe Projects 42-Day Fit-Out Critical Path Template Owner')
ON CONFLICT (domain_key) DO UPDATE SET
  holder_role_code = EXCLUDED.holder_role_code,
  description = EXCLUDED.description;
```


</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 |
| :--- | :--- | :--- | :--- |
| `EPIC-CONFIG-ADMIN-PEOPLE-OUTLET.md (C36–C51 & E1–E6)` | 5-Tier Authority + Single-Trip Onboarding + CSV Dry-Run -> APPLY + E1–E6 Trap Killers | `hop.people + hop.user_assignments + people_onboarding_cases` | **100% SYNTHESIZED** |
| `INTAKE-T1-11 & CONTRACT-T1-11-CAFE-PEOPLE-PRESENCE-MODULE.md` | 6 Pillars: Presence Radar, Shift A/B/C/Split Roster, Temp Loans, Single Person Passport, Cover Finder, DPDP Dignity | `outlet_shifts + staff_roster_assignments + staff_presence_events + staff_skill_passports` | **100% SYNTHESIZED** |
| `PEOPLE-MODULE-DESIGN.md (PEO1–PEO6) & Full HR Lifecycle` | 6-Category S3 Doc Vault, Permanent 4-State Transfers, 5-Gate Offboarding & <=25% EMI Staff Loans | `people_doc_vault + people_transfer_requests + people_offboarding_cases + people_loans` | **100% SYNTHESIZED** |

**Verification Evidence:** `pytest tests/unit/test_t1_11_people_presence_mobility.py` + `tests/test_people_hr_lifecycle.py` (32 fail-first tests) + Playwright `J19` 8-frame storyboard — 100% green across Manager/HR onboarding, 6-category doc vault, Medical `EXPIRED` food-station hard block, `derive_presence()` truth table, Temporary Loan vs Permanent Transfer isolation, `<=25%` EMI cap, and 5-Gate Offboarding FnF Lien lock.

</details>