Playbooks for Hotels — Declarative Hotel Operations

Status: Product Specification
Sources: Sovereign OS Playbook Architecture: Common Business Workflows, Comprehensive Business Processes Specification, Playbook Catalog — Full Detail for Every Playbook, D-03 — Jijibora Playbook Designs (developer), AGENTS.md — Sovereign OS / Cosmic Circuit mandates 3 & 4

1. Playbook Philosophy for Hotels

Hotel standard operating procedures (SOPs) are expressed as declarative playbooks — versioned YAML specs stored in NATS JetStream KV (SOVEREIGN_SCENARIOS) — not as hardcoded application logic. Each playbook binds strictly to canonical primitives (claim, truth_node, truth_edge, resource, resource_edge, integration_entity) with zero bespoke tables.

A hotel playbook declares:

1. Canonical schema bindings — which CNS types and claim traits the playbook touches
2. Execution & state gates — Kestra (:8180) macro-DAGs for multi-day flows, Apache Camel (:8181) micro-integrations for real-time steps, PoCE cryptographic sessions for sign-offs
3. External mediation — bidirectional sync to PMS, ERPNext, OpenMAINT, Plane, Synapse via integration_entity mirrors
4. Declarative UI schemas — forms, checklist cards, approval modals rendered dynamically (UI Bolt-On Guide & Declarative Component Blueprints)

2. Hotel Playbook Catalog

3. Playbook H-1 — Reservation & Folio Lifecycle (Front Desk)

Use & purpose: Capture a reservation, bind it to a room resource, build the folio line-by-line, and close out at check-out with payment settlement.

Who uses it: Front desk agents, night auditor, revenue manager, cashier.

Flow:

