toga-ai 1.0.614 → 1.0.616

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -5,6 +5,7 @@
 | [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform | src/main.tsx, src/App.tsx, src/routes.tsx, src/contexts/AuthContext.tsx, src/contexts/helpers/getLoginSettings.ts, src/api/axiosInstance.ts, src/stores/, src/themeConfig/ThemeContext.tsx, src/fieldsConfig/index.ts, src/hooks/useAssignClientFields.ts, vite.config.ts, package.json |
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts, src/utils/formatSalesOrderBundlesFromApi.ts, src/stores/useCartStoreZu.ts, src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts, src/pages/OrderDetails/view/components/OrderItems.tsx |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
+| [Cart Order-Total & Shipping Computation](features/cart-order-total-computation.md) | The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from `cartData`. | toga2-commerce/src/pages/Cart/viewModel/useCartViewModel.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/api/CartApi.ts |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
 | [Catalog cache freshness — the 24h persisted query cache, and how to opt a query out of it](features/catalog-cache-freshness.md) | TOGa Commerce runs a **single `QueryClient` with a 24-hour default `staleTime`**, and persists it to **`localStorage["commerce"]`** through `PersistQueryClientP | toga2-commerce/src/App.tsx, toga2-commerce/src/contexts/AuthContext.tsx, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts |
 | [Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category](features/category-tile-sort-order.md) | **"Move item X to the front of category Y" is a DATA change, not a code change.** The order of item tiles on a storefront category page is driven by exactly one | src/pages/Filter/api/FilterApi.ts, src/pages/Filter/viewModel/useFilterViewModel.ts, api2/Component/Api/V2/V2.php, toga2-supply/src/pages/Items/api/itemsApi.ts |
@@ -14,6 +15,7 @@
 | [Inactive-item purchase gating (standalone lines only — kits are exempt by design)](features/inactive-item-purchase-gating.md) | An item with **`Items.isActive = 0`** must not be viewable, addable to a cart, or orderable **as a standalone line** on the storefront — but the **same flag is | toga2-commerce/src/utils/checkIsItemPurchasable.ts, toga2-commerce/src/api/fetchItemsActiveStatus.ts, toga2-commerce/src/hooks/useCartReconciliation.ts, toga2-commerce/src/stores/useCartStoreZu.ts, toga2-commerce/src/pages/ItemsView/api/ItemsApi.ts, toga2-commerce/src/pages/ItemsView/viewModel/useItemDetailsViewModel.ts, toga2-commerce/src/pages/ItemsView/ItemViewPage.tsx, toga2-commerce/src/components/AuthLayout/AuthLayout.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartTableBundleItem.tsx, toga2-commerce/src/api/syncSalesOrderFromApiToLocalStorage.ts, _underscore/Model/Compass/SalesOrder.php, dbchanges2/Client_Compass/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql, dbchanges2/Client_CompassCanada/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |
 | [Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel](features/order-submit-sync-sequencing.md) | Submitting an order from the cart fires **two independent sync routines** — one for the sales-order header (`syncSalesOrderData`) and one for the line items (`s | toga2-commerce/src/pages/OrderDetails/hooks/useSubmitOrder.ts, toga2-commerce/src/api/syncSalesOrdersDataFromLocalStorageCartToApi.ts, toga2-commerce/src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
+| [Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)](features/shipping-cost-waiver-gating.md) | On the toga2-commerce **Cart** page, a shipping option's **cost** can be waived by config using the same `PrimaryItemShippingRule` vocabulary that drives expedi | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/CartPage.tsx |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |
 | [Cart e2e — Cypress conventions & harness (toga2-commerce)](workflows/cypress-testing.md) | The Cypress **e2e** convention set for `toga2-commerce`, and the first **active** e2e coverage for the **Cart** page (`cartV2.cy.ts`, slice 1 — 12 tests, verifi | toga2-commerce/cypress/e2e/cartPage/cartV2.cy.ts, toga2-commerce/cypress/fixtures/cart/fetchSingleUserAdmin.json, toga2-commerce/cypress/fixtures/cart/fetchLocations.json, toga2-commerce/cypress/fixtures/cart/fetchUserShippingMethods.json, toga2-commerce/cypress/support/commands.ts, toga2-commerce/cypress/support/e2e.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartFormSection.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartContentsTable.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartTableItem.tsx, toga2-commerce/src/components/Inputs/AdvancedInput.tsx, toga2-commerce/src/components/BaseButton/BaseButton.tsx |
 | [Diagnosing ERR_HTTP2_PROTOCOL_ERROR (one client fails, everyone else is fine)](workflows/http2-protocol-error-diagnosis.md) | When a Chromium browser (Chrome / Edge) shows **`ERR_HTTP2_PROTOCOL_ERROR`** loading a `*.togacommerce.com` tenant for **one client/network but works for the TO |  |

package/knowledge/2.0/apps/toga2-commerce/features/cart-order-total-computation.md

@@ -0,0 +1,57 @@
+---
+title: Cart Order-Total & Shipping Computation
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-08-19
+owners: [apeterson]
+files:
+  - toga2-commerce/src/pages/Cart/viewModel/useCartViewModel.ts
+  - toga2-commerce/src/pages/Cart/CartPage.tsx
+  - toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx
+  - toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts
+  - toga2-commerce/src/pages/Cart/api/CartApi.ts
+related:
+  - 2.0/apps/toga2-commerce/features/shipping-cost-waiver-gating.md
+  - 2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
+  - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+---
+
+## Summary
+The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from
+`cartData`. `cartData.total` is computed in `useCartViewModel` as `subtotal + tax + shipping`,
+where `shipping` is read from `salesOrder.shipping` in the zustand cart/sales-quote store —
+**not** directly from the selected dropdown option. A `CartPage` effect is the bridge: it
+watches the selected shipping method, looks up the matching fetched option, reads its `c_cost`,
+applies waiver cost-gates, and calls `setShipping()` to write `salesOrder.shipping`.
+
+## How it works
+1. `CartForm.tsx` renders the summary purely from `cartData` (subtotal/shipping/tax/total).
+2. `useCartViewModel.ts` computes `cartData.total = subtotal + tax + shipping`, with `shipping`
+   derived from `salesOrder.shipping` (zustand store).
+3. `CartPage.tsx` has an effect watching the selected `shippingMethod`: it finds the matching
+   fetched option, reads `c_cost`, applies waiver cost-gates (see
+   [shipping-cost-waiver-gating](shipping-cost-waiver-gating.md)), then `setShipping()` writes
+   `salesOrder.shipping`. So the dropdown never feeds the total directly — it flows through the
+   store.
+
+## Gotchas
+- **`c_cost` is ACL-gated per tenant, and a missing grant silently zeroes shipping.** Only the
+  **Compass USA** CARTPAGE configs request fields `["uuid","name","c_cost"]` in
+  `fetchShippingMethod`. **Compass Canada** and **Quad** request only `["uuid","name"]`, so
+  their fetched options carry no `c_cost`; `Number(undefined) → NaN → "0"`, and shipping falls
+  back to `"0"` with no error. This is a **latent gap** for those tenants — if they are meant to
+  charge shipping, their CARTPAGE `fetchShippingMethod` field list must include `c_cost`.
+- **Shipping lives in the store, not the dropdown.** Reading the selected option's cost alone
+  will not tell you the order total — always trace through `setShipping()` →
+  `salesOrder.shipping` → `useCartViewModel`.
+
+## Change history
+- 2026-08-19 — Documented the previously-undocumented cart total/shipping computation path
+  while fixing the Compass USA Standard Ground waiver. Recorded the `c_cost` ACL-gating latent
+  gap for Compass Canada and Quad (their fetched options have no `c_cost`, so shipping silently
+  resolves to "0"). (apeterson)
+</content>

package/knowledge/2.0/apps/toga2-commerce/features/expedited-shipping-gating.md

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-07-27
-owners: [tcox]
+updated: 2026-08-19
+owners: [tcox, apeterson]
 files:
   - toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts
   - toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts
@@ -103,6 +103,10 @@ behavior is expressed in config, not in code branches.
   on that doc's slice-2 work-list.
 
 ## Change history
+- 2026-08-19 — No change to expedited visibility. Noted that the shared shipping-rule type
+  gained an optional `requireNoOtherItemsInKit` flag (+ `bundleHasOtherItems()` helper) used by
+  the separate Standard Ground cost waiver — see
+  [shipping-cost-waiver-gating](shipping-cost-waiver-gating.md). (apeterson)
 - 2026-07-27 — No behavior change. Noted that a cart Cypress e2e harness now exists and a
   gating + guardrail-modal spec is feasible (the `cart/fetchUserShippingMethods.json` fixture
   already ships the gated names with no `c_cost`); it is on the slice-2 work-list. Linked

package/knowledge/2.0/apps/toga2-commerce/features/shipping-cost-waiver-gating.md

@@ -0,0 +1,78 @@
+---
+title: Config-Driven Shipping Cost Waiver (Standard Ground free for computer kits)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-08-19
+owners: [apeterson]
+files:
+  - toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts
+  - toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts
+  - toga2-commerce/src/pages/Cart/CartPage.tsx
+related:
+  - 2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
+  - 2.0/apps/toga2-commerce/features/cart-order-total-computation.md
+  - ../../../../clients/compass-usa/profile.md
+---
+
+## Summary
+On the toga2-commerce **Cart** page, a shipping option's **cost** can be waived by config
+using the same `PrimaryItemShippingRule` vocabulary that drives expedited-option visibility.
+The **Compass USA** carts attach a cost gate `STANDARD_GROUND_FREE_FOR_COMPUTER_KITS` to the
+*Shipping Method* field so that **Standard Ground** ships free for a bare computer kit. The
+waiver is config-driven (no `if (clientSlug === ...)` branching) and is referenced only by the
+four Compass USA role configs (USER/ADMIN/MANAGER/SUPERUSER).
+
+## Key files / entry points
+- `src/pages/Cart/helpers/shippingOptionGates.ts` — `PrimaryItemShippingRule` type,
+  `evaluateShippingOptionRule`, and the `bundleHasOtherItems()` helper.
+- `src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts` — the
+  `STANDARD_GROUND_FREE_FOR_COMPUTER_KITS` gate constant (primary item
+  `itemCategory.name === "COMPUTERS"`, with `requireNoOtherItemsInKit: true`).
+- `src/pages/Cart/CartPage.tsx` — the effect that reads the selected option's `c_cost` and
+  applies waiver cost-gates before calling `setShipping()` (see
+  [cart-order-total-computation](cart-order-total-computation.md)).
+
+## How it works
+1. A cost gate matches a bundle when its **primary item** (`bundleItemGroup.slug === "primary"`)
+   satisfies the `{ item, path, operator, value }` rule — here
+   `item.itemCategory.name === "COMPUTERS"`.
+2. The **optional `requireNoOtherItemsInKit` flag** on `PrimaryItemShippingRule` narrows the
+   match: when set, the bundle qualifies only if the primary item matches **and** the kit has
+   no other items. `bundleHasOtherItems()` returns true when `bundleProgressContents` contains
+   any entry whose `bundleItemGroup.slug !== "primary"` (fees are already excluded from
+   `bundleProgressContents` upstream).
+3. `evaluateShippingOptionRule` qualifies a bundle only when the primary item matches AND, if
+   `requireNoOtherItemsInKit` is set, the kit is bare. Existing cart-wide "any qualifying
+   bundle" semantics for multi-bundle carts are preserved.
+4. When the selected method qualifies, the effect in `CartPage` waives its `c_cost` to 0 before
+   writing `salesOrder.shipping`.
+
+Resulting Compass USA behavior: bare computer kit (primary computer only) → Standard Ground
+free; computer kit **with** other items → charged $10; all non-computer kits → charged;
+expedited methods unchanged (still priced).
+
+## Gotchas
+- **The waiver only means what the flag says.** Before this fix the gate had no
+  `requireNoOtherItemsInKit`, so Standard Ground (the default selection) was waived for **any**
+  cart whose primary bundle item was in `COMPUTERS` — computer kits loaded at $0 shipping and
+  stayed there regardless of what else was in the kit. Always set `requireNoOtherItemsInKit`
+  when a waiver is meant only for a bare kit.
+- **`bundleProgressContents` is the source of truth for "other items"** — it already excludes
+  fees, so a fee line does not make a kit count as "having other items." If that upstream
+  exclusion ever changes, the waiver's narrowing changes with it.
+- **Waiver correctness depends on `COMPUTERS` categorization**, same as the expedited gate —
+  a computer kit mis-categorized in the catalog will neither waive nor gate.
+
+## Change history
+- 2026-08-19 — Fixed an over-broad Standard Ground waiver for Compass USA computer-kit carts:
+  added the optional `requireNoOtherItemsInKit` flag on `PrimaryItemShippingRule` and the
+  `bundleHasOtherItems()` helper, and set the flag on
+  `STANDARD_GROUND_FREE_FOR_COMPUTER_KITS`. Bare computer kits now ship free; kits with other
+  items are charged. Config-driven, Compass USA only, no client branching. No test harness in
+  the repo (no vitest/jest); verified by review. (apeterson)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -29,7 +29,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 9 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 17 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 19 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 11 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 9 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)

