toga-ai 1.0.355 → 1.0.356

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 32 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 33 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 30 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 11 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

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

@@ -14,11 +14,12 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-06-30
+updated: 2026-07-16
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
   - ../compass-usa/profile.md
+  - ../compass-usa/features/approval-decision-flow.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../2.0/apps/_underscore/features/surface-resolver.md
@@ -59,6 +60,12 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   Compass USA's 1/3/4. See [Surface Resolver](../../2.0/apps/_underscore/features/surface-resolver.md).
 - Customer language preference: `UserGlobalSettings.settingId = 2` (`en` / `fr-CA`); customer-
   facing emails are sent in EN or FR accordingly.
+- **Approval decisions use the shared Compass parent.** `_Model_Compass_Canada_ApprovalDecision`
+  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
+  [Approval-Decision Flow](../compass-usa/features/approval-decision-flow.md).
 - Assortment (product-grouping) names are served in fr-CA via the `AssortmentTranslations` sidecar
   (16 rows seeded). French was extracted from the old bilingual `"English/French"` `Assortments.name`
   values, which were then cleaned to English-only. See

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

@@ -2,6 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**, VIP auto-approve, and EN/FR localization — lives **entirely i | _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Compass/Usa/ApprovalDecision.php, _underscore/Model/Compass/Canada/ApprovalDecision.php |
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql, dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.sql |

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

