toga-ai 1.0.417 → 1.0.418

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

@@ -6,8 +6,8 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-07-17
-owners: ["apeterson", "dfranks"]
+updated: 2026-07-23
+owners: ["apeterson", "dfranks", "bala"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
   - _underscore/Model/Compass/SalesOrder.php
@@ -50,11 +50,35 @@ tenants differ, the **parent** branches on `$api->client->clientIdentifier === '
 - **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.
+- **Web-link host resolution** — `_Model_Compass_SalesOrder::resolveSupplyHost()` /
+  `resolveCommerceHost()` pick the tenant's supply/commerce domain for the links embedded in
+  approval and order-status emails (see below).
 
 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.
 
+### Email-link host resolution (US vs Canada domains)
+The "Review Order" link (togasupply) and the user order-details link (togacommerce) embedded in
+Compass approval and order-status emails are built from a **client-aware host resolver** on the
+shared parent `_Model_Compass_SalesOrder`, so the link always points at the domain that actually
+holds the order:
+- Four host constants: `HOST_SUPPLY__COMPASS_US = 'compass.togasupply.com'`,
+  `HOST_SUPPLY__COMPASS_CANADA = 'compasscanada.togasupply.com'`,
+  `HOST_COMMERCE__COMPASS_US = 'compass.togacommerce.com'`,
+  `HOST_COMMERCE__COMPASS_CANADA = 'compasscanada.togacommerce.com'`.
+- Public static `resolveSupplyHost(&$api)` / `resolveCommerceHost(&$api)` return the correct host;
+  private static `isCompassCanadaClient(&$api)` returns
+  `($api->client->clientIdentifier ?? '') === 'Compass_Canada'`. Anything not Canada falls back to
+  the **US** host, so US behavior is unchanged.
+- All 8 link-building sites build the URL as `"https://" . resolveSupplyHost($api) . "/?..."` (only
+  the host varies; the query string / uuid is identical). Sites wired: `ApprovalDecision.php` —
+  manager-approval-request block and VIP auto-approve block (`orderUrl` + `userOrderUrl` in each);
+  `SalesOrder.php` — admin-approved block (`postPut`), in-transit/delivered block, and
+  `_sendVipManagerNotification`.
+- This reuses the **same `$api->client->clientIdentifier` signal** as the email-template language
+  resolver, so the link host and the email template can never disagree.
+
 ### VIP manager auto-approve — the rule and its three (all supervisor-derived) triggers
 A single rule governs VIP auto-approve: a **manager-stage (step 2)** approval auto-approves iff the
 assigned manager's `Users.c_isVip = 1` **AND** the order subtotal
@@ -114,8 +138,25 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   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`.
+- **Never hardcode the web host in email links.** The email links previously used string literals
+  `compass.togasupply.com` / `compass.togacommerce.com` in the parent classes. Because the tenant
+  subclasses are empty, **Compass Canada orders inherited the US links** and sent Canada
+  recipients to the US supply/commerce site, which does not contain their order — so the link never
+  opened. Always build the host via `_Model_Compass_SalesOrder::resolveSupplyHost()` /
+  `resolveCommerceHost()`, never a literal. Real incident: order SAC100650 — manager Gary Berenz
+  could not open the order from the "Manager Approval Needed" email, so admin Kai Wong had to
+  approve as manager on his behalf. (Fixed 2026-07-23.)
 
 ## Change history
+- 2026-07-23 — Fixed Compass approval/status **email links** being hardcoded to the US domains
+  (`compass.togasupply.com` / `compass.togacommerce.com`) in the parent classes, so Compass Canada
+  orders (empty `Canada` subclass) inherited US links and Canada recipients were sent to a site
+  without their order. Added a client-aware host resolver to `_Model_Compass_SalesOrder` (four
+  `HOST_*` constants, `resolveSupplyHost()`/`resolveCommerceHost()`, `isCompassCanadaClient()`
+  branching on `clientIdentifier === 'Compass_Canada'`, US fallback), and rewired all 8 link sites
+  in `ApprovalDecision.php` and `SalesOrder.php` to build the host through it — reusing the same
+  `clientIdentifier` signal as the email-template resolver so host and template always agree.
+  Verified both client contexts resolve correctly; `php -l` clean. Prod incident SAC100650. (bala)
 - 2026-07-17 — Documented the VIP manager auto-approve rule (VIP manager + subtotal ≤ $5000) and
   its three supervisor-derived triggers (`postPost` creation, `postPut` contact change,
   `handleManagerReassignment` on `postPut`), plus the **POST-path gap**: a requester with no

package/package.json

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