toga-ai 1.0.606 → 1.0.607

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

@@ -5,6 +5,7 @@
 | [Test (test) Architecture](architecture.md) | `test` (project **Test**) is a **repository of ad-hoc developer scripts** — not a deployed application. | test/team/ |
 | [2.0 Deployment — Per-Client SQL Generator](features/2-0-deployment-client-sql.md) | `team/2.0 deployment/generate_client_sql.php` fans a single SQL change-set out across **all 2.0 client databases**. | test/team/2.0 deployment/generate_client_sql.php, test/team/2.0 deployment/Clients_Db.txt, test/team/2.0 deployment/Client.sql |
 | [Active Directory Authentication Test](features/active-directory-auth-test.md) | `team/active_directory_authentication_test.php` is an interactive CLI tool to test **Active Directory authentication**. | test/team/active_directory_authentication_test.php |
+| [Compass retrofix2 — Retroactive Data-Fix SQL Generator](features/compass-retrofix2-sql-generator.md) | `@jeff/compass/retrofix2.php` is a standalone **1.0 `App_`** script that retroactively repairs historical Compass USA (`Client_Compass`, 2.0) order data left in | test/@jeff/compass/retrofix2.php |
 | [Create Elastic Beanstalk Environment (script)](features/create-elastic-beanstalk.md) | `team/aws/create_elastic_beanstalk.php` is a **standalone** (no `App_` framework) constants-driven PHP generator. | test/team/aws/create_elastic_beanstalk.php |
 | [Developer Generators (password, UUID)](features/dev-generators.md) | Two tiny **1.0 `App_` framework** convenience scripts for everyday developer needs. | test/team/generate_password.php, test/team/uuid.php |
 | [Forecast vs NetSuite Discrepancy Analysis](features/forecast-netsuite-discrepancy-analysis.md) | `team/forecast-netsuite/discrepancy_analysis.php` detects discrepancies between our **Forecast database** and **NetSuite** (the source of truth for all sales da | test/team/forecast-netsuite/discrepancy_analysis.php |

package/knowledge/1.0/apps/test/features/compass-retrofix2-sql-generator.md

@@ -0,0 +1,102 @@
+---
+title: Compass retrofix2 — Retroactive Data-Fix SQL Generator
+framework: "1.0"
+repo: test
+project: Test
+client: shared
+type: feature
+status: active
+updated: 2026-08-18
+owners: [jcardinal]
+files:
+  - test/@jeff/compass/retrofix2.php
+related:
+  - ../architecture.md
+  - ../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
+  - ../../../clients/compass-usa/features/mits-po-to-so-item-linking.md
+---
+
+## Summary
+
+`@jeff/compass/retrofix2.php` is a standalone **1.0 `App_`** script that retroactively repairs
+historical Compass USA (`Client_Compass`, 2.0) order data left in the wrong shape by 50+ past bugs.
+It **emits review-first `.sql`** — it never writes the DB directly. It supersedes the older sibling
+`retrofix.php` in the same folder (that one is superseded/kept only for reference). The domain facts
+it repairs against (the supply chain, item-link bridges, both fulfillment flows, over-fulfill cap)
+live in the Compass
+[order-lifecycle & data-integrity workflow](../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md);
+this doc covers the **script's structure**.
+
+## How it works
+
+`processOrder()` runs three phases per Compass SO, newest-first. **Phase ordering is load-bearing:
+Phase 0 must run before Phase 1/2** because units are **shared up the chain** (the same `Units.id`
+at every level), so unit corrections must land before Phase 2 mirrors fulfillments upward.
+
+### Phase 0 — CG-unit asset-tag merge (new)
+Reproduces retroactively what the forward fix does at `library/app/api/toga2.php` (~lines 3688–3965):
+NetSuite delivers asset tags on **separate service-item lines** whose part number contains
+`ASSETTAG` (e.g. `ODP-COMPASS-ASSETTAG1`); older Compass imports landed each asset tag as its **own
+`Units` row** whose `serialNumber` holds the CG value (e.g. `CG2000027730`), attached via
+`ItemFulfillmentItemUnits` alongside the real serialized unit on the same fulfillment. Phase 0 folds
+each duplicate CG unit into its real device.
+
+Per fulfillment, order the IFIU-attached units by `ItemFulfillmentItemUnits.id` and split into CG
+(serial starts `CG`) vs real (non-CG serialized), then:
+- **1:1** → merge (≈17,500 fulfillments).
+- **equal N:N** → order-pair and emit a `REVIEW` comment (≈7).
+- **unequal, or zero real units** → logged and skipped (≈184).
+
+Each merge emits, in order:
+1. `UPDATE Units SET assetTag = <CG serial>` on the real unit — **only if empty; never clobbers a
+   different existing tag**.
+2. Repoint `InventoryAdjustmentItemUnits.unitId` CG→real (decided: **repoint, not delete**, to
+   preserve stock history — 14,249 CG units have inventory-adjustment rows).
+3. Delete the CG unit's `ItemFulfillmentItemUnits` rows (and their `..._TrackingNumbers` bridges).
+4. `DELETE` the CG unit.
+
+Scope: **IFIU-attached CG units only** (per developer). DB facts at time of build: 22,288 total
+CG-serial units, none with `assetTag` set; 19,214 attached to an IFIU.
+
+### Phase 1 — header/link/bridge repairs (levels L1–L4)
+Repairs the supply-chain header chain and the item-link bridges. Levels:
+- **L1** `repairOdpPoToAgilantSoLinks` — **always calls NetSuite** (`buildNetsuiteGroupMap`), even
+  when the L1 links already exist.
+- **L2/L3/L4** — NetSuite-free bridge repairs. **L3** repairs the
+  `PurchaseOrderItems_SalesOrderItems` rung (MITS PO item → ODP SO item) that the Flow-B recursive
+  IF mirror depends on.
+
+### Phase 2 — fulfillment mirror climb
+Walks each source ItemFulfillment up the chain (Agilant → ODP → Compass), creating the mirror IFs.
+
+## Level isolation — `runLevel()`
+
+Originally Phase 1 ran L1→L4 with **no isolation**. Because L1 unconditionally calls NetSuite, a
+NetSuite SSL/SOAP failure there threw, `main()`'s catch marked the **whole order FAILED**, and the
+independent NetSuite-free L2/L3/L4 repairs (including the L3 rung Phase 2 needs) were skipped — even
+though L1 usually had nothing to insert (the affected orders' Agilant SOIs were already fully linked,
+so the NetSuite call was pure overhead/risk).
+
+`runLevel()` wraps each Phase-1 level (and each Phase-2 source-IF climb) so **a level's exception is
+logged as a skip and swallowed**, letting the remaining independent levels still emit. This is the
+core reliability fix: independent repairs no longer share a failure fate with L1's external call.
+
+## Write guards — `emit()` vs `emitUnit()`
+
+- `emit()` — the default SQL sink; **hard-blocks any write to the `Units` and `TrackingNumbers`
+  tables**.
+- `emitUnit()` — a narrow helper for the Phase-0 units track that **permits `Units` UPDATE/DELETE
+  but still blocks `TrackingNumbers`**. This is a deliberate, scoped exemption to the
+  never-write-`Units` guard, used only by Phase 0.
+
+Never emit writes to `TrackingNumbers`; existing tracking rows are only ever linked, never created
+(consistent with the Compass workflow invariants).
+
+## Change history
+- 2026-08-18 — Initial doc. Recorded retrofix2.php's Phase 0/1/2 structure, the new **Phase 0
+  CG-unit asset-tag merge** (merge/order-pair/skip cases, the 4 emitted statements, repoint-not-delete
+  for inventory history), the **`runLevel()` level isolation** fix (L1's unconditional NetSuite call
+  no longer fails the whole order and skips the L2/L3/L4 bridge repairs), and the scoped **`emitUnit()`**
+  exemption to the never-write-Units guard. (jcardinal)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -12,7 +12,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togaview** (TOGa View) — 7 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)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
-- **test** (Test) — 14 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
+- **test** (Test) — 15 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 3 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **tools** (Tools) — 15 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 

