toga-ai 1.0.997 → 1.0.998

package/knowledge/clients/compass-canada/profile.md

@@ -182,7 +182,9 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   is an empty subclass of `_Model_Compass_ApprovalDecision`; the entire approval/notification/
   manager-reassignment/VIP-auto-approve flow lives in the parent and branches at runtime on
   `clientIdentifier === 'Compass_Canada'` (email-template UUID + EN/FR localization). Fixes to the
-  parent cover Canada automatically — no per-tenant change. See
+  parent cover Canada automatically — no per-tenant change. **Canada has no manager (VIP)
+  auto-approve by business rule**: no setting-18 limit is seeded, so it never fires; empty
+  `ApprovalDecisionTypes` is expected. See
   [Approval-Decision Flow](../compass-usa/features/approval-decision-flow.md).
 - **Canada shares the duplicate-`Users`-row / stranded-approval defect — confirmed 2026-08-20.**
   `Client_CompassCanada` held **2** approvals assigned to dead duplicate user rows (vs. 53 in

package/knowledge/clients/compass-usa/INDEX.md

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary |
 |-----|-----------|---------|
-| [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass sales-order approval-decision / notification flow — approval+CC email lists, manager reassignment, VIP auto-approve, EN/FR localization; open when touch |
+| [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass sales-order approval-decision / notification flow — approval+CC email lists, manager reassignment, settings-driven manager (VIP) auto-approve, EN/FR loc |
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | Compass USA ASN posting auto-creates the ItemFulfillment on the upstream SalesOrder and propagates tracking at every granularity; open when working ASN→IF creat |
 | [Compass Contact Email Resolution & Crossed `primaryContactEmailAddressId` Pointers](features/contact-email-resolution.md) | 2.0 | Any Compass code reading a contact's email must assert the email row belongs to that contact (~14% of pointers are crossed); open before reading Compass contact |
 | [Corporate vs Field laptop personas — the sector-52 split (designed, NOT built)](features/corporate-vs-field-laptop-personas.md) | 2.0 | Agreed design for splitting the Compass catalogue into a Corporate laptop and a field "laptop kit": attach Corporate at sector `J00000` via `Locations_Personas` |

package/knowledge/clients/compass-usa/features/approval-decision-flow.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-10-06
+updated: 2026-10-09
 owners: ["apeterson", "dfranks", "bala"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
@@ -16,11 +16,14 @@ files:
   - _underscore/Model/Client/ApprovalTemplateStage.php
   - _underscore/Model/Quad/SalesOrder.php
   - dbchanges2/Client_Compass/2026-09-10b - RegisterApprovalDecisionPrePostInterceptor.sql
+  - dbchanges2/Core/2026-10-09a - ManagerAutoApproveSettings.sql
+  - dbchanges2/Client_Compass/2026-10-09a - ManagerAutoApproveSettingsSeed.sql
 related:
   - mr-ma-order-approval-and-status.md
   - ../../../2.0/apps/toga25-supply/features/action-button-rule-engine.md
   - ../../../2.0/apps/_underscore/features/sales-order-denial-reason.md
   - people-file-user-lifecycle.md
+  - persona-model-and-levy-gating.md
   - stranded-approval-reassignment.md
   - ../../compass-canada/profile.md
   - ../../compass-canada/features/french-order-email-localization.md
@@ -29,7 +32,7 @@ related:
   - ../../../2.0/apps/_underscore/features/core-domains-app-host-registry.md
   - ../../../1.0/apps/worker/features/compass-manager-approval-reminder-emails.md
 ---
-Compass sales-order approval-decision / notification flow — approval+CC email lists, manager reassignment, VIP auto-approve, EN/FR localization; open when touching Compass approval emails, manager swaps, or stuck/stranded approvals.
+Compass sales-order approval-decision / notification flow — approval+CC email lists, manager reassignment, settings-driven manager (VIP) auto-approve, EN/FR localization; open when touching Compass approval emails, manager swaps, or stuck/stranded approvals.
 
 ## Summary
 Whole flow lives in shared parent `_Model_Compass_ApprovalDecision`. Both tenant subclasses `_Model_Compass_Usa_ApprovalDecision` and `_Model_Compass_Canada_ApprovalDecision` are **empty** (`extends _Model_Compass_ApprovalDecision {}`, no overrides). Client/language behavior is NOT subclassed — it branches at runtime in the parent on `$api->client->clientIdentifier` (`Compass_Usa` vs `Compass_Canada`). Fix a parent method → applies to both Compass US and Canada; no per-client change.
@@ -84,13 +87,29 @@ Only **three** clients ever build a supply order link — Compass USA, Compass C
 - **`worker2` — zero** supply/commerce link generation.
 - **Out of scope, same bug class, deliberately left alone:** user-facing commerce `userOrderUrl` links (`Model/Compass/SalesOrder.php` ~L484 and ~L1060, `Model/Compass/ApprovalDecision.php` ~L423 and ~L730) plus ~ten inline commerce URL literals across worker crons.
 
-### VIP manager auto-approve — rule + its three (all supervisor-derived) triggers
-A manager-stage (step 2) approval auto-approves iff the assigned manager's `Users.c_isVip = 1` AND order subtotal `<= _Model_Compass_SalesOrder::AUTO_APPROVE_IF_MANAGER_IS_VIP_AND_UNDER_AMOUNT` (= `5000`). Subtotal = `SUM(SalesOrderItems.quantity * price)` via `_Model_Client_SalesOrder::_subtotal()`.
+### Manager auto-approve (VIP) — settings-driven rule + its three triggers (TRUE-82608, 2026-10-09)
+One check, `_Model_Compass_ApprovalDecision::shouldAutoApproveManagerStep(int $managerUserId, float $orderSubtotal)`. Step 2 auto-approves iff ALL:
+1. Manager has a limit = `MAX(PersonaGlobalSettings.value)` with `settingId = 18` (`manager-auto-approve-limit`) over the manager's `Users_Personas` (numeric values only, `REGEXP` filter) — `getManagerAutoApproveLimit()`.
+2. Order subtotal `<=` that limit. Subtotal = `SUM(SalesOrderItems.quantity * price)` (`_Model_Client_SalesOrder::_subtotal()`), never `_total`.
+3. Manager has NOT opted out: no `UserGlobalSettings` row `settingId = 19` (`manager-auto-approve-opt-out`) with value `'1'` — `hasManagerOptedOutOfAutoApprove()`.
 
-Evaluated in exactly three places, all deriving the manager from a supervisor relationship:
-- **(a) Order creation** — `_Model_Compass_SalesOrder::postPost`, inside `elseif (!empty($managerUserUuid))`, where `$managerUserUuid` comes from requester's `Users.supervisorUserId`.
-- **(b) "Order for" / contact change** — `_Model_Compass_SalesOrder::postPut`, only when the PUT payload changes `contact`; re-derives the manager from the new contact's supervisor.
-- **(c) Manager reassignment** — `_Model_Compass_ApprovalDecision::handleManagerReassignment`, wired into `postPut` **only** (added by TRUE-78851). Writes log notes `"Manager reassigned — approval decision reset"` (non-VIP) or `"Manager approval skipped due to VIP logic"` (VIP auto-approve).
+Constants `SETTING_ID__MANAGER_AUTO_APPROVE_LIMIT = 18` / `SETTING_ID__MANAGER_AUTO_APPROVE_OPT_OUT = 19` on `_Model_Compass_ApprovalDecision`. Note text from `buildManagerAutoApproveNote()` is unchanged (`"Auto-approved: Manager is VIP and order total <= 5000"`, amount now read from the setting).
+
+**Replaced** the old rule `Users.c_isVip = 1 AND subtotal <= _Model_Compass_SalesOrder::AUTO_APPROVE_IF_MANAGER_IS_VIP_AND_UNDER_AMOUNT (5000)` — that constant is **removed**; do not reintroduce `c_isVip` here. Why: a VIP manager (`Client_Compass` user **60817**) wanted to approve every order himself, but `c_isVip` cannot be cleared (it comes from the HR people file and other teams use it).
+
+Data (all ids identical in prod, dev-sandbox, client-sandbox):
+- `dbchanges2/Core/2026-10-09a - ManagerAutoApproveSettings.sql` — `Core.Settings` ids 18/19, pinned + guarded.
+- `dbchanges2/Client_Compass/2026-10-09a - ManagerAutoApproveSettingsSeed.sql` — `PersonaGlobalSettings` persona **35** (VIP Role) / setting 18 = `'5000'`; `UserGlobalSettings` user 60817 / setting 19 = `'1'`. Literal ids, no Core reference.
+- **Release order: Core SQL → Client_Compass SQL → deploy `_underscore`.** Code first = ALL VIP auto-approval stops until seeded.
+- Persona 35 is a safe stand-in for `c_isVip`: PeopleFile grants it to every VIP and removes it when VIP is dropped (prod: 2269/2269 active VIPs hold it, no non-VIP does) — see [Persona model](persona-model-and-levy-gating.md). Replay of the last 5,184 prod manager decisions: old rule 1,663 auto-approved, new 1,662; the only difference is user 60817.
+- To change a limit: edit the persona's setting-18 row (or seed one on another persona). To exempt one manager: add their setting-19 = `'1'` row.
+
+Evaluated in exactly three places, all calling the shared check:
+- **(a) Order creation** — `_Model_Compass_SalesOrder::postPost`, inside `elseif (!empty($managerUserUuid))` (manager = delegate or requester's `Users.supervisorUserId`).
+- **(b) "Order for" / contact or delegate change** — `_Model_Compass_SalesOrder::postPut`; re-derives the manager. Compares **subtotal** since TRUE-82608 (before, it wrongly used `_total` = subtotal + shipping + tax).
+- **(c) Manager reassignment** — `_Model_Compass_ApprovalDecision::_evaluateManagerVip` via `handleManagerReassignment` (wired into `postPut` only, TRUE-78851); also reached by the bulk stranded-approval worker. Log notes `"Manager reassigned — approval decision reset"` (no auto-approve) or `"Manager approval skipped due to VIP logic"`.
+
+**Compass Canada has no manager auto-approve, by business rule.** Same code path runs, finds no setting-18 row (nothing seeded; persona 35 does not exist there), never auto-approves. Empty Canada `ApprovalDecisionTypes` is expected, not a bug.
 
 ### Who becomes the step-2 manager: delegate note first, supervisor otherwise
 `_Model_Compass_SalesOrder` resolves the step-2 (Manager) manager two ways:
@@ -155,9 +174,9 @@ When a step-2 (Manager) decision is reassigned, `_swapManagerEmailAddress()` upd
 - **⚠ A pure reassignment notifies nobody.** Changing only `ApprovalDecisions.assignedToUserId` sends no email: `handleApprovalDecision()` returns early when `isApproved` is absent from the payload, and `handleAssignmentNotification()` fires only for step 1. The manager approval-request email is triggered when the admin approves step 1, not when an assignment changes. Any tool/backfill/admin action that repoints a manager must send its own notification.
 - **`_evaluateManagerVip()` silently no-ops when the order has no requester `Users` row.** Runs `INNER JOIN Users ON Users.contactId = SalesOrders.contactId`; with nothing linked to the order's contact it returns zero rows and returns without evaluating VIP. Pre-existing — a second distinct way (alongside the no-supervisor POST-path gap below) for an order to never get VIP auto-approve considered.
 - **Stale supervisor links are the bigger source of stuck approvals — and the supervisor path does no `isActive` check.** Prod 2026-08-12: **869 active users have a `supervisorUserId` pointing at an inactive `Users` row**, and only **2** of those supervisors have a live twin account. The delegate/duplicate problem at the same moment: **77 open step-2 decisions assigned to inactive users** — only **11** automatically resolvable (8 by matching `c_hrEmpPersonnelNbr`, 3 more by email), the other **66** managers who left with no live record. Read them differently: *same human, new account* is mechanically fixable; *departed manager* needs a human to name the replacement. (Counts are point-in-time.)
-- **VIP auto-approve bypassed when the requester has no supervisor (POST-path gap).** All three VIP triggers are supervisor-derived. When a requester has `Users.supervisorUserId = NULL`, order creation skips the manager branch (no step-2 decision, no manager). If an admin then manually adds a manager, that CREATES the step-2 decision as a POST to `/approval-decisions` → `_Model_Compass_ApprovalDecision::postPost`, which calls only `logApprovalDecision` + `handleApprovalDecision` — neither contains VIP auto-approve logic. So a VIP manager under $5000 added to a no-supervisor order never auto-approves and must be manually overridden. TRUE-78851 wired `handleManagerReassignment` into `postPut` only, never the first assignment (POST).
+- **VIP auto-approve bypassed when the requester has no supervisor (POST-path gap).** All three VIP triggers are supervisor-derived. When a requester has `Users.supervisorUserId = NULL`, order creation skips the manager branch (no step-2 decision, no manager). If an admin then manually adds a manager, that CREATES the step-2 decision as a POST to `/approval-decisions` → `_Model_Compass_ApprovalDecision::postPost`, which calls only `logApprovalDecision` + `handleApprovalDecision` — neither contains VIP auto-approve logic. So a manager with a setting-18 limit, added to a no-supervisor order under that limit, never auto-approves and must be manually overridden. TRUE-78851 wired `handleManagerReassignment` into `postPut` only, never the first assignment (POST).
   - **Diagnostic signature:** absence of both `handleManagerReassignment` log notes in `Logs_<Tenant>.Record`, plus a step-2 decision whose `approvalDecisionTypeId = NULL` and `decidedByUserId` = the admin (not the manager). Order event log = logs cluster schema `Logs_Compass` (per-client `Logs_<Tenant>`), table `Record`, columns `(recordId, primaryKeyId, userId, timestamp, note)`; SalesOrder `RECORD_ID = 14`, `ApprovalDecisions` = **179**. Full manager-assignment history reconstructable from these tables — including telling an in-app change from a direct DB edit: see [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md).
-  - Real incident: order SA134461 — VIP manager Spyros Gravas, subtotal $926.47 (both auto-approve conditions met) still required manual override because the requester had no supervisor.
+  - Real incident: order SA134461 — VIP manager Spyros Gravas, subtotal $926.47 (auto-approve conditions met) still required manual override because the requester had no supervisor.
 - **⚠ The `!$hasManager` branch strands orders in an unrecoverable decided-but-untyped state — worst of the no-supervisor family.** When the "Order for" contact is changed to a user with no `Users.supervisorUserId`, `_Model_Compass_SalesOrder::postPut`'s `!$hasManager` branch (`Model/Compass/SalesOrder.php` ~L1018) PUTs `assignedToUser`, `decidedByUser`, `isApproved`, `approvalDecisionType`, `note` **and** `dtDecision` all to `null` — deliberately wiping an existing VIP auto-approval. A later manual approval sets `isApproved = 1` + `decidedByUserId` but never stamps `approvalDecisionTypeId` (correct — not a *system* decision). End state: `isApproved = 1`, `approvalDecisionTypeId = NULL`, and frequently a stale "Auto-approved: Manager is VIP and order total <= 5000" note.
   - **Frontend consequence (makes it unrecoverable):** blox derives `isPreApproved` from `!!stage.ApprovalDecisionTypes.name`, so it is `false`. The approval modal locks the stage's inputs and hides the Stage Actions block containing the only "Reset to Pending" control — no admin action can recover. This is why the 2026-08-31 frontend fix gates on `stepOneUndecided` rather than `isPreApproved` (see [Action-Button Rule Engine](../../../2.0/apps/toga25-supply/features/action-button-rule-engine.md)).
   - **Diagnostic signature in order activity log**, in order: `"Manager approval skipped due to VIP logic"` (creation-time VIP auto-approve), then `"Manager assignment cleared: new user has no supervisor"` AND `"VIP auto-approval removed: new user has no supervisor"` (written only by that `!$hasManager` branch), then `"Manager Approved by <admin>"` (manual approval).
@@ -177,9 +196,11 @@ When a step-2 (Manager) decision is reassigned, `_swapManagerEmailAddress()` upd
 - **⚠ An exemption from a server-side guard must be decided from the DATABASE, never from a client-supplied field.** The step-1 guard originally skipped itself when the payload carried `approvalDecisionType` / `approvalDecisionTypeId`, treated as a "system auto-approval" marker. That value comes from the request body → any caller could set it and skip the check. The early return and its `_isSystemAutoApproval` helper were removed in PR review. Checked against prod first: all **5,028** step-1 auto-approvals in Compass history are MR/MA orders (Canada has none), so the DB-backed order-number check covers every real case, and VIP auto-approvals land on step 2 and exit at the step check. General rule for any guard added here.
 - **⚠ The green approve tick used to silently replace the step-2 manager with the approver.** `makeApprovalDecision()` / `updateApprovalDecision()` in supply hardcoded `assignedToUserId: { uuid: userUuid }` into every single-stage approve payload, so an admin approving the manager stage overwrote the real manager with themselves — and the timeline read "Manager Approved", making it look like the manager acted. Confirmed on **SA136901** (07:18:35 re-sent an assignee that had not changed; Dawn Anderson already assigned by Emily at 06:50:06); also hit **SA136807** (Angel Almodovar replaced) and **SA137080** (delegate manager Daniel Mezzanares replaced). Fixed front-end by removing the field — `decidedByUserId` already records who approved. The "Approve All Stages" path was always correct, which is why it never reproduced there. Detail: [Record Modals & Nested Tables](../../../2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md).
 - **⚠ A manager swap sent in the SAME save as an approval is never logged, and the email list keeps the old manager.** `_evaluateManagerVip()` returns immediately when the request carries `isApproved`, assuming a request is *either* an assignment *or* an approval. When both arrive together the `"Manager reassigned"` note is skipped (the feature works — fired 757 times since May) AND so is the `SalesOrderEmailAddresses` swap, so the outgoing manager stays on the notification list. A handler for the combined case was drafted on the `_sandbox-client` branch only and is NOT on `TRUE-81900` — known gap, not shipped.
+- **⚠ Never read the auto-approve LIMIT from `UserGlobalSettings`.** Users can write their own `UserGlobalSettings` rows (the "own" ACL), so a per-user limit would let anyone raise their own approval ceiling. Limit lives only on `PersonaGlobalSettings` (admin-controlled). The opt-out is per-user on purpose: any write to it can only force manual approval, never skip it. Settings 18/19 are not in the user-writable allowlist of the `UserGlobalSettings` own-row guard — see [own-row guards](../../../2.0/apps/api2/features/api-payload-interceptors.md#own-row-guards-in-a-pre-interceptor).
 - **The upstream cause of an unassigned step 2 is a user saved with no `supervisorUserId`.** The admin add-user screen allows saving a user without one, and the PEOPLE-file import may or may not backfill it later. That data hole feeds both the `!$hasManager` wipe above and the never-created step-2 decision at order creation. Not fixed — the guard only stops the order being *stranded*, it does not give it a manager.
 
 ## Change history
+- 2026-10-09 — Manager auto-approve moved from `c_isVip` + hardcoded 5000 to persona setting 18 (limit) + user setting 19 (opt-out); postPut now compares subtotal (TRUE-82608). (bala)
 - 2026-10-06 — Recorded that no delegate + no supervisor saves an order with no step-2 decision, and that the commerce cart now blocks it (TRUE-82423). (bala)
 
 ## Related

package/knowledge/clients/compass-usa/features/persona-model-and-levy-gating.md

@@ -6,7 +6,7 @@ project: Worker
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-10-05
+updated: 2026-10-09
 owners: [bala, ajean, mhammontree]
 files:
   - worker2/Worker/Client/Compass/PeopleFile.php
@@ -51,7 +51,7 @@ below.
 | Base (was "All") | **1** | The **9** kits Levy and non-Levy both hold (81, 82, 84, 85, 105, 115, 120, 165, 166), plus the 71 items / 11 categories Levy also holds. **Every US user holds it.** |
 | Levy Purchaser | **24** | Levy's own **5** kits: 189, 193, 213, 231, 242. |
 | Non-Levy | **resolved by name** — **id 40, number 42 in prod** | The other 14 persona-1 kits / 123 items / 3 categories. Granted to non-Levy users only. |
-| VIP | 35 | VIP add-on. |
+| VIP | 35 | VIP add-on. Carries the manager auto-approve limit (`PersonaGlobalSettings` setting 18 = `'5000'`) — see [Approval-Decision Flow](approval-decision-flow.md). |
 | CDL (MacBook / Surface) | 30 | `@compassdigital.io` + VIP users. |
 
 **Never hardcode the Non-Levy id, and never assume it matches the number.** In prod it is **id 40**
@@ -184,6 +184,7 @@ Both are **latent, not live, and not yet fixed** — each needs its own ticket.
   constants from this file into tickets, docs, or chat transcripts.
 
 ## Change history
+- 2026-10-09 — Persona 35 now carries the manager auto-approve limit (setting 18); PeopleFile keeps it in exact sync with `c_isVip` (prod 2269/2269), so do not decouple the two (TRUE-82608). (bala)
 - 2026-10-05 — Linked the deferred
   [corporate vs field laptop split](./corporate-vs-field-laptop-personas.md) (Corporate attached at
   sector `J00000` via `Locations_Personas`; Field assigned here in `PeopleFile`, mirroring the Levy

package/knowledge/clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-09-16
+updated: 2026-10-09
 owners: ["jcardinal", "bala", "dfranks"]
 files: []
 related:
@@ -32,7 +32,8 @@ Compass customer SO  (SalesOrders.customerId = 2, number SA/MA/MR)
         --PurchaseOrders_SalesOrders--> Agilant/NetSuite SO (customerId = 3)
 ```
 - **SA** orders are user-created in Compass then sent to MITS; **MR** orders are created retroactively from the inbound MITS PO (they do not originate as Compass-entered SOs); MA exists too. Structurally MR uses the same bridges as SA.
-- One Compass SO item can split into multiple PO items (bundles / `c_isConfiguration`, `parentSalesOrderItemId`, `bundleId`).
+- One Compass SO item can split into multiple PO items (bundles / `c_isConfiguration`, `parentSalesOrderItemId`). Kit lines link via `SalesOrderItems.bundleItemId → BundleItems.bundleId`; `SalesOrderItems.bundleId` is effectively unused — never query kits by it.
+- `Client_Compass` order numbers `29xxxx` and `45`–`48xxxxxxxxx` are the Office Depot / Agilant side copies (`customerId` 1 / 3), not commerce orders — exclude them when counting Compass orders.
 
 ## Steps
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.997",
+  "version": "1.0.998",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",