1. Guest reservation arrives (PMS webhook → Camel → cns://claim/type/hotel/reservation claim created, traits [booking_confirmed, poce_governed])
2. Room resource reserved via truth_edge guest→occupies→room (lease-backed, time-bounded)
3. Folio lines posted as cns://claim/type/hotel/folio_line claims (room charge, F&B, minibar, incidentals)
4. Budget threshold evaluated against resource:budget_front_office (declarative lookup lookup.claims.threshold.v1)
5. Dual-custody approval gate for folio adjustments above tier (PoCE session, fn::poce::record_step)
6. Check-out: settlement claim finalized via fn::poce::finalize_session, ERPNext invoice mirror written via integration_entity (system: "erpnext")
7. Room lease released; truth_edge occupancy ended; housekeeping task auto-triggered (H-2)

Guard rails: No auto-charge without folio evidence; no check-out without PoCE finalize; no rate change without named approver; PMS remains SoR for fiscal reservation details, Sovereign for operational state.

Evidence & rollout: Reservation claim, folio lines, PoCE receipt, ERPNext invoice ref. Version 1.0.0. Soft-first.

4. Playbook H-2 — Housekeeping Task & Turnover

Use & purpose: Turn a departed room into a clean, inspectable room; track attendant, checklist, and sign-off.

Who uses it: Housekeeping supervisors, room attendants, inspectors.

Flow:

1. Departure event (from H-1 occupancy end) triggers cns://workflow/task claim housekeeping_HK-{room}
2. Task bound to room resource and assigned attendant via truth_edge
3. Attendant works checklist (linens, amenities, sanitization); records photo evidence to MinIO (SHA-256 in claim.evidence)
4. Inspector sign-off via SoD (separation of duties: inspector ≠ cleaner; lookup.claims.sod.v1)
5. fn::poce::record_step for clean-sign-off; room status → READY; new occupancy lease can bind
6. Real-time status streamed to front desk via NATS WebSocket (workflow.{property}.housekeeping.*)

Guard rails: No auto-mark-clean without inspector sign-off; no room released to new guest while task OPEN; no invented checklist items (bind from lookup.claims.checklist.v1).

Evidence & rollout: Task claim, photo hashes, inspector sign-off, PoCE receipt. Soft-first.

5. Playbook H-3 — Maintenance & Work Order (Engineering)

Use & purpose: Fault report → inspection claim → OpenMAINT work order → technician dispatch → spare-parts deduction → close with expert sign-off.

Who uses it: Engineering supervisors, technicians, vendors, front desk (fault intake from guests).

Flow:

1. Fault submitted as cns://claim/type/hotel/incident (or cns://operations/incident) with photo evidence (MinIO)
2. Camel transforms claim into OpenMAINT card (openmaint.v1.cmd.workorder.create); WO id stored in integration_entity (system: "openmaint")
3. OpenMAINT schedules technician; status syncs back over NATS to the task claim
4. Technician completes work, logs parts consumed; spare parts deducted from resource:budget_maintenance
5. Expert sign-off mandatory (SoD); fn::poce::finalize_session; work order closed
6. Recurring preventive maintenance scheduled as recurring cns://operations/work_order claims

Guard rails: No auto-close without expert sign-off; no parts deduction without work-order close; OpenMAINT owns asset spec/depreciation, Sovereign owns booking availability and sign-off (conflict matrix in Integration Matrix & System Adapters Specification §3).

Evidence & rollout: Incident claim, OpenMAINT WO ref, parts log, sign-off, PoCE receipt. Soft-first.

6. Playbook H-4 — Procurement & F&B Requisition

Use & purpose: Assemble purchasing requisitions (F&B supplies, amenities, linens), route by budget threshold, multi-tier cryptographic approval, sync PO to ERPNext.

Who uses it: Procurement officer, F&B manager, executive chef, finance director.

Flow:

1. Requisition claim cns://workflow/requisition with line items, currency, cost center, urgency
2. Declarative threshold policy (lookup.claims.threshold.v1 / .procurement.v1) computes approval tier (TIER_1_AUTO / TIER_2_MANAGEMENT / TIER_3_EXECUTIVE)
3. Dual-custody approval via PoCE (fn::poce::record_step per signer)
4. Approved requisition → Camel → ERPNext POST /api/resource/Purchase Order (idempotency key = requisition id); PO number stored in integration_entity
5. Goods receipt matched to PO; three-way match (PO, receipt, invoice) before payment release
6. Solver-gateway optional: procurement.basket_split@1 (branch_and_bound) to split F&B basket across vendors for least cost — proposes only; buyer disposes

Guard rails: No PO without PoCE-approved requisition; no synthetic vendor IDs; ERPNext owns fiscal GL/tax; Sovereign owns approval state. Fail closed if ERPNext unreachable (502).

Evidence & rollout: Requisition claim, approval signatures, ERPNext PO ref, three-way match, PoCE receipt. Soft-first.

7. Playbook H-5 — Event & Banquet Booking

Use & purpose: Book function spaces, set F&B minimums, manage event lifecycle from inquiry to post-event settlement.

Who uses it: Events manager, banquet chef, clients, finance.

Flow:

1. Event claim cns://claim/type/hotel/event (function space, dates, F&B minimum, AV needs, guest count)
2. Space resource reserved via time-bounded lease (no double-booking)
3. Milestone approvals (menu sign-off, BEO, deposit) as PoCE steps
4. Event execution; consumption logged to folio lines (H-1)
5. Post-event settlement; escrow release if group/corporate contract (federated PoCE if client is a separate org)

Guard rails: No space double-booking (lease conflict check); no event start without deposit confirmation; no auto-cancellation.

Evidence & rollout: Event claim, lease binding, milestone PoCE steps, settlement receipt. Soft-first.

8. Playbook H-6 — Event Design / Mood Board

Use & purpose: Curate visual direction for events (layout, color palette, floral, AV); export presentation-grade PDF for client sign-off.

Who uses it: Events team, clients, designers.

Flow:

1. Mood board claim cns://creative/mood_board with pinned assets (MinIO URLs + SHA-256)
2. Client annotations and approval gate
3. Camel /services/playbook/moodboard/{board_id}/export-pdf via Gotenberg (:3094) → signed PDF
4. PDF stored in MinIO; hash recorded on claim; client sign-off as PoCE step

Guard rails: No asset pinned without SHA-256 integrity; no export without board claim.

Evidence & rollout: Mood board claim, asset hashes, exported PDF ref, client sign-off. Soft-first.

9. Playbook H-7 — Staff Communication & Discussion

Use & purpose: Real-time, E2E-encrypted staff discussion rooms bound to operational threads; promote discussions to formal proposals.

Who uses it: All hotel staff, department heads.

Flow:

1. Discussion thread claim cns://collaboration/discussion → Synapse Matrix room (!room_id:hotel.local)
2. integration_entity mirror (system: "synapse", external_id: room_id)
3. Inbound Matrix messages mirrored back as cns://collaboration/discussion_comment claims (cryptographic provenance)
4. Moderator "Promote to Formal Proposal" → governance proposal claim (community governance s165)

Guard rails: Synapse is real-time transport; Sovereign is authoritative record. No governance decision from chat alone.

Evidence & rollout: Discussion claim, room mirror, comment claims, promotion receipt. Soft-first.

10. Playbook H-8 — Incident & Security Report

Use & purpose: Log security/safety incidents (theft, injury, property damage); escalate ladder; preserve evidence for audit/insurance.

Who uses it: Security staff, front desk, GMs, insurers.

Flow:

1. Incident claim cns://claim/type/hotel/incident with location, severity, reporter, photo evidence
2. Escalation ladder: property security desk → GM → regional safety office (human approval at each step; no auto-fine, no auto-lockout)
3. PoCE records each escalation step
4. Insurance packet exported (Gotenberg PDF) with evidence hashes

Guard rails: No auto-fine; no auto-publish; human approval required for escalation; no invented severity scores.

Evidence & rollout: Incident claim, escalation receipts, evidence hashes, export packet. Soft-first.

11. Playbook H-9 — Group Procurement (Multi-Property Federation)

Use & purpose: Hotel group aggregates F&B/amenity demand across properties for volume pricing; federated escrow release on delivery verification.

Who uses it: Group procurement, property procurement officers, suppliers.

Flow:

1. Federated requisition claim cns://federation/procurement with is_federated: true
2. Bound to peer property scopes via record_federation_binding (s184)
3. Each property signs allocation quota with BBS+ key (selective disclosure — no internal margin leakage)
4. Shared PoCE escrow session; supplier payment released only on multi-property delivery verification

Guard rails: Authority verdict required before award; missing verdict blocks award; no autonomous escrow release.

Evidence & rollout: Federated claim, federation bindings, BBS+ signatures, PoCE escrow receipt. See Cross-Organization Federation & Federated PoCE Specification.

12. Playbook H-10 — Guest Identity & Access

Use & purpose: Unified guest/staff identity with APF role-based access, BBS+ selective disclosure for age/nationality proofs, Keycloak anchoring.

Who uses it: Front desk, security, IT, compliance.

Flow:

1. Identity truth_node (cns://truth/node/person) linked to Keycloak DID
2. APF (s230) resolves effective permissions per role per property (front desk agent vs. housekeeping vs. manager)
3. BBS+ credential: guest proves age/nationality without surrendering full ID document
4. Access grants logged to PoCE for audit

Guard rails: No credential without Keycloak anchoring; no access beyond resolved APF permissions; no PHI custody (non-goal per Jijibora D-01 §7).

Evidence & rollout: Identity claim, APF resolution, BBS+ proof receipts. Soft-first.

13. Authoring the Next Hotel Playbook (Recipe)

Derived from D-03 — Jijibora Playbook Designs (developer):

1. Reuse the spine, add nothing new. Consume platform.criteria.v1.* subjects; emit platform.criteria.v1.match.fired with inherit_causation: true. No second bus, no second envelope.
2. Copy the rule JSON shape. Fields: rule_id, name, domain, enabled, version, description, runtime{tier,engine,chain}, pipeline{id,stage,max_depth,terminal}, inputs[]{stream,filter}, evaluation{kind,engine,key_by}, outputs[]{on_match|on_feasible|on_breach}, side_effects{handled_by} (terminal-only actuation).
3. Declare the pack in dictionary.v1.json first: emits/consumes/enrichment/solver_stages/security_bound per pack.
4. Declare every lookup in NATS KV with canonical_subject, canonical_event_type, pipeline_id.
5. Declare all side effects in NATS KV — never inline imperative SQL in route handlers.
6. If it cannot be expressed as a fragment/config/lookup, stop and ask before writing code (AGENTS.md — Sovereign OS / Cosmic Circuit mandate 3).