package/knowledge/clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md

@@ -5,10 +5,11 @@ project: _Underscore
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-08-04
+updated: 2026-08-18
 owners: ["jcardinal", "bala", "dfranks"]
 files: []
 related:
+  - 1.0/apps/test/features/compass-retrofix2-sql-generator.md
   - clients/compass-usa/profile.md
   - clients/compass-usa/features/asn-to-item-fulfillment.md
   - clients/compass-usa/features/mits-po-to-so-item-linking.md
@@ -71,6 +72,27 @@ back-link chain climbs **Agilant → ODP → Compass**. Item back-links use
 `ItemFulfillmentItems.upstreamItemFulfillmentItemId` the same direction and may be many-downstream →
 one-upstream for bundles.
 
+> **Mirror-gap root cause — a missing item bridge stalls the climb (verified 2026-08-18).** The
+> recursive IF mirror climbs Agilant → ODP → Compass through **BOTH** bridge tables. If the
+> `PurchaseOrderItems_SalesOrderItems` rung linking the Compass/MITS PO item → the ODP SO item is
+> **missing**, the mirror **cannot map past the ODP SO** and never creates the ODP/Compass mirror IFs
+> — the Compass SO shows "nothing fulfilled" even though the Agilant SO has an ItemFulfillment
+> (`c_netsuiteInternalItemFulfillmentId` set, created by NetSuite sync). Orders SA130530, SA130334,
+> SA130430 all had an intact header chain and every other item bridge, but were missing **only** that
+> one rung (confirmed against a healthy order that had it). When diagnosing a Flow-B order that
+> fulfilled upstream but shows empty on Compass, check that specific bridge first.
+
+### Asset tags arrive as separate CG "units" (Flow B)
+NetSuite delivers asset tags on **separate service-item lines** whose part number contains
+`ASSETTAG` (e.g. `ODP-COMPASS-ASSETTAG1`). Older Compass imports landed each asset tag as its **own
+`Units` row** whose `serialNumber` holds the CG value (e.g. `CG2000027730`), attached via
+`ItemFulfillmentItemUnits` alongside the real serialized unit on the **same** fulfillment. The
+forward fix (`library/app/api/toga2.php` ~lines 3688–3965) applies those asset tags to the serialized
+items **in order** and sets `Units.assetTag` on the real device. Retroactively this is Phase 0 of the
+[retrofix2 tool](../../../1.0/apps/test/features/compass-retrofix2-sql-generator.md); because units
+are **shared up the chain** (same `Units.id` at every level), the correction must land before the
+fulfillment mirror climbs.
+
 ## Expected raw-data invariants (for detect-and-repair)
 
 1. **Links:** every SOI that should be procured has exactly one PURE bridge to the matching POI on the
