Inventory P2 for Hotel Operations Platform (Fixed Scope, Not Greenfield)

PROJECT CORE — INVENTORY · PHASE 2 Universal Operational Inventory — Items, Counts, Movement, Variance, Valuation, Reporting & Portfolio Governance Phase 2 of the existing Inventory subsystem · builds on Library / Board / PDEE Scope v1.2 · HotelHub / OperationsHub · PHP CodeIgniter 3 Monolith Patent Pending · U.S. Provisional Application No. 64/013,207 THIS IS NOT A GREENFIELD PROJECT. A substantial inventory subsystem already exists in the codebase and is your starting point. You are extending and binding it onto the platform spine — not building it from scratch, and not rebuilding it. It already does real work: a count engine with a draft → in-progress → completed → approved lifecycle, variance and loss calculation, manual adjustments with before/after audit, multi-location stock, barcodes, item templates, and variance tolerances. Reuse all of it. Where to look: controllers inventory*, itemmaster; models inventory_*_model; migrations in db/inventory/ (001–016); the working logic in inventory_count_model and inventory_adjustment_model. Section 20 (Code-Verified Reuse) names exactly what exists, what to reuse, and what must be fixed. Read it before writing any code. 1. Purpose & Position Phase 2 turns the existing standalone inventory subsystem into a universal, governed inventory that serves consumables (food, amenities, chemicals), circulating goods (linen, uniforms), and serialized assets (FF&E, equipment) across a portfolio. It is the closed loop applied to stock: a catalog governed in the Library, a count executed on the Agenda, variance reconciled on the Board, a correction carried by Communications. This phase delivers a complete, flexible inventory in one pass — every facet hooked up, nothing left on one leg. The only things consciously left out are genuine seams to separate products (procurement, recipe-costing, accounting; Sections 17, 19). It rides the shared object model, the Library lifecycle, PDEE, the Agenda execution record, and the Board (Scope v1.2). It introduces no parallel store, engine, scheduler, or audit. Scope v1.2 §3.7 already states the governing equations: an inventory list is a versioned Library object; a count is a (recurring) Agenda task. 2. Guiding Principles • One object, many behaviors. Food, linen, and FF&E are not three modules — they are one shared inventory object with a mode overlay that changes how it depletes, what “on hand” means, what variance means, and how it is valued. • The catalog governs; the count moves stock. The Library holds what an item is and should be (par, cost, units, cadence, tolerances). Quantities change only through a count or correction on the Agenda. • Reuse, never duplicate. Tracking is an overlay on the shared model; cadence/coverage/closure are PDEE; execution is Agenda; visibility is Board; the record is the shared audit_logs spine. No parallel systems. • Everything is accountable. Every action — count, adjustment, movement, transfer, catalog edit, par change — is written to the shared audit spine with who, what, when, and before/after, and is surfaced where people look (Section 12). • Built on Foundations. Every object is scoped to the property through the assignment spine and tenant-isolated server-side. The system runs fully with AI disabled; Intelligence is advisory only and never moves stock, closes a count, or fires a trigger. 3. The Inventory Object on the Shared Model 3.1 Object types as Library objects Inventory objects live on the shared operational object model (v1.2 §2), carrying the same identity, lifecycle, tenant scope, targeting, permissions, relationships, provenance, and audit as any other object: the item / catalog (“inventory list”), the count Program, and the count record & adjustment. Versioned with immutable history; nothing overwrites a published version. 3.2 Inventory Mode — the universal abstraction The single decision that makes inventory universal and flexible. Each item carries a mode that changes its behavior across counting, valuation, and variance. The codebase carries the seed in the is_asset flag (inventory_items); Phase 2 elevates that binary into a small, deliberate typology — and stops there, so “universal” never sprawls into infinite item-types. • Consumable — food, amenities, chemicals. Depletes continuously; cost-of-goods and waste matter; expiry/shelf-life applies. Variance means shrinkage in dollars and spoilage. • Circulating — linen, uniforms, rotating china. Cycles (in-use → laundry → storage → lost/damaged); the shelf count is not the total owned. Variance means par loss across the circulation. • Asset / FF&E — furniture, equipment, electronics. Quantity is identity; tracked present/missing/condition by serial or tag; ties to depreciation and Preventive Maintenance (Section 14). Variance means missing or damaged units. 3.3 Tiering, portfolio assignment & inheritance Portfolio governance rides the Library tiering (Library Addendum §3.1–§3.3) — not a separate corporate module. A catalog or count Program authored once at the organization tier is assigned with a target — all properties · by brand · by region · by property type · by department · or an explicit hotel list — and resolved per user against the assignment spine and permissions. A regional user assigned to six properties counts and reports across those six; a single-hotel user sees only theirs; corporate sees the roll-up. • Mandatory / locked, adopt-as-is, adapt / override. The three inheritance relationships; on override, corporate retains visibility that a local version exists. Why it matters: because every property inherits the same versioned item object — not a retyped string — a portfolio total is a true sum, not a spreadsheet reconciliation. Shared item identity is the corporate tier, and it is the precondition for aggregation. 4. Units of Measure & Conversions F&B breaks without this. You buy a case of 24, stock bottles, use ounces. Today unit-of-measure is free-text and there is no pack-size column; case-pack scanning cannot compute. Phase 2 makes units real: a governed UOM reference (the legacy inventory_uoms dummy data is retired), purchase → stock → usage conversion factors, and pack-size on the item and on carton barcodes. 5. Valuation & Costing • Weighted-average costing + cost history. The pragmatic hospitality default, replacing the single mutable cost field. (Deeper FIFO/lot costing is available as a later option, not required for this phase.) • Value on hand & loss in dollars. Total inventory value on hand, food-cost %, and variance/loss in real currency — surfaced on the Board and in reporting (Sections 9–10). • Waste / spoilage reasons. A shortfall carries a reason — consumed, wasted, expired, transferred, broken, missing — so shrinkage analysis is real, not “stuff disappeared.” This also feeds the advisory Intelligence layer (Section 13). 6. Stock Movement & Reconciliation The inventory_restock and inventory_usage tables and models exist but are unwired. Phase 2 wires them into a perpetual book the count reconciles against: • Receive → transfer → consume → waste. A running book value, so on-hand is known between counts. • Count as reconciliation. The physical count is the truth that reconciles against book value; the difference is real variance. • Transfers, including inter-property. Move stock between storage locations and between properties (e.g., two pilot hotels). • Housekeeping depletion hook. Per v1.2 §3.7, wire the housekeeping checklist inventory_option hook so daily room cleaning depletes inventory and yields live amenity/FF&E visibility. 7. Counts as Programs (PDEE) & the Agenda Count Renderer A count is a Program governed by PDEE (v1.2 §4A): cadence (§4A.1 — one-time, daily, weekly, monthly, quarterly, cycle), coverage (§4A.2 — every location / every asset / sample %), eligibility (§4A.3), closure (§4A.5 — Complete / Coverage Not Met / Overdue). Recurring counts auto-generate; nobody builds a one-off count tool. PDEE generates the count into the Agenda. The Agenda count canvas is one dynamic surface with a pluggable count card chosen by mode/type — location grid (linen), category sheet with cost & expiry (F&B), scan stream (barcode), asset audit (FF&E), and cycle/spot. Constant chrome, different card. Visual direction: the Inventory Visual Direction deck. 8. Count Integrity (Audit-Grade) • Tolerance-driven variance. Use the existing inventory_variance_thresholds table: a variance past tolerance is flagged, routed, and can force a recount. • Count freeze / cutoff. An open count snapshots expected-on-hand at start; movement during the count does not corrupt it. • Blind count + auto-recount. Optional mode that hides the expected quantity so the counter cannot back-fill it; auto-recount when variance exceeds tolerance. • Approval & segregation of duties. Sign-off exists; enforce that the approver is distinct from the counter for valued counts. • Photo evidence. Capture a photo against a count line or exception (damaged asset, short shelf), using the Library media infrastructure — not a new store. • Camera & QR scanning. Counting supports phone-camera scanning alongside hardware scanners, resolving against the existing barcode index. QR asset tags can be generated and printed for FF&E, so one scan opens that asset’s record across inventory and Preventive Maintenance. The barcode store (inventory_item_barcodes) is type-agnostic; this is an input-method capability, not a schema change. 9. Variance, Shrinkage & the Board Roll-Up Variance resolves onto the Board through the exit-state and Program-coverage model already defined in v1.2 §4 and §4.6 — from real records only, no silent drops, each item linking back to its count record and item object. • Variance with memory. Signed Δ, % of par, tolerance state, trend, and repeat-offender detection. • Portfolio shrinkage roll-up. Upward visibility (Library Addendum §3.3): corporate sees shrinkage, coverage, and overrides across properties; outliers surface. • Reorder shortfalls routed. Below-reorder items surface and route to the GM / buyer; actionable once the procurement seam is wired (Section 17). 10. Reporting, Filters & Export Not a BI suite — queryable inventory with real flexibility on the back end. Live operational views (variance, shrinkage, coverage, value) surface on the Board; this is the filtered, exportable layer on top, reading the same real data — no second analytics engine. • Filters. By property, mode, category, location, status, variance, value, and date range. • Export. Counts, variances, valuation, and item history exportable (CSV) for finance, insurance, and audit. • Portfolio inventory view (read-only). A single above-property reporting screen for a corporate or regional user: see all assigned properties at once or pick one, and filter the rows dynamically — e.g., waste across the portfolio, then narrow to one hotel — without switching hotel by hotel. It reports on the roll-up; it does not push or command. Boundary. This is a read-only reporting view riding the roll-up in Section 9. The full above-property command surface — pushing standards down, managing Programs across properties — remains the Control Center, scoped separately (Library Addendum §3.3). 11. Alerts & Notifications Operational alerts fire through the existing notification rail as PDEE triggers — not a new alerter: below-reorder, count overdue, variance past tolerance, and expiry approaching. Routed by role and tenant scope. 12. Audit, History & Accountability Two layers — the record, and the view that surfaces it. • Complete audit record. Every inventory action — count, adjustment, movement, transfer, approval, catalog edit, par/reorder/tolerance/mode change — writes to the shared audit_logs spine with who, what, when, and before/after. One spine, no parallel inventory log (the adjustment model already does this; extend the pattern to everything). • Last-changed-by, visible. The last editor and timestamp show on the record itself — on the row, not buried — so a manager sees who touched a count or catalog entry last without digging. • Per-item history view. Open any item and see its full timeline: counted by whom and when, adjusted with reason, transferred, par changed, on what version. Operators and insurance both want this; the data is already on the immutable spine. 13. Intelligence Layer (Advisory) AI layered off the platform Control layer to observe and recommend — never to act. Inventory data flows back through the Control layer so it can be used for portfolio insights. Build the plumbing now (governed read access through the Control layer, and a place for recommendations to surface); enable the recommendation models deliberately, later. • Observe. Intelligence reads counts, variances, movement, and waste reasons to surface patterns — chronic short items, a par that is always wrong, spoilage trends, shrinkage outliers across the portfolio. • Recommend, advisory only. Surfaces suggestions to a human (e.g., “par looks low on King sheets,” “coffee short three months running”). It never adjusts a quantity, closes a count, or fires a reorder. The system runs fully with AI disabled. Note: layering the observe plumbing now is cheap and right. Hold the live recommendation models behind a deliberate enable, because suggesting reorder quantities or flagging shrinkage to a person is accuracy-and-liability territory that needs care. 14. FF&E / Asset Depth & the PM Tie A counted asset is the same asset that is serviced — one object, not two registers. Serialized asset record (serial/tag, condition, room/location assignment, acquisition cost & date, warranty, disposal); the asset object links to its Preventive-Maintenance workflow so servicing and verification share identity. Full PM program orchestration remains the PM module’s own work; Phase 2 establishes the shared asset object and the link, plus a clean export for insurance and capital audit. 15. In-Context Delivery & Role-Based Experience • Knowledge in their ear. A count’s instructions/SOP surface in-context inside the Agenda at count time (Library Addendum §9 pairing) — no new pipeline. • Role-adaptive views. Frontline counts assigned locations; supervisor sees the department; GM sees the property; corporate sees the portfolio roll-up. Enforced server-side via the assignment spine. 16. Data Import & Onboarding A new or pilot property must load its existing item list once — the difference between “demoable” and “deployable.” A clean import path for catalogs and opening quantities (CSV), validated against the governed catalog, so no one hand-enters 400 linens. 17. Reorder & Procurement Seam par_level and reorder_threshold exist and counts flag shortfalls; Phase 2 surfaces and routes them. It does not build a procurement suite. Mirroring the LMS decision (Library Addendum §15) — own the operational loop; integrate the commodity — vendor, purchase-order, and receiving are a clean integration seam to extend later. • Procurement (vendor / PO / receiving) and recipe-costing / menu engineering — separate products; defined integration seams, not built here. [SEAM] 18. Architecture, Reuse & Boundaries (Mandatory) • Tracking attributes are overlays on the shared operational object model (v1.2 §2) — not a separate store or schema. • All cadence, coverage, generation, closure, and alerts are PDEE (v1.2 §4A) — no parallel engine or scheduler. • Counts execute in Agenda; variance/exception surfaces on the Board — no parallel execution or visibility surface. • All records write to the shared audit_logs spine — no parallel log. • Settings live in the Library. Par, reorder, cadence, tolerances, and catalog definitions are governed Library objects authored and versioned there; inventory reads its configuration from the Library and does not own a settings module. • All access is tenant-isolated and permission-enforced server-side via the assignment spine — never client-supplied hotel context, never UI-only. Integrates into the existing CodeIgniter monolith; runs fully with AI disabled. 19. Explicit Exclusions (Hard Locks) • No parallel object store, lifecycle, trigger engine, scheduler, audit, or permission system. • No full procurement / purchase-order suite, no recipe-costing engine, no accounting/financial integration — integration seams only (Section 17). • Inventory does not become an execution runtime surface — execution remains in Agenda. • No client-supplied tenant/hotel context; no cross-tenant visibility. • No AI firing, completing, or closing a count, trigger, or coverage state; no autonomous reorder. 20. Code-Verified Reuse & Dependency State Verified against the develop branch. Reuse — do not rebuild: • Count engine & variance — inventory_count_model approves counts and writes quantities back; variance, variance_percent, loss_value computed (inventory_counts, inventory_count_items). • Adjustment write-back — inventory_adjustment_model updates inventory_item_locations.current_quantity with before/after audit (the accountability pattern to extend everywhere). • Locations, barcodes, templates, tolerances — inventory_item_locations, inventory_item_barcodes, inventory_templates, inventory_variance_thresholds present and usable. • Restock / usage — tables and models exist but are unwired; Section 6 wires them. Must be fixed as part of binding to the spine: • Tenancy — controllers key off session firm_id as hotel_id and ignore the active-hotel switcher; re-base onto the assignment spine. • Taxonomy collision — a legacy item_master dump defines a second inventory_categories table (id, category_name) colliding with the governed (category_id, hotel_id) schema; retire the duplicate, kill the Item Master menu. • Free-text governance — category and unit-of-measure are strings on inventory_items; make them governed references (Sections 3–4). Dependencies. Phase 2 rides the shared object model + Library foundation (v1.2 M1), the Agenda single consolidated execution record (Agenda Phase 3), and the PDEE engine; these are technical prerequisites for the dependent milestones. The decouple cleanup (retire item_master, free-text → governed) is independent of the spine. 21. Milestone Structure Phase 2 is one complete delivery, staged into independently-gateable milestones. Each milestone is independently evaluated for scope compliance, governance compatibility, quality, and stability before the next is authorized; completion of one milestone does not guarantee continuation. Sequence and price are negotiated separately (Section 23); no timeline is stated or implied here. Milestone IM1 — Foundation & Decoupling • Bind the item and count objects to the shared operational object model and the Library lifecycle. • Re-base tenancy from session firm_id onto the assignment spine; honor the active-hotel context. • Retire the item_master taxonomy collision and the duplicate Item Master menu. • Govern category and unit-of-measure (replace free-text); establish purchase → stock → usage conversions. • Catalog and opening-quantity import path. Milestone IM2 — Modes, Units & Valuation • Inventory mode typology (consumable / circulating / asset) governing count, valuation, and variance behavior. • Pack-size and unit conversions applied across counting and costing. • Weighted-average valuation with cost history and value-on-hand. • Waste / spoilage reason capture on shortfalls. Milestone IM3 — Movement, Counts & Integrity • Wire restock/usage into receive → transfer → consume → waste book value; the count reconciles against it; inter-location and inter-property transfers. • Counts as recurring PDEE Programs (cadence, coverage, eligibility, closure) generating governed Agenda work. • Agenda count renderer — one canvas, pluggable count cards (location grid, category sheet, scan stream, asset audit, cycle). • Count integrity: tolerance-driven variance, count freeze, blind count, auto-recount, segregation of duties; photo evidence. Depends on the PDEE engine and the Agenda single consolidated execution record (Agenda Phase 3). Milestone IM4 — Portfolio, Board, Reporting & Audit Views • Targeted inheritance and portfolio → multiple-hotel → single-hotel assignment by user and permission. • Variance and shrinkage roll-up on the Board; tolerance routing; alerts/notifications via PDEE. • Back-end reporting: filters and export over the real data. • Audit and history surfacing: last-changed-by on the record, and a per-item history timeline. Milestone IM5 — Intelligence, FF&E / PM, Frontend & Hardening • Advisory Intelligence plumbing — observe and recommend, ship-disabled; no autonomous action. • FF&E asset depth, the Preventive-Maintenance link, and insurance / capital export. • Frontend rebuild to the inventory visual direction. • Multi-hotel QA, permission and isolation validation, governance hardening, documentation. 22. Acceptance & Evidence Standard Acceptance of each milestone is determined solely by the Client. Every milestone requires deployment for review, a testing opportunity, an architecture/implementation summary, and a walkthrough before acceptance. For a deliverable to be accepted it must provide, and the Client must verify: • A deployed build on a review environment — not a local-only or screenshot demonstration. • Specific file / table / column evidence for every claimed deliverable: the structures exist, are wired, and behave as specified, demonstrated by reference to the code and schema — not by a functional demo alone. • An architecture/implementation summary and a walkthrough. A functional demonstration, screenshot, or verbal assurance, by itself, is not acceptance. A milestone is accepted only when it satisfies its deliverables and the criteria below: • Inventory objects live on the shared model (no parallel store) and flow Library → Agenda → Board preserving identity, lifecycle, targeting, permissions, and audit. • A catalog authored once at corporate inherits to targeted properties and is assignable portfolio → multiple hotels → single hotel by user and permission; portfolio totals are true sums. • Mode correctly changes the count card, valuation, and meaning of variance for consumable, circulating, and asset items. • UOM conversions compute purchase ↔ stock ↔ usage; counts value correctly; movement maintains a perpetual book the count reconciles against. • A count is a recurring PDEE Program generating governed Agenda work; closure/coverage deterministic; non-closure surfaces on the Board. • Variance derives from real records against tolerances with waste reasons; portfolio shrinkage rolls up on the Board with full drill-back and no silent drops. • Reporting filters and exports the real data; alerts fire via PDEE; every action is audited to the shared spine with last-editor visible and a per-item history view. • Intelligence observes and recommends only, never acts; the system runs fully with AI disabled; tenant isolation enforced via the assignment spine; procurement, recipe-costing, and accounting remain seams. 23. Milestone Governance & Client Protections This is a fixed-cost, milestone-gated scope of work. The following protections govern the engagement and prevail over any conflicting expectation. • Independent milestone gating. Each milestone is independently evaluated and approved. Completion or payment of one milestone does not obligate the Client to authorize, continue, or fund any subsequent milestone. • Client control after any milestone. The Client may pause, restructure, reduce, replace, re-scope, or terminate the engagement after any milestone, at any time and for any reason, with no penalty or obligation beyond milestones already accepted and paid. • Acceptance before payment. Each milestone requires deployment for review, a testing opportunity, and the Client’s acceptance (Section 22) before payment. Partial completion does not trigger automatic payment. No advance, and no payment for work in progress. • Right to reject and remediation. The Client may reject any deliverable that fails Section 22. Rejected work is remediated and re-submitted at no additional cost until accepted or the engagement is terminated. Repeated failure to meet acceptance is grounds for termination without further obligation, and without payment for the unaccepted milestone. • Ownership. All deliverables, code, schema, migrations, documentation, and designs become the exclusive property of HotelHub / OperationsHub upon payment of the applicable milestone. The contractor retains no rights and may not reuse, resell, or repurpose the codebase, schema, architecture, or concepts. Immutable provenance and lineage are preserved. • Confidentiality. The scope, codebase, architecture, and platform concepts are confidential; no disclosure, reuse, or derivative work. • Scope control. Only the capabilities specified in this document are in scope. Anything not specified — including the seams in Sections 17 and 19 — is out of scope and negotiated separately. Acceptance implies no scope expansion. • No schedule or price representation. This document specifies scope, deliverables, and acceptance only. Timeline, sequence, and price are negotiated separately and ar