toga-ai 1.0.121 → 1.0.122

package/knowledge/1.0/apps/worker/INDEX.md

@@ -3,7 +3,8 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
-| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compass/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php |
+| [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
+| [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php |
 | [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/reconcile_netsuite_totals.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |

package/knowledge/1.0/apps/worker/features/compass-ma-sales-order-exception-report.md

@@ -0,0 +1,82 @@
+---
+title: Compass MA Sales Order Exception Report
+framework: "1.0"
+repo: worker
+project: Worker
+client: compass-usa
+type: feature
+status: active
+updated: 2026-06-18
+owners: ["bala"]
+files:
+  - worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php
+related: []
+---
+
+## Summary
+A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%`
+sales orders whose corresponding Office Depot (ODP) sales order has **not** been created in
+NetSuite yet. It is a catch-the-stragglers report: orders that should have flowed to NetSuite
+but haven't. Runs against the Compass client DB (`db_prod_compass` / `Client_Compass`).
+
+## Key files / entry points
+- `worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php` — the
+  whole job: one main SELECT, a per-row NetSuite recheck, and a PhpSpreadsheet Excel email.
+
+## How it works
+1. **Main query** walks a two-hop bridge chain to connect the customer order to the vendor order:
+   Compass SO (`number LIKE 'MA%'`) → `SalesOrders_PurchaseOrders` → Compass PO →
+   `PurchaseOrders_SalesOrders` → **ODP SO** (`customerId = OFFICE_DEPOT`) →
+   `SalesOrders_PurchaseOrders` → ODP PO. Note the two bridge tables are used in **opposite
+   directions** at each hop — `SalesOrders_PurchaseOrders` for SO→PO, `PurchaseOrders_SalesOrders`
+   for PO→SO. It also inner-joins the ODP SO's address, state, items, item→PO-item bridge, PO
+   items, and vendor items — so a row with any of those missing silently drops out.
+2. **Filter:** `MA%` Compass SO, ODP SO `customerId = App_Client_Compass::CUSTOMER_ID__OFFICE_DEPOT`
+   (= 1), and `OfficeDepotSalesOrders.c_netsuiteInternalSalesOrderId IS NULL`.
+3. **Per-row NetSuite recheck:** for each surviving row it looks for an **Agilant**-customer
+   (`CUSTOMER_ID__AGILANT` = 3) sales order tied to that ODP PO number. If found → it back-fills
+   `c_netsuiteInternalSalesOrderId` on the ODP SO and skips the row (drops it off the report
+   permanently). If not found → it writes the row to the Excel.
+4. Emails the workbook to operations only if at least one data row was written.
+
+## Data model
+- `Client_Compass.SalesOrders` — the ODP sales order is the one keyed on (`id AS salesOrderId`,
+  `customerId = 1` Office Depot). Relevant columns: `c_netsuiteInternalSalesOrderId` (NULL until
+  the order exists in NetSuite) and `salesOrderStageId`.
+- `Client_Compass.SalesOrderStages` — `5 = Pending Billing`, `6 = Pending Billing/Partially
+  Fulfilled`, `7 = Billed`, `8 = Canceled`, `9 = Closed`.
+- Bridges: `SalesOrders_PurchaseOrders` (salesOrderId, purchaseOrderId) and
+  `PurchaseOrders_SalesOrders` (purchaseOrderId, salesOrderId) — distinct tables, distinct
+  directions.
+
+## Client variations
+Compass USA only — this is a Compass-specific integration cron.
+
+## Gotchas / known issues
+- **Two removal levers, and only one used to exist.** Historically the *only* way an order left
+  the report was `c_netsuiteInternalSalesOrderId` becoming non-NULL (set by the per-row recheck
+  when the NetSuite order is found). An order **closed/canceled on Office Depot's end** never gets
+  a NetSuite order, so it never gets that id, so it stuck on the report forever. The fix (2026-06)
+  added a **stage-based exclusion** so canceling/closing the ODP SO removes it.
+- **To remove an order, mark the OFFICE DEPOT sales order — not the Compass SO.** The query
+  filters on `OfficeDepotSalesOrders.salesOrderStageId`; the Compass SO's stage is never read.
+  Setting the Compass `MA%` order's stage does nothing.
+- **NULL-safe stage filter is mandatory.** Active orders normally have `salesOrderStageId = NULL`.
+  In SQL `NULL NOT IN (8, 9)` evaluates to *unknown* (not true), so a bare
+  `salesOrderStageId NOT IN (8, 9)` would drop **every NULL-stage order** — i.e. almost the whole
+  report. The condition must be `(salesOrderStageId IS NULL OR salesOrderStageId NOT IN (8, 9))`,
+  and it must be parenthesized because `AND` binds tighter than `OR`.
+- **Don't fake the NetSuite id to hide an order.** Writing a bogus `c_netsuiteInternalSalesOrderId`
+  removes it from the report but corrupts the field for anyone who reads it later. Use the stage
+  lever instead.
+- `$inProduction = true` switches the DB link to `db_prod_compass`; set false to test against
+  `db_beta_compass`.
+
+## Change history
+- 2026-06-18 — Added stage-based exclusion so orders closed/canceled on ODP's end drop off the
+  report: `(salesOrderStageId IS NULL OR salesOrderStageId NOT IN (8, 9))` in the main query.
+  Removing specific stuck orders is then a data change (set the ODP SO's `salesOrderStageId` to
+  8/9), not a code change. (bala)
+
+## Related docs
+- [Compass USA profile](../../../clients/compass-usa/profile.md)

package/knowledge/1.0/apps/worker/features/compass-partial-in-transit-delivered-emails.md

@@ -10,9 +10,7 @@ updated: 2026-06-18
 owners: ["bala"]
 files:
   - worker/crons/toga2/compass/update_salesorder_status_from_odp.php
-  - worker/crons/toga2/compass/workflow/test_partial_in_transit_email.php
   - worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php
-  - worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php
 related: []
 ---
 
@@ -30,8 +28,6 @@ and earlier packages). The dynamic HTML is injected into a stored `EmailTemplate
 - `worker/crons/toga2/compass/update_salesorder_status_from_odp.php` — Compass USA prod cron.
 - `worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php`
   — Compass Canada prod cron.
-- `*/workflow/test_partial_in_transit_email.php` — read-only prod test scripts for each client
-  (email goes only to a test recipient, no DB writes). Use these to preview rendering.
 - Shared helper set in each cron: `getOrderFulfillmentData`, `buildItemRowsHtml`,
   `buildSectionHeaderHtml`, `buildPackageBlockHtml`, `buildTrackingUrl`, `buildOrderItemsHtml`.
 
@@ -106,14 +102,13 @@ the tracking number as emailed (it retries next run).
   `getOrderFulfillmentData` — same query as Compass USA. Canada was originally on the ASN chain
   because it had **zero `ItemFulfillmentItems`**; if that line-bridge data is not populated for a
   Canada order, `getOrderFulfillmentData` returns no packages and the cron falls back to the
-  full email. Verify line-bridge data exists for Canada before relying on the partial path.
+  full email.
 - **Line bridge is moving-forward only** — it began populating ~2026-06-12; pre-cutoff tracking
   numbers are intentionally out of scope (driving-query date cutoff).
 - The driving query still uses the ASN chain (to find shipped orders + tracking) for **both**
   clients — that is correct and unrelated to the package-contents source.
-- Test scripts only ever email a test recipient and never write `c_dtInTransitEmailSent`.
-- **Not yet deployed.** These crons depend on the api2 POST scripted-API change and the
-  `RecordScripts`/`AclRecordScripts` registration (prod done, beta pending) — see related docs.
+- **Not yet deployed.** These crons depend on the api2 POST scripted-API change and its
+  `RecordScripts`/`AclRecordScripts` registration — see related docs.
 
 ## Change history
 

package/knowledge/2.0/apps/_underscore/features/email-template-sending.md

@@ -87,7 +87,7 @@ can keep using `sendEmail($api, ...)`.
   (previously the inactive case returned `false` and an SMTP failure was swallowed entirely).
   Any fire-and-forget caller now propagates that exception, which is intended (so an email is
   never silently marked as sent). Blast radius is every client, including the Compass/Quad
-  `SalesOrder`/`ApprovalDecision` order-placed emails — verify on beta before shipping.
+  `SalesOrder`/`ApprovalDecision` order-placed emails.
 
 ## Change history
 

package/knowledge/2.0/apps/api2/features/scripted-api-post-body-args.md

@@ -65,13 +65,9 @@ None — this is engine behavior. Per-client access is controlled by `AclRecordS
 - **Normal CRUD is unaffected.** The POST scripted block only fires when a POST Record Script
   is registered for the route; otherwise the request falls through to the usual create path
   (`if (!$isUsingScriptedCall && empty($routePairs))` / `locateRecord`).
-- **Registration is environment-specific.** The `RecordScripts` (Core) + `AclRecordScripts`
-  (client) rows must exist in every environment the API reads. As of this writing they were
-  run in **prod** for the email `sendEmail` script (Core + Client_Compass + Client_CompassCanada);
-  **beta still needs them** before the POST path dispatches there.
-- **Deploys with `_underscore`.** api2 pulls `_underscore` at deploy; `http://api2` and
-  `api.beta.togahub.com` resolve to deployed boxes (`/var/app/current`), not a local checkout —
-  so testing the change requires deploying it, not just editing locally.
+- **Registration is per-environment.** The `RecordScripts` (Core) + `AclRecordScripts`
+  (client) rows must exist in every environment the API reads; a missing POST `RecordScripts`
+  row means the POST path silently falls through to normal CRUD.
 - **CI commit policy.** Subject must be `TRUE-<ticket>: <Subject>` (≤80 chars, capitalized,
   imperative, no trailing period, more than one word).
 

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 7 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 9 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 5 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)

package/package.json

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