@@ -0,0 +1,100 @@
+---
+title: Compass Approval-Decision Flow (Notifications & Manager Reassignment)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-07-16
+owners: ["apeterson"]
+files:
+  - _underscore/Model/Compass/ApprovalDecision.php
+  - _underscore/Model/Compass/Usa/ApprovalDecision.php
+  - _underscore/Model/Compass/Canada/ApprovalDecision.php
+related:
+  - mr-ma-order-approval-and-status.md
+  - ../../compass-canada/profile.md
+  - ../../../2.0/apps/_underscore/features/email-template-sending.md
+---
+
+## Summary
+Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**,
+VIP auto-approve, and EN/FR localization — lives **entirely in the 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- and language-specific
+behavior is **not** subclassed; it branches at runtime inside the parent on
+`$api->client->clientIdentifier` (`Compass_Usa` vs `Compass_Canada`). Practical consequence: a fix
+to a parent method applies to **both** Compass US and Compass Canada automatically — there is no
+per-client code change to make.
+
+This doc covers the **approval-decision / notification** half of Compass approvals. The separate
+auto-approval + `_status` gating on the order itself is in
+[Compass MR/MA Order Auto-Approval & Status Gate](mr-ma-order-approval-and-status.md).
+
+## Key files / entry points
+- **`_underscore/Model/Compass/ApprovalDecision.php`** — the shared parent that owns the whole
+  flow (notification-list maintenance, `_swapManagerEmailAddress()`, VIP auto-approve, email-template
+  UUID resolution, localization).
+- **`_underscore/Model/Compass/Usa/ApprovalDecision.php`** — empty subclass, no overrides.
+- **`_underscore/Model/Compass/Canada/ApprovalDecision.php`** — empty subclass, no overrides.
+
+## How it works
+### One shared parent, runtime client branch (not subclass overrides)
+Compass US and Compass Canada resolve to different model classes at request time
+(`_Model_Compass_Usa_ApprovalDecision` / `_Model_Compass_Canada_ApprovalDecision`), but both are
+empty shells extending `_Model_Compass_ApprovalDecision`. All behavior is inherited. Where the two
+tenants differ, the **parent** branches on `$api->client->clientIdentifier === 'Compass_Canada'`:
+- **Email-template resolution** — `resolveEmailTemplateUuid()` picks the tenant's template UUID.
+- **EN/FR localization** — user language is read from `UserGlobalSettings` (`settingId = 2`;
+  `en` / `fr-CA`) so Canadian notifications go out in the recipient's language.
+
+Because the divergence is a runtime branch and not an override, do **not** add per-client logic to
+the empty subclasses — extend the shared parent and branch there if a genuine tenant difference is
+needed.
+
+### Manager reassignment and the notification list
+When a step-2 (Manager) approval decision is **reassigned** to a new manager,
+`_swapManagerEmailAddress()` updates the order's CC/notification list in `SalesOrderEmailAddresses`:
+it removes the outgoing manager's email and adds the incoming manager's. The one email that must
+**never** be dropped is the **order requester's** — the person the order is for, resolved via
+`SalesOrders.contactId → Users` (the requester's email is looked up with a parameterized
+`SELECT Users.email FROM SalesOrders INNER JOIN Users ON Users.contactId = SalesOrders.contactId
+WHERE SalesOrders.id = ?`). Before deleting the old-manager email, the method compares it against
+both the new-manager email and the requester email and **skips the delete when it matches the
+requester**. All of these comparisons are case-insensitive (`strcasecmp()`), matching
+`getFilteredCcEmails()`.
+
+## Gotchas / known issues
+- **Never drop the order requester from notifications on manager reassignment.** If the outgoing
+  manager happens to also be the order requester (same email), deleting the old-manager address
+  from `SalesOrderEmailAddresses` would silently remove the requester from all order notifications.
+  `_swapManagerEmailAddress()` guards against this by comparing the old-manager email to the
+  requester's email (looked up via `SalesOrders.contactId → Users`) and skipping the delete when
+  they match. This was a live bug (fixed 2026-07-16).
+- **Email comparisons must be case-insensitive.** Use `strcasecmp()`, not `!==` — the notification
+  list can hold the same address in different casing, and `getFilteredCcEmails()` already compares
+  case-insensitively. A strict `!==` comparison here previously let a casing mismatch defeat the
+  requester/new-manager guards.
+- **Don't put tenant behavior in the empty subclasses.** `Usa`/`Canada` `ApprovalDecision` are
+  intentionally empty; the tenant branch lives in the parent on `clientIdentifier`.
+
+## Change history
+- 2026-07-16 — Fixed `_swapManagerEmailAddress()` dropping the order requester from the order's
+  notification list (`SalesOrderEmailAddresses`) when a step-2 manager was reassigned and the
+  outgoing manager's email also belonged to the requester: now looks up the requester email via
+  `SalesOrders.contactId → Users` and skips the delete when they match; also switched the
+  old-vs-new and old-vs-requester comparisons to case-insensitive `strcasecmp()` (was `!==`) to
+  match `getFilteredCcEmails()`. Documented that the flow is the shared parent
+  `_Model_Compass_ApprovalDecision` (empty `Usa`/`Canada` subclasses, runtime `clientIdentifier`
+  branch), so the fix covers Compass Canada automatically. Shipped on branch TRUE-80244 (pushed;
+  not yet merged to `_beta`). (apeterson)
+
+## Related docs
+- [Compass MR/MA Order Auto-Approval & Status Gate](mr-ma-order-approval-and-status.md) — the
+  auto-approval + `_status` gating half of Compass approvals (on `_Model_Compass_SalesOrder`).
+- [Compass Canada](../../compass-canada/profile.md) — uses this identical flow; the runtime
+  `Compass_Canada` branch drives its EN/FR notification localization.
+- [Email Template Sending](../../../2.0/apps/_underscore/features/email-template-sending.md) — the
+  shared engine the resolved approval-notification templates are sent through.

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

@@ -15,12 +15,13 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-07-15
+updated: 2026-07-16
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
   - features/asn-to-item-fulfillment.md
   - features/cost-centers.md
+  - features/approval-decision-flow.md
   - workflows/cross-kit-bundle-corruption.md
   - ../../2.0/apps/worker2/features/compass-vip-support-importer.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
@@ -75,6 +76,10 @@ separate, related client (see its own profile).
 - [VIP Support Importer (worker2)](../../2.0/apps/worker2/features/compass-vip-support-importer.md)
   — manual (Postman) worker2 action that reads Compass's quarterly VIP spreadsheet and sets
   `Users.c_supportedByUserId` (assigned support tech) per VIP.
+- [Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) —
+  the shared `_Model_Compass_ApprovalDecision` parent (empty `Usa`/`Canada` subclasses; runtime
+  `clientIdentifier` branch) that owns approval notifications, manager reassignment, VIP
+  auto-approve, and EN/FR localization.
 
 ## Notes
 - **Order status is shipped-only (2026-06-30).** Compass imports all IF stages

package/package.json

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