package/knowledge/sessions/2026-08-17-Department-Revert-sking.md

@@ -0,0 +1,101 @@
+---
+type: session
+slug: Department-Revert
+title: NYC DOE ticket department and technician revert loop
+author: sking
+repos: [worker, library, dbchanges]
+framework: "1.0"
+client: nycdoe
+status: active
+created: 2026-08-17
+updated: 2026-08-17
+---
+
+# Session: Department-Revert
+**Date:** 2026-08-17
+**Project/Repo:** worker + library + dbchanges (1.0)
+**Task:** Root-cause why NYC DOE repair order 838745 (ServiceNow INC2234900) kept reverting its assigned technician and department in both TogaDesk and ServiceNow, and prevent it for all tickets.
+
+---
+
+## What WORKED
+
+- **Root cause found via production DB forensics, not code reading.** `repair_order_history` for repair 838745 showed the *same* correction applied four times: `Department: DOE Calls Borough -> DOE Manhattan Borough` plus `Technician unassigned: CJackson64@schools.nyc.gov`. The department can only move *from* Calls Borough repeatedly if something silently reset it *to* Calls Borough in between — and that something wrote no history row. This framing is what cracked it.
+- **Three defects identified in `worker/crons/sync/nycdoe/process_tickets.php`** (inbound cron, `*/15`, registered `worker/schedules/cron.worker.sync.json:606`):
+  1. Department overwritten unconditionally on every inbound update, with no comparison to local state — unlike status, which already had an anti-downgrade rank guard directly below it.
+  2. `$ticketDepartment` never reset between `do/while` iterations, so a ticket with an empty / unmapped / `SD QA` `assignment_group` silently inherited the **previous ticket's** department *and* `contractId`.
+  3. Technicians resolved against `people.name` while ServiceNow sends an **email** (`u_technician`). The lookup could therefore only match a row whose *name* was an email — an orphan the cron itself auto-created. It only ever INSERTed, never removed, and used `fetchOne()` where it needed every technician on the order.
+- **Newest-edit-wins guard verified against live data.** SQL returned `guard_allows_overwrite = 0` for 838745 (local `dtUpdated` epoch 1786558258 vs SNOW `sys_updated_on` 1786541919 — local ~4.5h newer). Post-deploy re-check: `ticketDepartmentId = 60` held, and **0** department history rows since 2026-08-13 (it had been flipping ~daily).
+- **Timezone assumption verified before relying on it.** DB session and global `time_zone` are `US/Central`; framework `_.php` forces `America/Chicago`. Same zone, so the epoch comparison is valid. A mismatch here would have made the guard wrong by hours.
+- **Loop-reset contract validated by reimplementation** — pre-fix logic produces `[60, 60]` across two tickets, post-fix produces `[60, null]`. Confirms the cross-ticket contamination was real, not theoretical.
+- **Closed-status prefix matching validated against every real status.** `WORK_IN_PROGRESS_DIAGNOSTIC_COMPLETE` contains "COMPLETE" but `LIKE 'COMPLETE%'` correctly excludes it. A substring match would have frozen 551 in-progress orders. Now pinned by a test.
+- **Orphan scale measured:** 105 orphan `people` rows (name IS an email, no email, no sys_id); 394 assigned technicians with no `referenceId`; 161 resolvable; 58 missing email. Reference case: people **56271** (`CJackson64@schools.nyc.gov`, 190 orders) vs real Calvin Jackson **9781** (`cjackson@togatech.com`, sys_id `775fafea…d43ed`, 799 orders), with duplicate **10225** sharing that sys_id.
+- **Phase 1 + 2 shipped and merged:** dbchanges#264, library#861, worker#1696. Migration has been RUN — `people.serviceNowEmail` exists (varchar, nullable, `MUL`), `referenceId` now indexed, `email` still `UNI` and untouched, and the migration's own acceptance criterion met exactly: **0 populated of 54,528 rows**.
+- **Orphan spread has stopped.** Newest order carrying an orphan is `2026-08-13 08:45:03`; totals fell 10,111 -> 9,934 orders and 1,024 -> 822 open assignments. Remaining orphan links are leftover state, not active damage.
+- **Schema-guard PRs opened:** library#863 (`App_Database::columnExists()`) and worker#1697 (both crons degrade to `people.email`).
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **`php -l` cannot be run on this machine.** `which php` -> `php not found`; no `docker` either. Every PHP file in this work is **syntax-unverified**. Do not claim lint passed. Structural brace/paren balance checks were used as a weak substitute.
+- **Naive brace-balance checking produces false positives.** `library/app/api/nycdoev2.php` reports `curly=1` and `library/app/database.php` reports `paren=1` — both are **pre-existing at HEAD**, artifacts of the comment/string stripper, not real imbalances. Always diff the imbalance against `git show HEAD:<file>` before believing it.
+- **Grouping a classification `CASE` by its alias returns duplicate group labels.** The first orphan-classification query returned `MISSING_REFERENCE_ID` twice with different counts and zero `ORPHAN_EMAIL_AS_NAME`, because the `repair_order_technicians` join fans out per assignment. Fix: dedupe per `people.id` in a derived table first, then aggregate. Correct numbers only came out after that.
+- **`git checkout -b <x> origin/_main` fails: `fatal: couldn't find remote ref _main`.** These repos use **`_production`** as the default branch, not `_main`, despite the team git-workflow rule naming `_main`. `origin/HEAD -> origin/_production`.
+- **Branching from a stale `origin/_production` caused a conflicted stash pop** (`UU` on both cron files). `git show origin/_production:…| grep -c serviceNowEmail` returned `0` even though worker#1696 was merged. **Always `git fetch origin` before cutting a branch off a recently merged base.** Recovery was `git reset --hard origin/_production` + re-apply (stash preserved throughout).
+- **`COALESCE(serviceNowEmail, email)` was the wrong shape** — it makes the two addresses mutually exclusive, so a technician resolvable today could stop resolving. Replaced with a two-pass build that indexes BOTH keys, ServiceNow address winning on collision.
+- **Wrong claim, corrected: "zero technicians have a schools.nyc.gov address."** 14,162 `people` rows DO have one in `email` — they are DOE **requesters**, not technicians. Among *assigned technicians*: 0 in `email`, 41 in `name`. Always state which column.
+- **Wrong claim, corrected: "182 queued is safely below `MAX_TICKETS = 200`."** That guard tests `$res->num_rows > 200` against a `SELECT COUNT(...)` query, which always returns **1 row** — so it never fires at any queue depth. Dead code, not a safety valve.
+- **A code deploy ahead of its migration takes the sync down silently.** worker#1696 merged **11:02 CDT**; last successful `process_tickets` run **11:01:36 CDT**. `Unknown column 'people.serviceNowEmail'` every 15 min for **2h34m**, 182 incidents queued. `import_inc` kept succeeding the whole time, so nothing looked broken from outside. Merging a dbchanges PR is NOT the same as running the migration.
+
+## Not tried yet (candidates for next session)
+
+- **Run `worker/crons/sync/nycdoe/backfill_technician_identities.php`** — dry run, review CSV, then `--apply`. Requires the worker host (PHP + ServiceNow credentials). Not runnable from a dev box.
+- **History logging for cron-driven department/technician changes** — highest-leverage remaining mitigation; the absence of it is why this bug survived weeks.
+- **Queue-depth alerting** on `NYCDOETickets.dtProcessed` staleness, and alerting on the new `unmatched u_technician email` / `no ServiceNow sys_id` log lines.
+- **Fix the `MAX_TICKETS` `num_rows` bug** in `process_tickets.php`.
+- **Model-level column guard** — `App_Model` builds SELECT/UPDATE from declared fields, so `App_Model_TogaDesk_People` would still break if `serviceNowEmail` were absent. `columnExists()` only guards raw SQL.
+- **`referenceId` backfill** for the 132 technicians with no sys_id (outbound cannot name them to SNOW).
+- **`togadesk/desk/includes/controllers/actions/central/assignDepartment.php:5-16`** — silently deletes ALL technicians whenever a department is set, with no history row.
+- **`bulkEditOnsiteServiceTickets.php:51-53`** — calls `->save()` where it means `->delete()`, so bulk unassignment silently no-ops.
+- **`togadesk/desk/includes/controllers/data/central/view.php`** — interpolates `$_GET['id']` raw into SQL at L22, L45, L105, L182, L343.
+- **Rotate the ServiceNow OAuth credentials** hardcoded in plaintext at `library/app/api/nycdoev2.php:36-50` (client id / secret / refresh token for both stage and production). Pre-existing, committed, untouched by this work. Treat as compromised per the team security rule.
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `worker/crons/sync/nycdoe/process_tickets.php` | MERGED (#1696) + PR #1697 | Newest-wins dept guard, per-tick state reset, email-based technician matching, no auto-create. #1697 adds the `columnExists` fallback. |
+| `worker/crons/sync/nycdoe/send_ticket_updates.php` | MERGED (#1696) + PR #1697 | Compares against `serviceNowEmail` w/ `email` fallback; no longer blanks `u_technician` when sys_id missing (logged no-op). |
+| `worker/crons/sync/nycdoe/report_technician_identities.php` | MERGED (#1696), NEVER RUN | Read-only classifier. Manual, unscheduled. |
+| `worker/crons/sync/nycdoe/backfill_technician_identities.php` | MERGED (#1696), NEVER RUN | Dry-run default, `--apply` writes. Needs worker host. |
+| `worker/crons/sync/nycdoe/test_assignment_revert_guard.php` | MERGED (#1696), NEVER RUN | Asserts A–F. Read-only, exits non-zero on failure. |
+| `library/app/model/togadesk/people.php` | MERGED (#861) | Declares `$serviceNowEmail`. |
+| `library/app/api/nycdoev2.php` | MERGED (#861) | Adds `getUserByEmail()`, mirroring the zero-caller `getUserSysIdByName()`. |
+| `library/app/database.php` | PR #863 OPEN | Adds `App_Database::columnExists()`, request-cached. |
+| `dbchanges/TOGaDeskSupport/SK/2026-08-12-add-people-servicenow-email.sql` | MERGED (#264) + **RUN in prod** | Column + 2 indexes. Verified: 0 populated of 54,528. |
+
+Untouched and NOT mine, left alone deliberately: `library/app/api/carrier/ups.php` (uncommitted on `hotfix/nycdoe-duplicate-unit-creation`), `worker/crons/sync/nycdoe/test_po168215_receipt_resolution.php` (untracked).
+
+## Decisions made
+
+- **Newest-edit-wins** for department/technician conflict. Rejected "ServiceNow authoritative" (would require removing the fields from the TogaDesk UI or techs keep losing edits) and "TogaDesk authoritative" (drifts when DOE legitimately reroutes). Mirrors the existing status anti-downgrade guard. 60s clock-skew margin because the two timestamps come from different clocks.
+- **Dedicated `people.serviceNowEmail` column.** Rejected overwriting `people.email` — it is UNIQUE, gates login/password-reset on `count(...) == 1` (a collision locks the account out), addresses ~10 notification send sites, and the AD sync **rewrites it every run** so the value would not persist. Rejected reusing `referenceId` (already overloaded: SNOW sys_id for DOE, TOGA2 contact UUID in `toga2.php`) and `ldap_user`.
+- **Index BOTH email columns rather than `COALESCE`.** Guarantees no technician who resolves today stops resolving, before any backfill. Pinned by `test_technician_still_resolves_via_people_email_when_column_is_null()`.
+- **Non-unique index** on `serviceNowEmail` — a UNIQUE index would break the AD sync insert path the same way `email` already does.
+- **ServiceNow `sys_id` as the mapping source**, matched locally on `referenceId`. Rejected name/surname heuristics: `CJackson64` fits four real Jacksons (Calvin, Cecilia, Cari, Charles). Backfill refuses to act on ambiguity rather than guessing.
+- **Repoint open orders only** (968 at planning, 822 now). Closed orders (9,143) keep their historical technician — already invoiced and signed off.
+- **Deactivate orphans, never delete** — history rows still reference them.
+- **Outbound no longer blanks `u_technician`** when a technician has no sys_id; that wipe is the outbound half of the same reversion bug. Two-line revert if reviewers disagree.
+- **Guard degrades rather than fails fast** — falling back to `people.email` keeps the sync alive; failing fast would have produced the same 2h34m outage with a nicer message.
+
+## Blockers
+
+- **No PHP runtime on the dev machine.** `php -l` has never run against any file in this work, and none of the three new scripts have been executed. Stated explicitly in every PR.
+- **Backfill cannot be run from a dev box** — needs the worker host with ServiceNow credentials.
+- **library#863 must merge before worker#1697** (the worker code calls `App_Database::columnExists()`).
+
+## Exact next step
+
+> Merge **library#863** first, then **worker#1697**. Then on the **worker host** run `php crons/sync/nycdoe/backfill_technician_identities.php` (dry run — no `--apply`), read the CSV written to the cache folder as `<date>-nycdoe-technician-backfill-dryrun.csv`, and check the `NO_LOCAL_PERSON` and `AMBIGUOUS_LOCAL_MATCH` buckets — not just `RESOLVED` — before re-running with `--apply`.
+
+---
+_Saved by /session-save on 2026-08-17_

package/package.json

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