Core Board Library - Senior Full-Stack Developer

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 v1.2 (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 overridden. Non-closure and Coverage-Not-Met surface on the Board as deterministic exceptions. 4A.6 Audit (Immutable) Every Program action records Created By, Modified By, Published By, Generated By Engine, Completed By, and Verified By. These write to the existing shared audit_logs spine (which carries immutability triggers) — not a new Program-specific log. 4A.7 AI Doctrine AI may suggest coverage risks, predict misses, and summarize status. AI may NOT generate execution records, mark coverage complete, close Programs, publish Programs, or assign accountability. PDEE runs fully with AI disabled. 4A.8 Studio On-Ramp (Program Authoring) — forward-compatible PDEE is designed to accept Programs authored through Ops Studio as a prompt-first on-ramp: a user describes an obligation in natural language (e.g., “quarterly fire-extinguisher inspection, every extinguisher, all properties”) and Studio drafts the Program definition — cadence, coverage, eligibility, template — as a Draft in Library under the existing Draft-only on-ramp contract (3.3). A human reviews and publishes; PDEE then runs it deterministically. Studio drafts the policy; it never runs the engine, generates work, or closes a loop. This preserves the execution boundary and the run-with-AI-disabled doctrine. The Studio authoring build itself is separate work; this scope only guarantees PDEE/Library accept such drafts through the standard contract. 5. SHARED GOVERNANCE & ARCHITECTURE RULES (MANDATORY) • Reuse existing shared layers — governance, lifecycle, permissions, recurrence, audit, isolation, reporting — wherever compatible. • No isolated or parallel subsystems where a shared operational architecture layer already exists. • All restrictions, permissions, and isolation enforce server-side before behavior, never UI- only. • All governance-relevant actions generate immutable audit records; no parallel logging systems. • The platform must run fully with AI disabled; AI is advisory and never writes the record or executes. • Must integrate into the existing CodeIgniter monolith and preserve migration compatibility. 6. SECURITY & TENANT ISOLATION • All Library objects and Board views are hotel/tenant-isolated; no cross-tenant exposure. • Hotel context resolves from the active session/assignment server-side — never from client input. • Permissions are role-aware and enforced server-side at the data layer. • Immutable audit and provenance preserved across the object lifecycle. 6A. CODE-VERIFIED REUSE & DEPENDENCY STATE What already exists in the codebase and MUST be consumed rather than rebuilt (verified against the repo): • Lifecycle: Template Builder draft→review→publish lifecycle exists and is the authority — reuse it; do not create a parallel publishing path. • Tenant isolation / identity: Foundations provides hotel context, roles, assignments (recently audited) — reuse it. • Audit: a general audit_logs table exists WITH immutability triggers. Write provenance/audit to that shared spine. Do NOT add another audit/log table. (Several module logs — AI usage, AI settings, inventory, WebRTC, key-log — still exist alongside it; consolidating them onto audit_logs is a planned foundational project.) • Recurrence: there is no unified recurrence engine, but a cron runner (cron_job) exists and some objects carry a frequency field. Design recurrence to a shared interface built on the existing cron runner; do not invent a parallel scheduler. • Execution truth: Board reads from Agenda’s single consolidated execution record (Agenda Phase 3 collapses the legacy parallel paths — PMP/checklist, agendaprogress, templatesubmissions — into one). Board must not read the legacy paths. • Inventory: the existing inventory subsystem is the backbone — reuse it; wire housekeeping’s inventory_option hook into it. • Key log: already part-wired to Agenda (key_log_agenda_executions) — keep/extend that integration rather than building anew. 7. MILESTONES (INDEPENDENTLY GATEABLE) Project Core is one workstream, one shared object model. Each milestone closes independently and is acceptance-gated; approval of one does not guarantee continuation. Milestone 1 — Shared Operational Object Model + Library Foundation • define and implement the shared object model • Library object storage across all operational types • tenant isolation + server-side permissions foundation • lifecycle state model (draft→review→publish→supersede/archive) Milestone 2 — Library Lifecycle, Contracts & Provenance • draft→publish lifecycle enforcement • on-ramp write contracts (Studio / Import / Conversion → Draft only) • read contracts for Agenda / Board • immutable versioning, supersession, provenance/lineage • retrieval by type/status/targeting/relationship Milestone 3 — Board Visibility, Exceptions & Statistics • live operational status surfacing from real execution records • exception capture & surfacing across the full taxonomy • exception triage/routing (action remains in execution systems) • operational statistics & trends from real data only, with drill-down Milestone 4 — Role-Adaptive Presentation, QA & Governance Hardening • role-adaptive Board presentation (exec / manager / frontline) • permission + isolation validation across Library and Board • provenance / audit validation • governance audit remediation and production hardening • documentation + architecture summary PDEE Engine Track (gated; starts after M1 Library foundation + Agenda Phase 3) The PDEE engine is a distinct, independently-gateable track. It does not start until the shared object model + Library foundation (M1) are in place and Agenda Phase 3 has consolidated the single execution record it generates into. It may run as a track inside Project Core or be spun out as a separate “Phase 3.5” engagement — see Decisions to Confirm. Milestone P1 — Program Object Model & Builder • Program schema on the shared object model • Program Builder in Library • lifecycle integration (reuse existing draft→publish) • Library integration (definitions, versions, history, attachments) Milestone P2 — Cadence & Eligibility Engine • deterministic generation engine on the existing cron runner • cadence/scheduling logic • eligibility logic resolved against Foundations • Agenda work generation Milestone P3 — Coverage & Closure Engine • coverage rule calculations from execution records • closure state logic • escalation logic Milestone P4 — Board Visibility & Reporting • Program dashboards & health • coverage reporting • trend reporting • drill-down Program → Coverage → Execution Records Milestone P5 — QA, Hardening & Governance • audit validation against the shared audit_logs spine • multi-hotel validation • security testing • documentation 8. ACCEPTANCE CRITERIA • a single shared operational object model is implemented and reused by Library and Board (no per-surface re-implementation) • objects flow Library → Agenda → Board preserving identity, lifecycle, targeting, permissions, and audit • Library enforces one lifecycle with no parallel publishing path • no object is executable before publish; on-ramps write Drafts only • Board surfaces the full exception taxonomy from real records with no silent drops • all Board statistics derive from real execution data — no mock or static metrics • role-adaptive presentation enforced server-side; no cross-tenant leakage • immutable provenance/audit preserved; no parallel governance, audit, or logging systems • system functions with AI disabled 9. EXPLICIT EXCLUSIONS (HARD LOCKS) • no parallel object store, lifecycle, governance, recurrence, audit, permission, or reporting systems • Board may not become a direct execution runtime surface • no autonomous publishing, assignment, or operational enforcement • no simulated, static, or placeholder statistics/telemetry • no client-supplied tenant/hotel context • no cross-hotel intelligence or cross-tenant visibility • AI may not write the published record or execute 10. DECISIONS TO CONFIRM Two forks are scoped with a default; confirm or flip: • Board action scope (defaulted to: surface + triage + route only; resolution happens in Agenda). If Board should allow limited in-place actions (e.g., acknowledge/close an exception), that must be added explicitly and still route through governed execution — not a parallel engine. • Library object-type set (defaulted to the full operational set above). Confirm the exact types in scope for v1 vs. reserved for later, so no unsupported type is silently accepted. • PDEE packaging (defaulted to: included here as a gated engine track). Decide whether to keep PDEE as a track inside Project Core or spin it out as a separate “Phase 3.5” engagement. Recommendation: spin out if keeping Library & Board independently closeable matters; keep unified if one developer/context is the priority. Either way, PDEE starts only after the Library foundation + Agenda Phase 3. • Programs naming (PDEE = engine; “Programs” = user-facing term). Confirm both terms; “PDEE” was the engine name from