toga-ai 1.0.802 → 1.0.804

package/.claude/settings.json

@@ -70,6 +70,16 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/design-fidelity-reminder.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-13
+updated: 2026-09-14
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -441,6 +441,54 @@ true all use `ZERO_DOLLAR_HOLD` detection.
 **Status: written, NOT committed and NOT deployed** as of 2026-09-08. Touches `worker` and `library`,
 so both deploy together (the standing rule for this pair).
 
+### ⚠ An OUT-OF-SCOPE transfer-order destination customer wedged INVENTORY_ADJUSTMENTS — the importer now SKIPS it (fixed + deployed 2026-09-14)
+
+The INVENTORY_ADJUSTMENTS section froze at `1-RUNNING` (window shrinking) on NYCHH because a
+transfer-order-backed fulfillment imported by its on-demand cascade hit
+`POST /v2/transfer-orders` → **EV-10 "Column 'destinationLocationId' cannot be null"** every run.
+
+- **Root cause:** on a stocking-SO transfer order the **destination** resolves from the NetSuite
+  **customer** → `Locations.c_netsuiteInternalCustomerId`. The offending order's customer was **not
+  in scope** — no client `Locations` row — so the destination was omitted and the NOT NULL insert
+  1048'd. The **origin** (the warehouse) resolved fine.
+- **How an out-of-scope customer gets there:** the INVENTORY_ADJUSTMENTS cascade scopes by
+  **warehouse**, then imports the referenced fulfillment whose sales order can belong to a
+  **different** customer. A shared warehouse (e.g. NYCHH's HQ) fulfills for many customers, so
+  out-of-scope orders follow.
+- **"In the Customers table" is NOT a tenant-scope signal.** The offending customer existed in the
+  client's `Customers` table but had no `Locations` row. The reliable in-scope test is **"maps to a
+  client Location"**, not "is in Customers".
+- **Fix (skip, don't force):** `App_Api_Toga2::syncTransferOrderFromNetsuite()` now `error_log`s and
+  `return null`s when the destination customer maps to no client Location, instead of POSTing a null
+  destination. Two log messages distinguish **out-of-scope customer** from **in-scope but no Location
+  (backfill a Location)**. Destination resolves **before** origin and the skip runs first, so a
+  skipped order writes nothing (no stray origin-warehouse Location row). The cascade
+  (`syncItemFulfillmentFromNetsuite` returns the fulfillment uuid or null;
+  `attachInventoryAdjustmentToItemFulfillment` treats null as nothing-to-link) skips cleanly on the
+  null instead of re-throwing at the fulfillment item-match. **No** empty-map guard: an empty
+  customer→Location map is a real warehouse-only-client state where skip-with-loud-log is correct.
+  Full detail on the [NYCHH transfer-order import doc](../../../clients/nychh/features/netsuite-transfer-order-import.md).
+
+### ⚠ A shared library function signature has THREE call sites — one is a DIRECT cron call (grep ALL repos)
+
+The fix above added a param to `syncTransferOrderFromNetsuite()`. Only the two **library** callers
+(`library/app/api/toga2.php:923` from `syncSalesOrder`, `:4984` from the `syncItemFulfillment`
+cascade) were updated. The **third** caller is a **direct cron call** in this engine —
+`common_sync_togasupply.php:782` (the SALES_ORDERS section) — and it still passed 7 args, so
+SALES_ORDERS froze at `1-RUNNING` with `Logs.Event` issue **754** *"Too few arguments to function
+`App_Api_Toga2::syncTransferOrderFromNetsuite()`, 7 passed … at least 8 expected"*. It surfaced only
+when SALES_ORDERS ran; INVENTORY_ADJUSTMENTS reaches the function via the library-internal callers.
+Fixed by adding the 3rd arg at `:782`.
+
+> **Lesson:** when changing a shared **library** function signature, **grep ALL repos** (library +
+> worker) for callers. Worker crons call library classes through the autoloader with **no `require`**,
+> so an import/`require` search misses the cron call sites. `php -l` on the library file also will not
+> catch a stale caller in another repo.
+
+Also corrected two stale comments in `common_sync_togasupply.php` (ITEM_FULFILLMENTS and
+INVENTORY_ADJUSTMENTS sections) that claimed a per-record/per-client try/catch that no longer exists
+(all such catches were removed 2026-08-27 — the sync fails loud).
+
 ### WARNING: transfer-order status refresh is nested INSIDE `IS_ENABLED_INTEGRATION_SALES_ORDERS`
 
 Turning sales orders off silently turns **transfer-order status updates** off too - the refresh lives

package/knowledge/clients/nychh/features/netsuite-transfer-order-import.md

@@ -6,7 +6,7 @@ project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-13
+updated: 2026-09-14
 owners: [jcardinal, bala, rgirish]
 files:
   - library/app/api/toga2.php
@@ -122,14 +122,74 @@ full evidence table (location 75 → warehouse 117, the only `allowSending` sour
 locations carry a customer id, 7 carry a location id) is in
 [NYCHH TransferOrder → NetSuite push](./transfer-order-netsuite-push.md).
 
-> **⚠ OPEN, not fixed (2026-09-13) — a transfer order's DESTINATION location does not resolve, and
-> it is now collapsing the INVENTORY_ADJUSTMENTS section.** `TransferOrders.destinationLocationId` is
-> also NOT NULL. The INVENTORY_ADJUSTMENTS section (window shrinking, stuck `RUNNING`) runs an
-> on-demand cascade that imports a transfer-order-backed fulfillment, and the
-> `POST /v2/transfer-orders` for **TO 277871** (`c_netsuiteInternalSalesOrderId` **7102750**) fails
-> **EV-10 "Column 'destinationLocationId' cannot be null"** — the **origin** resolved but the
-> **destination** did not. This is a **separate** destination-resolution bug from the origin
-> fallback above (and from the 128829 no-location edge case). Next task; not yet root-caused.
+### ⚠ RESOLVED (2026-09-14) — an OUT-OF-SCOPE destination customer was wedging INVENTORY_ADJUSTMENTS; the importer now SKIPS such transfer orders
+
+`TransferOrders.destinationLocationId` is also NOT NULL, and the INVENTORY_ADJUSTMENTS section was
+stuck `RUNNING` (window shrinking) because `POST /v2/transfer-orders` for **TO 277871**
+(SO **7102750** / tranId **277871**) failed **EV-10 "Column 'destinationLocationId' cannot be null"**
+every run — origin resolved, destination did not.
+
+**Root cause (proven in prod):** the destination resolves from the NetSuite **customer** →
+`Locations.c_netsuiteInternalCustomerId`. TO 277871's customer (entity) is **3997 "1896 Laurel Hill
+Management, LLC"** — **not** a NYCHH customer, no parent in NetSuite, and **no row in
+`Client_Nychh.Locations`**. So the destination could not resolve, `destinationLocation` was omitted,
+and the NOT NULL insert 1048'd. The **origin** resolved fine (line location 6 "HQ" → warehouse
+Location 78). With fail-loud + no per-record try/catch, the one bad record threw every run and shrank
+the adaptive window → the whole section wedged.
+
+**Why an out-of-scope customer reaches NYCHH at all:** the INVENTORY_ADJUSTMENTS cascade scopes by
+**warehouse** (an adjustment at the shared **HQ** warehouse, loc 6, maps to NYCHH), then imports the
+referenced fulfillment whose sales order belongs to a **different** customer. HQ fulfills for many
+customers, so more out-of-scope orders follow.
+
+> **Key data fact — "in the Customers table" is NOT a tenant-scope signal.** Customer 3997 DOES exist
+> in `Client_Nychh.Customers` (id 19) but has **no Location**. The reliable in-scope test is **"maps
+> to a client Location"** (`c_netsuiteInternalCustomerId` on a `Locations` row), not "is in
+> Customers".
+
+**Fix (developer decision "skip out-of-scope TOs"; CTO AGREE, php-reviewer clean, cso SAFE TO SHIP):**
+`App_Api_Toga2::syncTransferOrderFromNetsuite()` now **SKIPS** (`error_log` + `return null`) when a
+stocking-SO transfer order's destination customer maps to no client Location, instead of POSTing a
+null destination. Two distinct log messages: **"out-of-scope customer"** vs **"in-scope but no
+Location (backfill a Location)"**. A new 3rd param
+`$lookupCustomerByNetsuiteCustomerInternalId` is used **only** to classify the log line.
+
+- **Destination resolves BEFORE origin, and the skip runs first** (cso refinement) — a skipped order
+  writes nothing, so no stray origin-warehouse `Location` row is left behind.
+- **Cascade skips cleanly on the null return.** `syncItemFulfillmentFromNetsuite` returns the
+  fulfillment uuid on a real import and **null** when not imported;
+  `attachInventoryAdjustmentToItemFulfillment` treats null as "nothing to link" (no throw) instead of
+  the old "still not found" throw that would just re-wedge the crash at the fulfillment item-match.
+- **No `!empty(customer→Location map)` guard** (cso refinement) — the map is built in the cron's
+  up-front LOOKUPS phase and a failure there aborts the whole cron, so by sync time the map has
+  loaded. An empty map is a **real** state (a warehouse-only client) where skip-with-loud-log is
+  correct and freezing is wrong.
+
+**VERIFIED in prod:** after the library deploy the INVENTORY_ADJUSTMENTS cursor advanced past the
+blocker and ran forward through most of 2026; skipped TOs logged, no more EV-10 destination wedge.
+
+This is **separate** from the origin fallback above and from the 128829 no-location edge case.
+
+#### Follow-on regression: the added param broke a THIRD call site → SALES_ORDERS froze at 1-RUNNING
+
+`syncTransferOrderFromNetsuite()` has **three** callers, not two: `library/app/api/toga2.php:923`
+(from `syncSalesOrder`) and `:4984` (the `syncItemFulfillment` cascade), **plus a DIRECT cron call**
+in `worker/crons/toga2/netsuite/common_sync_togasupply.php:782` (the SALES_ORDERS section). The skip
+fix added a param but updated only the **two library callers**; the worker cron still passed 7 args →
+`Logs.Event` issue **754**: *"Too few arguments to function
+`App_Api_Toga2::syncTransferOrderFromNetsuite()`, 7 passed in
+`crons/toga2/netsuite/common_sync_togasupply.php` on line 789 and at least 8 expected."* It surfaced
+only when SALES_ORDERS ran (cursors reset to recheck), because INVENTORY_ADJUSTMENTS reaches the
+function through the library-internal callers. **Fix:** added the missing 3rd arg
+`$lookupCustomerByClientUuidAndNetsuiteCustomerInternalId[$uuidClient]` to the `:782` call.
+
+> **Lesson (recorded on the shared engine doc too):** when you change a shared **library** function
+> signature, **grep ALL repos** (library + worker) for callers — worker crons call library classes
+> via the autoloader with **no `require`**, so an import search misses the cron call sites.
+
+**Deploy:** the library change (the skip) is deployed and verified over many cron cycles; the worker
+change (the missing 3rd arg + two stale-comment fixes) is the current fix — **redeploy worker** to
+pick it up.
 
 ## Item-fulfillment transfer-order line link
 
@@ -324,12 +384,27 @@ item receipts replays about two years unless it is rewound forward first.
 
 ## Change history
 
-- 2026-09-13 - **OPEN: INVENTORY_ADJUSTMENTS collapsing on an unresolved transfer-order
-  DESTINATION.** The section's on-demand cascade imports a transfer-order-backed fulfillment, and
-  `POST /v2/transfer-orders` for **TO 277871** (`c_netsuiteInternalSalesOrderId` **7102750**) fails
-  **EV-10 "Column 'destinationLocationId' cannot be null"** — origin resolved, destination did not.
-  Separate from the origin fallback and the 128829 no-location case; next task, not yet root-caused.
-  Recorded in the origin/destination section. (jcardinal)
+- 2026-09-14 - **RESOLVED: the INVENTORY_ADJUSTMENTS destination wedge.** Root cause (prod): TO 277871
+  (SO 7102750) has customer **3997 "1896 Laurel Hill Management, LLC"** — not a NYCHH customer and with
+  **no `Client_Nychh.Locations` row**, so the destination never resolved and the NOT NULL insert 1048'd
+  (EV-10) every run. It reaches NYCHH because the INVENTORY_ADJUSTMENTS cascade scopes by the shared HQ
+  **warehouse** (loc 6) then imports a fulfillment for a different customer. Key fact: customer 3997 IS
+  in `Client_Nychh.Customers` (id 19) but has no Location — "maps to a client Location" is the tenant
+  signal, not "is in Customers". **Fix** (skip out-of-scope TOs; CTO AGREE, php-reviewer clean, cso SAFE
+  TO SHIP): `syncTransferOrderFromNetsuite()` now SKIPS (error_log + return null) when the destination
+  customer maps to no Location, with two log messages (out-of-scope vs in-scope-no-Location); new 3rd
+  param `$lookupCustomerByNetsuiteCustomerInternalId` classifies the log; destination resolves before
+  origin and the skip runs first (no stray origin row); the cascade treats the null return as
+  nothing-to-link (no re-wedge). Library deployed + verified (cursor advanced through 2026).
+  **Follow-on:** the added param broke a THIRD, direct cron call site
+  (`common_sync_togasupply.php:782`, SALES_ORDERS) → issue 754 "Too few arguments" → froze SALES_ORDERS;
+  fixed by passing the 3rd arg there. Also fixed two stale comments claiming a per-record try/catch that
+  was removed 2026-08-27. Redeploy **worker** for the cron fix. (jcardinal)
+- 2026-09-13 - **OPEN (now resolved 2026-09-14, above): INVENTORY_ADJUSTMENTS collapsing on an
+  unresolved transfer-order DESTINATION.** The section's on-demand cascade imports a
+  transfer-order-backed fulfillment, and `POST /v2/transfer-orders` for **TO 277871**
+  (`c_netsuiteInternalSalesOrderId` **7102750**) failed **EV-10 "Column 'destinationLocationId' cannot
+  be null"** — origin resolved, destination did not. (jcardinal)
 - 2026-09-10 - Recorded that the import concentrates **1,832 of 1,939** transfer orders on catch-all
   destination **location 2**, all with `createdByUserId` NULL (so none came from the Create Transfer
   Order screen), and that whether it should resolve the real hospital instead is still open with the

package/knowledge/clients/nychh/profile.md

@@ -18,7 +18,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-09-13
+updated: 2026-09-14
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
@@ -138,11 +138,15 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   unit. Engine + shim detail:
   [per-client sync](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md),
   [SuiteQL/REST shim](../../1.0/apps/library/features/netsuite-suiteql-rest-shim.md).
-- 🚩 **OPEN (2026-09-13): INVENTORY_ADJUSTMENTS collapsing on an unresolved transfer-order
-  DESTINATION.** The section's on-demand cascade imports a transfer-order-backed fulfillment and
-  `POST /v2/transfer-orders` for **TO 277871** (`c_netsuiteInternalSalesOrderId` 7102750) fails
-  **EV-10 "destinationLocationId cannot be null"** — origin resolved, destination did not. Separate
-  destination-resolution bug; next task. See
+- **RESOLVED (2026-09-14): INVENTORY_ADJUSTMENTS destination wedge.** `POST /v2/transfer-orders` for
+  **TO 277871** (SO 7102750) failed **EV-10 "destinationLocationId cannot be null"** every run because
+  its customer **3997 "1896 Laurel Hill Management, LLC"** is not a NYCHH customer and has **no
+  `Client_Nychh.Locations` row** (though it IS in `Customers`, id 19 — "maps to a Location" is the
+  scope signal, not "is in Customers"). It reached NYCHH because the adjustment cascade scopes by the
+  shared HQ warehouse then imports a fulfillment for a different customer. Fix: the importer now SKIPS
+  out-of-scope transfer orders (loud log) instead of forcing a null destination; library deployed +
+  verified. A follow-on regression from the added param froze SALES_ORDERS (a 3rd, direct cron call
+  site, issue 754 "Too few arguments") — fixed; **redeploy worker**. See
   [NYCHH NetSuite → TransferOrders import](./features/netsuite-transfer-order-import.md).
 - **NYCHH sync scope + data-gap scale + backfill approach (2026-09-09).**
   - **Scope = 22 NetSuite customers:** parent **28908** "NYC Health + Hospitals" + 21 hospital child

package/package.json

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

package/scripts/hooks/design-fidelity-reminder.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * design-fidelity-reminder.js — PRE-EDIT enforcement of the Design Contract discipline.
+ *
+ * Why this exists: on Desk (and the other 2.0 React apps) the model keeps improvising
+ * UI — inventing button text, helper lines, field order and labels instead of matching
+ * the designer's on-disk design. That drift ships UIs that "function" but do not match
+ * what Matt designed, and the developer has to catch it every time. A rule in a file is
+ * passive; over a long session the model slides back to improvising. This is the
+ * mechanical backstop, modeled on plain-talk.js.
+ *
+ * How it works: registered on PreToolUse for Edit|Write|MultiEdit. Just before the model
+ * edits a UI source file — a path under a `src/` tree ending .tsx / .jsx / .css — it prints
+ * a short <system-reminder> to stdout with the Design Contract rules, so the discipline is
+ * in context at the moment the UI is written. On any non-UI file it stays silent.
+ *
+ * It never blocks. It always exits 0 — a reminder must never stop or deny an edit. It
+ * fails open on any error: a crashing nudge must never brick a session. Per team hook
+ * convention DENY/error text goes to STDERR — this hook never denies, so it never uses it.
+ *
+ * Escape hatch: set TOGA_DESIGN_FIDELITY_DISABLED=1 to silence the reminder.
+ */
+
+const fs = require('fs');
+
+/* Read the CC hook payload. PreToolUse delivers the tool input on stdin as
+ * { tool_name, tool_input: { file_path, ... } }; fall back to the CLAUDE_TOOL_INPUT env
+ * (what the sibling PostToolUse reminders read) and to a top-level file_path. */
+function readFilePath() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+
+  let data = {};
+  if (raw && raw.trim()) {
+    try { data = JSON.parse(raw); } catch (e) { data = {}; }
+  }
+
+  let fp =
+    (data.tool_input && typeof data.tool_input.file_path === 'string' && data.tool_input.file_path) ||
+    (typeof data.file_path === 'string' && data.file_path) ||
+    '';
+
+  if (!fp && process.env.CLAUDE_TOOL_INPUT) {
+    try {
+      const env = JSON.parse(process.env.CLAUDE_TOOL_INPUT);
+      if (env && typeof env.file_path === 'string') fp = env.file_path;
+    } catch (e) { /* ignore */ }
+  }
+  return fp;
+}
+
+/* A Desk / React-app UI source file: under a `src/` tree AND ending .tsx / .jsx / .css. */
+function isUiSourceFile(filePath) {
+  if (!filePath) return false;
+  const p = filePath.replace(/\\/g, '/').toLowerCase();
+  return /\/src\//.test(p) && /\.(tsx|jsx|css)$/.test(p);
+}
+
+function reminder() {
+  return [
+    '<system-reminder>',
+    'DESIGN CONTRACT — this edit touches a UI source file. Match the designer\'s design,',
+    'do not improvise UI. Reusing a shell or making it "function" is NOT fidelity.',
+    '',
+    '  1. The on-disk design is the authority. Open the exact design source file FIRST and',
+    '     build from it — match its LAYOUT/placement, not just pixels.',
+    '  2. Build to a written Design Contract: every field + its order, each label/placeholder,',
+    '     required flags, button text, modal size/layout, and the header/footer.',
+    '  3. Invent NOTHING user-visible — button text, helper/info lines, labels, required flags.',
+    '     Copy comes from the design + Surface/settings. If it is not in the design, ASK.',
+    '  4. Design-vs-data conflict → STOP and ask. Do not decide it yourself.',
+    '  5. No self-sign-off. Hand the developer a labeled diff (mine vs the design). "It',
+    '     functions" is not fidelity.',
+    '</system-reminder>',
+  ].join('\n');
+}
+
+function main() {
+  if (process.env.TOGA_DESIGN_FIDELITY_DISABLED === '1') process.exit(0);
+
+  const filePath = readFilePath();
+
+  if (isUiSourceFile(filePath)) {
+    // Inject the reminder into the model's context via the PreToolUse additionalContext
+    // channel (raw stdout on PreToolUse only shows in transcript, not context). Non-blocking:
+    // additionalContext adds context, it does not deny the edit.
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: reminder(),
+      },
+    }));
+  }
+  process.exit(0);
+}
+
+try { main(); } catch (e) { process.exit(0); } // fail-open: never block or brick an edit