@@ -141,12 +163,18 @@ column is `ON UPDATE CURRENT_TIMESTAMP`), which can look like a fresh modificati
 `api2` cXML ShipNotice handler; the `_underscore` recursive item-fulfillment engine.
 
 ## Retrofix tooling
-A standalone repair script lives in the worker 1.0 test area (`test/@jeff/compass/retrofix.php`,
-machine-local path tracked in dev memory). It sweeps Compass SOs newest-first, detects deviations from
-the invariants above, and repairs via direct SQL on `db_prod2_compass`. Safety rules baked in: rehearsal
-mode (logs intended writes, rolls back), per-phase gating, a hard block on any write to the
-`TrackingNumbers` table, and the never-over-fulfill cap. It is a diagnostic/repair tool, not part of the
-runtime workflow.
+The current repair script is **`test/@jeff/compass/retrofix2.php`** (1.0 `App_`), which
+**supersedes** the older `retrofix.php` sibling in the same folder. Unlike the description below of the
+earlier tool, retrofix2 **emits review-first `.sql`** rather than writing the DB directly. It runs
+three phases newest-first per SO — **Phase 0** (CG-unit asset-tag merge; must run first because units
+are shared up the chain), **Phase 1** (header/link/bridge repairs, levels L1–L4, where L3 fixes the
+`PurchaseOrderItems_SalesOrderItems` rung the mirror needs), **Phase 2** (fulfillment mirror climb).
+Each level is wrapped in `runLevel()` so one level's exception (notably L1's unconditional NetSuite
+call failing) is logged as a skip and swallowed, letting the independent NetSuite-free repairs still
+emit. Write guards: `emit()` hard-blocks `Units` and `TrackingNumbers` writes; the Phase-0-only
+`emitUnit()` permits `Units` UPDATE/DELETE but still blocks `TrackingNumbers`. Full structure in the
+[retrofix2 feature doc](../../../1.0/apps/test/features/compass-retrofix2-sql-generator.md). It is a
+diagnostic/repair tool, not part of the runtime workflow.
 
 ## Edge cases & escalation
 - Incomplete orders (no PO/ASN/Agilant leg yet) are normal — repair only the layers that exist.
@@ -155,6 +183,12 @@ runtime workflow.
 - High-multiplier over-fulfillment (5×–20×) does not fit the split-PO spurious-link pattern — separate cause.
 
 ## Change history
+- 2026-08-18 — Recorded the **Flow-B mirror-gap root cause** (a missing `PurchaseOrderItems_SalesOrderItems`
+  rung stalls the recursive IF mirror past the ODP SO, so a fulfilled Agilant order shows empty on
+  Compass — orders SA130530/SA130334/SA130430), the **CG asset-tag "unit" data shape** (asset tags land
+  as their own CG-serial `Units` rows), and repointed the Retrofix tooling section to the new
+  **retrofix2.php** (review-first `.sql`; Phase 0/1/2; `runLevel()` level isolation; `emit()`/`emitUnit()`
+  write guards). (jcardinal)
 - 2026-08-04 — Added the **"empty shell" order signature** — the ODP importer writes the SO header
   and its items in two separate API requests, so a fatal on the second leaves a committed,
   zero-item order — plus the three orphan sweeps that detect it (zero-item SOs, zero-item POs, ODP

package/package.json

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