toga-ai 1.0.129 → 1.0.131

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

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [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 |
+| [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 |
 | [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 |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |

package/knowledge/clients/compass-usa/features/asn-to-item-fulfillment.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-16
+updated: 2026-06-18
 owners: [jcardinal]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
@@ -16,6 +16,7 @@ files:
   - 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
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
 ---
@@ -54,6 +55,11 @@ the gotcha about already-fulfilled orders). Flow:
    - **`remaining <= 0`** (reconcile path, new): the tracking targets are the **existing IFIs**
      for that SOI (resolved via `ItemFulfillmentItems.salesOrderItemId` → their `itemFulfillmentId`),
      **not** an SO-number lookup — NetSuite/toga2-supply IFs are `F`-numbered, not SO-numbered.
+     As of **2026-06-18** an existing IFI that **already carries item-level tracking is skipped**
+     here (`itemFulfillmentItemHasTracking()`): reconcile only attaches onto untracked
+     out-of-band IFIs. An already-tracked, fully-fulfilled line revisited by a later ASN is a
+     vendor re-transmission and must not gain a second tracking number (see the duplicate-tracking
+     gotcha).
 4. Copy the ASN item's tracking (`AdvanceShippingNoticeItems_TrackingNumbers`) onto each target
    IFI via `POST /item-fulfillment-item-tracking-numbers` → `ItemFulfillmentItems_TrackingNumbers`
    — **idempotent** (skipped if the bridge row already exists; ASNs get re-POSTed).
@@ -176,8 +182,29 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
   `NOT EXISTS`. ~116 PO items across other Compass orders share the off-by-one fingerprint and
   are not yet repaired — a broader reviewed backfill is still outstanding.
 
+- **Duplicate tracking from vendor ASN re-transmission (root cause, fixed forward 2026-06-18)
+  — DISTINCT from the cross-line contamination above.** Compass vendors (Office Depot, Strategic
+  Systems) re-send the **same** shipment ASN file for several days; one PO can receive many ASNs
+  (e.g. SA132898 / PO `50305272-1` got 6). The first ASN takes the create path and attaches its
+  tracking; a later ASN re-listing the same, now fully-fulfilled line takes the **reconcile path**
+  and — pre-fix — attached its *different* tracking number onto the existing IFI. On a qty-1 line
+  this yields two item-level tracking rows (plus a propagated package row). Unlike the cross-line
+  bug, **both** tracking numbers here map cleanly to the correct line via their own valid ASN
+  items, so the `NOT EXISTS (ASN item with matching VendorItems.itemId)` cleanup guard does **not**
+  catch it — diagnose instead by an IFI carrying more item-level tracking numbers than its
+  fulfilled quantity. Fix: the reconcile path now skips any IFI that already has item-level
+  tracking (`itemFulfillmentItemHasTracking()`), so only untracked out-of-band IFIs receive ASN
+  tracking. The legitimate out-of-band case (IFI has no tracking, one ASN arrives) is preserved.
+  Forward-only; SA132898 repaired by `2026-06-18a` (delete the later tracking + orphaned package
+  row, keep the original; no backfill needed since the correct number is already present).
+
 ## Change history
 Dated one-liners, newest first.
+- 2026-06-18 — Reconcile path now skips IFIs that already carry item-level tracking
+  (`itemFulfillmentItemHasTracking()`), stopping duplicate/different tracking numbers from
+  vendor ASN re-transmissions piling onto fully-fulfilled lines (qty-1 SA132898 / USB31CC1 had
+  2). Distinct root cause from the 2026-06-16 cross-line contamination. SA132898 repaired by
+  `2026-06-18a` (cleanup-only; original tracking already correct). (jcardinal)
 - 2026-06-16 — Identified cross-line tracking contamination root cause: bad
   `SalesOrderItems_PurchaseOrderItems` rows (PO-local lineNumber collision in
   `_Model_Compass_PurchaseOrder`, fixed forward 2026-06-11 `ec935478`; and the worker ODP-PO

package/knowledge/clients/tow-foundation/INDEX.md

@@ -2,5 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [Credit Card Receipt Processing](features/receipt-processing.md) | 2.0 | Automated processing of credit card receipts uploaded to SharePoint. | worker2/Worker/Client/TowFoundation.php, worker2/Worker/Client/TowFoundation/ProcessReceipts.php |
+| [Credit Card Receipt Processing](features/receipt-processing.md) | 2.0 | Automated processing of credit card receipts uploaded to SharePoint. | worker2/Worker/Client/TowFoundation.php, worker2/Worker/Client/TowFoundation/ProcessReceipts.php, worker2/Worker/Client/TowFoundation/TowFoundationVendors.php |
 | [Tow Foundation](profile.md) | 2.0 | Tow Foundation is a nonprofit client. |  |

package/knowledge/clients/tow-foundation/features/receipt-processing.md

@@ -5,11 +5,12 @@ project: Worker
 client: tow-foundation
 type: client-feature
 status: active
-updated: 2026-06-12
+updated: 2026-06-18
 owners: ["rgirish"]
 files:
   - worker2/Worker/Client/TowFoundation.php
   - worker2/Worker/Client/TowFoundation/ProcessReceipts.php
+  - worker2/Worker/Client/TowFoundation/TowFoundationVendors.php
 related:
   - clients/tow-foundation/profile.md
 ---
@@ -23,7 +24,7 @@ Excel file per person, uploads it to SharePoint, and sends a summary email.
 
 Invocation: `{"action": "Client/TowFoundation/ProcessReceipts/Run", "parameters": {}}`
 
-Optional filter parameters: `limit` (int), `year` (string e.g. `"2026"`), `person` (string e.g. `"Brent Peterkin"`).
+Optional filter parameters: `limit` (int), `year` (string e.g. `"2026"`), `person` (string e.g. `"Brent Peterkin"`), `billingCycle` (string — matches the **end** of the billing-cycle folder name, e.g. `"06-03-2026"` matches `"Amex ending in 06-03-2026"`, `"Mastercard ending in 06-03-2026"`, etc.).
 
 ## Key files / entry points
 
@@ -48,7 +49,7 @@ Credit Card Receipts/
 
 1. **Auth** — OAuth2 client-credentials token from Microsoft Graph
 2. **Walk** — `walkReceiptsFolder()` enumerates all receipt files and statement Excels
-3. **Filter** — optional `$year` / `$person` / `$limit` applied to the receipt list
+3. **Filter** — optional `$year` / `$person` / `$billingCycle` / `$limit` applied to the receipt list. `$billingCycle` uses `str_ends_with()` so passing just the date (e.g. `"06-03-2026"`) matches any card type. Person folders named `"Brent Peterkin CC receipts"` are normalized to `"Brent Peterkin"` via regex strip of ` CC receipts` suffix before any map lookups.
 4. **Pre-load statements** — all billing-cycle `.xlsx` files under `reports/` are downloaded
    and parsed upfront via PhpSpreadsheet (auto-detect header row by scanning for
    description/amount keywords)
@@ -59,8 +60,9 @@ Credit Card Receipts/
    - Cross-verify amount ± $0.01 against parsed statement; if matched, override `payment_memo` with statement description
    - Build base filename (no suffix yet) and store in `$pendingRenames`
    - On extract failure → move to `Archive/exception/` immediately
-6. **Collision detection** — count base name occurrences across all pending renames
-7. **Pass 2 — Move** — for each pending rename:
+6. **Deduplication** — after Pass 1, receipts sharing identical `(personName, invoice_date, vendor_name, total)` are deduplicated; only the first is kept, the rest are logged as `DUPLICATE skipped` and dropped. This catches the same receipt uploaded twice to SharePoint.
+7. **Collision detection** — count base name occurrences across remaining pending renames
+8. **Pass 2 — Move** — for each pending rename:
    - If base name appears more than once, assign `_a`, `_b`, `_c`... suffix to **all** colliding files (including the first)
    - PATCH SharePoint to rename + move to `Archive/` (flat — no person subfolder)
 8. **Excel generation** — one `.xlsx` per person (PhpSpreadsheet); columns: Row #, Account Name, QB Vendor, Payment Amount, Date, Payment Method, Payment Memo, QB Description, Class, Category, Payment Account, Ref No.
@@ -80,6 +82,25 @@ Amex billing cycle runs 3rd-to-3rd. `computeRefNo()` returns the cycle-end date
 - Charge on or before the 3rd → cycle ends on the 3rd of the same month
 - Charge after the 3rd → cycle ends on the 3rd of the next month
 
+### QB vendor matching
+`TowFoundationVendors.php` holds 2,994 vendor names exported verbatim from Tow Foundation's
+QuickBooks vendor list (June 2026). `matchQbVendor()` runs three passes against this list:
+1. Exact match (case-insensitive)
+2. Substring match — QB name contains extracted name or vice versa (min 4 chars); picks shortest match on multiple hits
+3. `similar_text()` similarity ≥ 80% — picks highest scorer
+
+Returns the exact QB vendor string or `''` if no confident match. The AI only extracts
+`vendor_name`; QB matching is done entirely in PHP — no tokens spent per receipt on the list.
+
+To update the vendor list: re-export from QuickBooks → run the extraction script →
+replace `TowFoundationVendors.php`. The matching logic is in `matchQbVendor()` and needs no changes.
+
+### AI category values
+The AI is prompted to return **specific expense types** — e.g. `"Dining"`, `"Travel"`,
+`"Accommodation"`, `"Transportation"`, `"Office Supplies"`, `"Entertainment"`,
+`"Professional Services"`, `"Subscriptions"`. It must not use broad accounting labels
+like `"Administrative Expenses"`.
+
 ### Per-person constants
 `CLASS_MAP` and `PAYMENT_ACCOUNT_MAP` in `ProcessReceipts.php` map each cardholder's name
 to their QuickBooks Class and Payment Account strings. Ryan Farrell uses Bank of America
@@ -133,7 +154,13 @@ Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
   `Credit Card Receipts/3. QB Excel/` (not inside each person's subfolder). This folder
   exists at the root of `Credit Card Receipts/` alongside the person folders.
 
+- **Person folder name normalization** — SharePoint folders are named `"Brent Peterkin CC receipts"` but `CLASS_MAP` / `PAYMENT_ACCOUNT_MAP` keys are just `"Brent Peterkin"`. The ` CC receipts` suffix is stripped via regex in `walkReceiptsFolder()`. Without this, Class and Payment Account columns are blank for those persons.
+- **`billingCycle` filter is suffix-match, not exact** — always pass just the date portion (`"06-03-2026"`), not the full folder name. Passing the full name (`"Amex ending in 06-03-2026"`) also works but would miss Mastercard folders.
+- **Ole Mole not in QB vendor list** — as of June 2026 this vendor is not in Tow Foundation's QuickBooks, so `qb_vendor` will be blank for Ole Mole charges until they add it to QB and the vendor list is refreshed.
+- **Duplicate detection is within-run only** — if the same receipt was processed in a prior run and archived, it won't be caught. The dedup only covers receipts present in the current run's `$pendingRenames`.
+
 ## Change history
 
+- 2026-06-18 — QB vendor matching via local fuzzy match against `TowFoundationVendors.php` (2,994 vendors); AI category prompt updated to return specific types (Dining, Travel, etc.); duplicate receipt detection added (person+date+vendor+amount dedup); `billingCycle` filter parameter added (suffix-match — card-type agnostic); person folder ` CC receipts` suffix stripped so CLASS_MAP/PAYMENT_ACCOUNT_MAP resolve correctly (rgirish)
 - 2026-06-12 — QB Excel upload moved to root-level `3. QB Excel/`; Archive/exception folders flattened (no person subfolder); unsupported mime types (`application/octet-stream`) now throw ReceiptProcessingException instead of being silently skipped (rgirish)
 - 2026-06-11 — Added CC (Magdalena), BCC (devteam@togatech.com), per-cardholder Archive subfolders, Excel upload to "3. QB Excel" SharePoint folder, two-pass rename with alphabetical duplicate suffix, rename format changed to `YYYY.MM.DD Full Name_Vendor_Amount` (rgirish)

package/package.json

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