toga-ai 1.0.55 → 1.0.56

package/knowledge/INDEX.md

@@ -9,7 +9,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 4 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 5 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 5 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

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

@@ -4,4 +4,5 @@
 |-----|-----------|---------|-------|
 | [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, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql |
 | [Compass: Item Fulfillments for Sales Order Items TableView (tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | The Compass TableView `item-fulfillments-for-sales-order-items` (`TableViews.id = 13` in Client_Compass) was rebuilt as part of the tracking-number bridge migra | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.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 |
 | [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/mits-po-to-so-item-linking.md

@@ -0,0 +1,79 @@
+---
+title: Compass MITS PO → SO Item Linking
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-06-11
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Compass/PurchaseOrder.php
+related:
+  - asn-to-item-fulfillment.md
+---
+
+## Summary
+MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order
+(`mitsSalesOrder`). `_Model_Compass_PurchaseOrder` links each `PurchaseOrderItem` to the
+`SalesOrderItem` it fulfills via the `SalesOrderItems_PurchaseOrderItems` bridge. There are
+**two distinct linking paths** depending on order type, and conflating them caused a
+production data-integrity bug.
+
+## Key files / entry points
+- `_underscore/Model/Compass/PurchaseOrder.php` — `prePost` (SA path + MR via `handleMrOrder`)
+  and `postPost` (link creation).
+- USA/Canada subclasses (`Model/Compass/Usa|Canada/PurchaseOrder.php`) are empty and inherit
+  this behavior — edit the parent.
+
+## How it works
+- **SA orders (normal):** each inbound PO item carries `createdFromSalesOrderItem.lineNumber`
+  (the MITS line, which includes configuration-line offsets). `prePost` remaps it to the real
+  SO `lineNumber` via `$mapIncomingLineNumbersToOriginalLineNumbers` and builds
+  `salesOrderItemPurchaseOrderItems` on the payload, so the **correct** bridge rows are created
+  by the normal nested API write. This is the authoritative SA linkage.
+- **MR orders (`mitsSalesOrder` starts with `MR`):** `prePost` calls `handleMrOrder` and
+  returns early. `handleMrOrder` creates/appends the SO from the PO items, **strips**
+  `createdFromSalesOrderItem`, and deliberately **aligns** SO and PO `lineNumber`s. It does
+  NOT build the item bridge — so the `postPost` lineNumber-match pass is the **only** (and
+  correct) MR linking mechanism.
+
+## Data model
+- `SalesOrderItems_PurchaseOrderItems` (`Client_Compass`): `uuid`, `salesOrderItemId`,
+  `purchaseOrderItemId`. One row per (SO item, PO item) the PO fulfills.
+- A PO item's `lineNumber` is **PO-local (1..N per PO)** — NOT the SO line number.
+
+## Client variations
+USA and Canada share the parent handler unchanged.
+
+## Gotchas / known issues
+- **Spurious cross-part links from the `postPost` lineNumber join (fixed 2026-06-11).** The
+  `postPost` link pass matched `SalesOrderItems.lineNumber = PurchaseOrderItems.lineNumber`
+  for *all* orders. For SA orders that is wrong: PO line numbers are PO-local, so whenever an
+  SO is split across multiple POs, or carries non-PO lines (freight/tax/warranty) that shift
+  the SO line numbers, the join created extra links pointing PO items at the **wrong** SO line
+  (different part). The correct SA links already existed from `prePost`; the `postPost` pass
+  only added bogus duplicates. Detection: ~40% of recent SA orders had ≥1 link where the PO
+  item's part ≠ the SO item's part. **Fix:** guard the `postPost` link block with
+  `if (static::isMrOrder($api->httpPayload))` so it runs for MR only. A link whose PO-item
+  part ≠ SO-item part is always invalid (a PO line can only fulfill the same part) — that is
+  the safe cleanup predicate for remediating historical rows.
+- **Downstream tracking-number misattribution (NOT yet fixed as of 2026-06-11).** Because
+  tracking propagation followed the (scrambled) SO↔PO linkage, tracking numbers landed on the
+  wrong IF granularity for affected SA orders. Tracking for Compass lives at
+  `ItemFulfillmentItemUnits_TrackingNumbers` and `ItemFulfillments_TrackingNumbers` (header),
+  NOT `ItemFulfillmentItems_TrackingNumbers`. Source of truth for "which tracking shipped which
+  part" is the ASN side: `AdvanceShippingNoticeItemUnits_TrackingNumbers` →
+  `AdvanceShippingNoticeItems.purchaseOrderItemId` → PO item → part. A correct remediation
+  re-derives every tracking→IF-unit attachment from that ASN truth rather than doing per-line
+  swaps (the scramble spans multiple lines, so a single swap just moves a different wrong
+  number onto the line). Example seen on SA132739: UPS `1Z8696XA0193326215` actually shipped
+  `C40QYUC-1` (SO line 4) but was attached to SO line 1 (`1000555`).
+
+## Change history
+- 2026-06-11 — Guarded `postPost` SO↔PO item linking to MR orders only; SA links come solely
+  from `prePost`'s `createdFromSalesOrderItem` remap. Fixes spurious cross-part links. (jcardinal)
+
+## Related docs
+- [Compass ASN → ItemFulfillment Auto-Creation](asn-to-item-fulfillment.md)

package/package.json

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