Description
Summary Please Review the attached scope & milestone agreement if interest please send any questions. Thanks. PROJECT CORE — LIBRARY & BOARD Operational System of Record, Operational Visibility Surface & Policy-Driven Execution Engine — Scope (Finalized, code-verified; Programs/PDEE layered in) System: HotelHub / OperationsHub Framework: PHP CodeIgniter 3.x (Existing Monolith) Scope Type: Core Platform / Spine Completion Dependencies • Foundations Hierarchy Architecture (hotel context, identity, permissions, isolation, time zone) • Agenda Architecture (execution surface) • Template Builder Lifecycle (draft / review / publish) • Shared Operational Object Model Doctrine • Existing AI Intelligence Layer (advisory only) 1. PURPOSE & ARCHITECTURAL POSITION Library and Board complete the operational spine of HotelHub: Library → Agenda → Board. Library is the operational system of record. Agenda is the execution surface. Board is the operational visibility and exception surface. These are not standalone modules and may not be built as such. They are connected surfaces over a single shared operational object model. An operational object must flow Library → Agenda → Board carrying the same identity, lifecycle state, targeting, permissions, tenant scope, and immutable audit history at every stage. This scope completes that spine while preserving the platform’s existing governance, lifecycle, isolation, and execution-boundary doctrine. 2. SHARED OPERATIONAL OBJECT MODEL (FOUNDATION — NON- NEGOTIABLE) Library and Board MUST be built on a single shared operational object model. This model is the connective tissue of the platform and must be defined once and reused by Library, Agenda, and Board. It may not be re-implemented per surface. Every operational object must carry, as shared attributes: • stable object identity (UUID + human-readable reference ID) • object type (SOP, checklist, inspection, PM workflow, log, recurring Program, directive, reference object, one-time / recurring task) • lifecycle state (draft, in review, published, superseded, archived) • tenant scope (hotel_id / organization_id, enforced server-side) • targeting metadata (portfolio / property / department / role / position) • permissions and visibility rules • relationship links (parent-child, dependency, supersession, Program-linked, reference- linked) • immutable provenance and lineage (creator, modifier, approver, deployment authority, version history) • audit history Behavioral differences between object types must be expressed as overlays on this shared model, not as isolated systems with their own governance, recurrence, permission, audit, or lifecycle logic. 3. LIBRARY — OPERATIONAL SYSTEM OF RECORD Library is the single canonical home for all operational objects. It is not a passive document store and not a per-tool catchall; it is the system of record that every other surface reads from and writes into. 3.1 Object Storage & Types Library MUST store all operational object types in the shared object model. No operational object type may maintain a separate, isolated store outside Library where Library compatibility is possible. Object types include: • SOPs, checklists, inspection workflows, PM workflows • operational logs (including lost & found) • templates (Template Builder remains schema/lifecycle authority) • Programs (push + guaranteed deterministic closure across properties — see 3.6) • operational directives and reference objects • one-time and recurring tasks • inventory objects (the existing inventory subsystem is the backbone — see 3.7) 3.2 Lifecycle (MANDATORY) All objects move through the existing governed lifecycle: • Draft → Review → Publish → (Supersede / Archive) No object becomes executable until published. No surface may bypass this lifecycle. There is one lifecycle, shared with Template Builder — no parallel publishing system. 3.3 On-Ramp & Read Contracts • Studio, Import, and Conversion write into Library as Drafts only — never as published or executable objects. • Agenda reads published objects from Library for execution. • Board reads object and execution state for visibility — it does not own the record. • AI may assist authoring/structuring but never writes the published record and never publishes. The system must function fully with AI disabled. 3.4 Versioning, Provenance & Lineage • Re-import or revision creates a new immutable version; it never overwrites a published object. • Supersession relationships are preserved and traceable. • Provenance (who created / modified / approved / published) is immutable where governance requires. 3.5 Isolation, Permissions & Retrieval • All Library access is hotel/tenant-isolated and enforced server-side — no cross-tenant visibility. • Visibility and edit rights are role-aware and permission-enforced server-side (UI restriction alone is insufficient). • Objects are retrievable by type, status, targeting, and relationship for reuse across the platform. 3.6 Programs & Program Builder (Library side of PDEE) “Programs” is the user-facing term; the engine beneath them is the Policy-Driven Execution Engine (PDEE) defined in Section 4A. Deep Clean, fire extinguishers, backflow, pool logs, brand audits, preventive maintenance, vehicle inspections, asset verification — all are Programs powered by one engine. Users do not create tasks; they create Programs, and the engine generates the governed work. Library gains a Program Builder. A Program is a governed operational policy carrying: name, description, program type, attached form/template, cadence, coverage rules, targeting rules, eligibility rules, closure rules, escalation rules, visibility rules. • Program Builder supports: create, edit draft, review, publish, supersede, archive — using the existing Library lifecycle (no separate publishing system). • Library stores Program definitions, versions, history, attachments, and templates as shared operational objects. • Programs are authored manually in Program Builder, and may also be drafted via on- ramps (Studio / Import) under the Draft-only contract in 3.3 — see 4A.8. • Closure is deterministic and rule-driven; non-closure surfaces on the Board as an exception. AI is advisory only and never generates, closes, or publishes (see 4A.7). 3.7 Inventory (Existing Backbone) • Inventory is the most complete existing subsystem (items with asset flag, serial, barcode, cost, par/reorder; counts, adjustments, audit logs). It is reused, not rebuilt. • An inventory list = an operational object versioned in the Library; an inventory count/check = a (recurring) Agenda task. • The housekeeping checklist already carries an inventory hook (inventory_option); wiring it so daily room cleaning feeds a live inventory enables portfolio FF&E/asset visibility. 4. BOARD — OPERATIONAL VISIBILITY & EXCEPTION SURFACE Board is where the organization sees operational reality: what is being executed, what is failing or pending, and the operational statistics that matter. Board surfaces and routes; it does not execute. Execution runtime behavior remains in Agenda and the governed execution systems. 4.1 Exit States & Exception Surfacing (CORE) HotelHub is a closed-loop execution engine: every task that enters the system must exit with a documented, immutable state. Board surfaces those states, reading from Agenda’s single consolidated execution record (the one execution truth established by Agenda Phase 3 — not the legacy parallel paths). Documented exit states: • Completed • Exception • Passed to Next Shift • Skipped / N-A • Incomplete • Escalated Board MUST also surface Program coverage: per-property closure, and any property that did not close the loop as a deterministic exception. Exceptions are captured from real execution records — never inferred or fabricated. No exception may be silently dropped. Each surfaced item links back to its source operational object and execution record for full traceability. 4.2 Exception Triage & Routing • Board may surface, filter, group, and route exceptions to the appropriate role/owner for resolution. • Resolution / completion actions occur in the governed execution systems (Agenda), not as a parallel execution engine inside Board. • Routing and escalation visibility must respect role and tenant scope. 4.3 Operational Statistics & Visibility Board MUST present operational statistics derived from real execution data only — no simulated, static, or placeholder metrics. Required visibility includes: • completion / closure status across operational objects • open vs. resolved exceptions, by taxonomy category • trends over time (completion, exceptions, escalations) • visibility by property, department, role, and position • drill-down from any statistic to the underlying execution record 4.4 Role-Adaptive Presentation • Board presentation adapts to role: executives see restricted/rolled-up visibility; managers/MOD see operational detail; frontline sees only what their role permits. • Presentation differences are visibility overlays on the shared model — not separate data pipelines. • All views remain tenant-isolated and permission-enforced server-side. 4.5 Execution Boundary (NON-NEGOTIABLE) Board may not become a direct execution runtime surface. Task completion, execution tracking, verification, and enforcement remain in Agenda / Board execution systems / Programs. Board reads and routes; it does not absorb execution responsibility. 4.6 Program / PDEE Visibility Board is the compliance surface for Programs. It MUST display, from real execution records only: • Program Health, Coverage %, Open Exceptions, Overdue Programs, Upcoming Programs, Program Trends • drill-down path: Program → Coverage → Execution Records • coverage and closure status are read from the engine’s rule-calculated state — never recomputed or overridden in Board 4A. POLICY-DRIVEN EXECUTION ENGINE (PDEE) PDEE is the operational automation engine that converts policy, cadence, and coverage requirements into deterministic operational execution. It reads published Programs from Library, generates governed work into Agenda, and feeds closure/coverage state to Board. Its purpose is singular: operational obligations cannot be forgotten, skipped, or silently disappear. PDEE is deterministic end-to-end — no AI in any generation, coverage, or closure decision. Architectural placement: PDEE sits between Library (where Programs are defined) and Agenda (where work executes). It introduces no parallel object store, lifecycle, audit, or scheduler; it builds on the shared object model, the existing Library lifecycle, the existing cron runner, and the shared audit_logs spine. 4A.1 Cadence Engine Supported cadences: one-time, daily, weekly, monthly, quarterly, semiannual, annual, custom interval. Generation is deterministic; there is no AI scheduling. Built on the existing cron_job runner via a shared interface — not a new scheduler. 4A.2 Coverage Rule Engine Coverage rules define completion requirements: every room / floor / building / asset / fire extinguisher, percentage samples (e.g., 10%, 25%), randomized samples, or a custom target list. Coverage status is calculated by rules from execution records — never by AI, never manually set. 4A.3 Eligibility Engine Programs determine who may execute, by hotel, department, position, role, team, asset group, or location group. Only eligible users receive generated work. Eligibility resolves server-side against Foundations. 4A.4 Execution Generation Published Programs automatically generate Agenda work — tasks, inspections, logs, audits. Generated work inherits Program identity, hotel, department, template, cadence, and coverage requirement, plus its audit trail. All generated work executes entirely inside Agenda; Agenda remains the execution authority. 4A.5 Closure Engine Program closure states: Complete, Complete With Exceptions, In Progress, Coverage Not Met, Overdue, Escalated. Closure is calculated from execution records and is never manually overridd