toga-ai 1.0.250 → 1.0.252

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -8,5 +8,5 @@
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

package/knowledge/2.0/apps/toga25-supply/features/surface-frontend.md

@@ -11,7 +11,11 @@ owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
   - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
+  - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts
   - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/surface/actionRegistry.ts
@@ -56,15 +60,18 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
   **structural fingerprint**: `looksLikeBundle` now requires **both** an `elements` array **and** a
   `surface` descriptor object (not the `elements` array alone — see the decoy gotcha below).
   `extractBundle(raw, slug)` then **prefers** the bundle whose `surface.slug === slug`, falling back to
-  first-found, so a stray sibling bundle can't win. `looksLikeGroup` requires the documented `group`
-  discriminator key so a single-bundle envelope is not mistaken for a group. On a malformed payload it
+  first-found, so a stray sibling bundle can't win. On a malformed payload it
   falls back to a safe empty bundle (empty `elements` + empty `messages`/`theme`/`vocabularies` maps)
   so the page never crashes.
 - **`useFetchSurfaceMetaGroup(slugs[])`** — the grouped sibling of `useFetchSurfaceMeta`, for a screen
   needing many section surfaces at once. **Order-insensitive** (the slug list is normalized so cache
   hits don't depend on argument order), `staleTime: Infinity`, hits the grouped endpoint
-  `GET /v2/surfaces/meta-group?slugs=...`, and extracts the `{surfaces}` map via `extractGroup()` /
-  `looksLikeGroup()` (the same structural-fingerprint approach as `extractBundle`). Returns `{}` for
+  `GET /v2/surfaces/meta-group?slugs=...`, and extracts the SLUG-keyed `{surfaces}` map via the
+  recursive **`findSurfaceMap(raw, depth=5)`** — which walks the envelope tree and returns the
+  `surfaces` map whose **values look like bundles** (or an empty/null map), uniquely identifying the
+  inner slug-keyed map regardless of nesting or `data` wrapping. (`extractGroup`'s old
+  `data`/`data.<key>` probe and the `looksLikeGroup` `group`-discriminator check were both removed —
+  see the group-nesting gotcha below for why.) Returns `{}` for
   unmigrated screens (`enabled:false`), so a non-roster client does no fetch.
 - **`componentRegistry`** (`src/surface/componentRegistry.tsx`) — the **presentation sibling** of
   `actionRegistry`, both keyed by the surface meta's `action.key`. `actionRegistry` maps key→behavior
@@ -154,6 +161,17 @@ three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouche
   `getDetailSections` are untouched — **only the SOURCE of section config moves JSON → Surface.**
   Business logic stays in code: the recurring-lease `_totalLease` gate in the grid and approval
   gating are **not** moved. (Registered-renderer seam: *config describes, code decides.*)
+- **Full adapter-seam data path (verified this session, no direct `<SurfaceSection>`):**
+  `useFetchSurfaceMetaGroup(SALES_ORDER_SURFACE_SLUGS)` → `surfaceBundleToTenantFields(surfaces)` →
+  merged into `tenantFields` (roster clients only; `clientSlug` is the **uppercased** `getHostname()`
+  result matched against the roster) → **`buildPatchedTenantFields`** (which only overrides
+  `recordActionFields`, so it **preserves all surface section keys**) → `SalesOrderView` →
+  **`SalesOrderSummaryGrid`** (renders by `section.type` / `cardType`:
+  `detailSection`/`locationCard`/`totalsCard`, where `cardType` comes from `surface.config.cardType`)
+  + **`getDetailSections`** (reads `section.isVisible` for the `displayToggle` sections, which carry a
+  `sectionVisibility` marker element). **Decision (confirmed by the developer this session): KEEP the
+  adapter approach — do NOT replace it with a direct `<SurfaceSection>` swap.** The bespoke grid
+  renderers and the `TenantFields` seam are the deliberate integration point.
 - **Roster gate — `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]`** (an
   in-code roster in `surfaceBundleToTenantFields.ts`; the view-model
   `useSalesOrderRecordModalLayoutModel.tsx` consults it). The view-model resolves sections from
@@ -182,6 +200,27 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   bundle → the action bar renders nothing. Fix: `looksLikeBundle` must require **both** `elements` AND
   a `surface` descriptor; use recursive `findBundle` + slug-preferring `extractBundle` (see How it
   works). The durable backend follow-up is to confirm/stabilize the single-meta envelope contract.
+- **The GROUPED meta envelope double-nests the slug-keyed `surfaces` map under an OUTER route-keyed
+  `surfaces` slot — match by value shape, never grab the first `surfaces`.** The meta-group V2 envelope
+  mirrors single-meta's bundle nesting: the real SLUG-keyed map sits one level deeper under a ROUTE-keyed
+  outer slot — `{ surfaces: { "meta-group": { group, surfaces: { "order-details": bundle, … } } },
+  elements: [] }`. The old `extractGroup` grabbed the **first** `surfaces` it saw (the outer route-keyed
+  one, whose values are *group* objects, not bundles), so `surfaces["order-details"]` was `undefined`
+  and `surfaceBundleToTenantFields` produced `{}` — every migrated-client SalesOrders section vanished.
+  Fix: recursive **`findSurfaceMap(raw, depth=5)`** returns the `surfaces` map whose **values look like
+  bundles** (or null/empty), uniquely identifying the inner slug-keyed map regardless of nesting or
+  `data` wrapping. Verified by trace across 6 envelope shapes (double-nested, resolver-return-at-top,
+  simple, data-wrapped, null-child, empty). **Note:** an earlier attempt that required a top-level
+  `group` discriminator on the probed level (`looksLikeGroup`) broke the fetch (returned `{}`) because
+  the V2 envelope carries no top-level `group` at that level — `looksLikeGroup` was removed entirely.
+- **For migrated clients, a dropped (`surface: null`) display section silently vanishes — there is no
+  JSON fallback left.** Once a client's JSON section blocks are deleted (roster migration), a section
+  whose surface resolves to `surface: null` (a seed/ACL gap, e.g. `additional-order-details` /
+  `admin-notes` / `notes`) is dropped by `surfaceBundleToTenantFields` and the section disappears with
+  no fallback. That is a backend seed/ACL gap, **not** an FE bug. Separately, two sections are
+  intentionally gated in `getDetailSections`: `shipments` is **permanently hidden** (the view-model
+  hardcodes `shipmentsData: []` and `useShipments` is commented out; the section gates on
+  `shipmentsData.length > 0`), and `invoices` is data-gated on `invoiceData.length > 0`.
 - **The surface `record` shape must match the rule field namespace — wrap as `{ order }`.** Seeded
   Tier-1 rules namespace their field as `order._status`, so `getByPath(record, "order._status")` only
   resolves if the host passes `record={{ order }}`. Passing the bare order object resolves to
@@ -210,6 +249,19 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-06-30 — Follow-up: fixed the GROUPED meta fetch returning `{}` (every migrated-client
+  SalesOrders section had vanished). The meta-group envelope double-nests the slug-keyed `surfaces`
+  map under an outer ROUTE-keyed `surfaces` slot; the old `extractGroup` grabbed the first (outer,
+  group-valued) `surfaces`. Replaced it with recursive `findSurfaceMap(depth=5)` that returns the
+  `surfaces` map whose values are bundle-shaped (verified across 6 envelope shapes). **Reverted the
+  earlier same-session `group`-discriminator `looksLikeGroup` change** — requiring a top-level `group`
+  broke the fetch; `looksLikeGroup` removed entirely. Verified the SalesOrders section migration is
+  fully wired via the adapter seam (`useFetchSurfaceMetaGroup` → `surfaceBundleToTenantFields` →
+  `buildPatchedTenantFields` (overrides only `recordActionFields`) → `SalesOrderSummaryGrid` /
+  `getDetailSections`) and confirmed the decision to KEEP the adapter over a direct `<SurfaceSection>`.
+  Documented why some sections stay hidden (`shipments` hardcoded empty; `invoices` data-gated; and a
+  dropped `surface: null` display section vanishes with no JSON fallback for migrated clients — a
+  seed/ACL gap). (apeterson)
 - 2026-06-30 — Migrated the SalesOrders record-modal sections onto Surface for the roster clients
   [COMPASS, COMPASSCANADA, QUAD] via the registered-renderer seam: added `useFetchSurfaceMetaGroup`
   (order-insensitive grouped `/surfaces/meta-group` fetch) + `surfaceBundleToTenantFields()` (adapts
@@ -221,7 +273,7 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
 - 2026-06-30 — Debugged + extended the client-side action-bar renderer (no client-specific work).
   Fixed three rendering bugs: (1) the single-meta envelope's **decoy `elements: []`** masked the real
   nested bundle — `looksLikeBundle` now requires `elements` AND a `surface` descriptor, with recursive
-  `findBundle(depth=4)` + slug-preferring `extractBundle` + `group`-discriminator `looksLikeGroup` +
+  `findBundle(depth=4)` + slug-preferring `extractBundle` +
   safe empty `messages`/`theme`/`vocabularies` fallback (`useFetchSurfaceMeta.ts`); (2) Tier-1 rules
   always false because the host passed the bare order object instead of the `{ order }` envelope the
   `order.*` field namespace requires (`SalesOrderTopBar.tsx`); (3) every action icon rendered as

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -13,7 +13,7 @@
 | [Etilize Catalog Item Import & Refresh](features/etilize-catalog-item-import.md) | Client-generic catalog onboarding from an S3 CSV plus an Etilize re-pull. | worker2/Worker/Etilize/Items.php |
 | [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |
-| [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [NetSuite ↔ ClickUp / TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Clickup.php, worker2/Worker/Clickup/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, _underscore/Model/Client/EmailTemplate.php |

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -1,16 +1,18 @@
 ---
-title: NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)
+title: NetSuite ↔ ClickUp / TOGA Opportunity Sync (API Message Queue + worker2 webhook)
 framework: "2.0"
 repo: worker2
 project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-06-30
 owners: ["dfranks"]
 files:
   - worker2/Worker/Netsuite.php
   - worker2/Worker/Netsuite/Opportunity.php
+  - worker2/Worker/Clickup.php
+  - worker2/Worker/Clickup/Opportunity.php
   - worker2/Controller/Index.php
   - _underscore/Worker.php
   - test/@dave/NetSuite/api-message-queue/lib_amq_queue.js
@@ -38,7 +40,10 @@ Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer
 record ("API Message Queue"), a scheduled SuiteScript drains it to
 `webhook.togahub.com/netsuite`, and worker2 routes it to a per-recordType handler that upserts
 into the `Forecast` DB. The legacy NetSuite→ClickUp opportunity-task creation is preserved as a
-second, independently-gated concern in the same handler.
+second, independently-gated concern in the same handler. As of 2026-06-30 (TRUE-79181) the ClickUp leg
+is **bidirectional for field + stage**: ClickUp task edits flow back to the linked NetSuite opportunity
+(`_Worker_Clickup_Opportunity`, update-only), and NS→CU now drives the ClickUp task **status** — see
+the "CU→NS direction" section.
 
 ## Key files / entry points
 
@@ -364,29 +369,106 @@ None — platform-wide Forecast sync.
   (doubled-prefix ids — see the doubled-id gotcha), which are **SuiteQL-queryable** for after-the-fact
   diagnosis even though the calling-script log rolls off.
 
-## CU→NS direction (future — not yet built): reverse mapping
+## CU→NS direction (BUILT 2026-06-30, TRUE-79181): reverse sync
 
-The current sync is **NS→CU only**. When the ClickUp→NetSuite direction is built, it cannot reuse the
-block-to-block compare, because the source of the edit is the ClickUp **composite** but the destination
-is **discrete NetSuite fields**. It must **reverse-map** — extract the real NS values out of the wrapper
-before comparing-to / writing-to NetSuite:
+The integration is now **bidirectional** for **field + stage**. ClickUp task edits flow back to the
+linked NetSuite opportunity via a new handler, and NS→CU now drives the ClickUp task **status** (not
+just description text).
 
-- **Title → NS `title`:** the task name is `{opp#} — {customer} — {title}`. Do **not** naively split on
-  ` — ` (a title can contain a dash). Strip the **known** `{Opportunity#} — {Customer#} — ` prefix using
-  the values already on the `Opportunity #` / `Customer #` custom fields as anchors; the remainder is
-  the NS title.
-- **Description → NS `memo`:** take only the lines between the `Details:` marker and the trailing
-  `NetSuite Internal ID:` line. Company / Amount / Expected Close / Stage are NS-derived display, not
-  ClickUp-authored — parse them out and ignore.
-- **Custom fields** are already discrete — no extraction.
+**Handler:** `_Worker_Clickup_Opportunity` (`worker2/Worker/Clickup/Opportunity.php`) — an abstract
+static-class worker, dispatched by `_Worker_Clickup::Webhook` via
+`_Worker::runTask('Clickup/Opportunity/Process', {taskId,event,data})`. Routing is gated by the ClickUp
+**LIST id** (Presales Qualification list `901111987449`) for `taskUpdated`/`taskStatusUpdated` events;
+non-opportunity lists fall through to the legacy sprint handling in `Clickup.php`.
 
-Pair this with: a **field-ownership gate** (only write fields ClickUp is authoritative for — Amount/
-Stage/Expected Close are NS-owned, and HubSpot also writes these records, so don't push them back), the
-same **skip-if-unchanged** compare on the extracted values, and **actor-identity suppression** (drop
-`taskUpdated` events authored solely by the ClickUp bot/integration user) so our own NS→CU writes don't
-trigger a CU→NS write. The NS→CU change-detection above is the complementary backstop, not a substitute.
+**CU→NS is UPDATE-ONLY** (never create/delete):
+1. Resolve the linked NS opportunity from the task's `Opportunity #` custom field
+   (`a5529cdc-8dbb-4165-8bc5-9f5cc691796a`, = NS `tranId`) via a one-row SuiteQL
+   `SELECT id FROM transaction WHERE type='Opprtnty' AND tranid='<n>'`.
+2. GET the opportunity with `expandSubResources=true` — this also supplies the **current** NS values
+   for the diff.
+3. **No match → skip.**
+4. PATCH **only** the NS-owned fields that actually differ (currently `title`, `stage`). A no-op write
+   fires no NS event, so the write cannot re-trigger NS→CU. **Echo prevention is the difference-check
+   alone** — there is no actor-identity / "last-synced-from" suppression field (that hardening was
+   explicitly deferred; see Decisions).
+
+**Shared `STAGE_MAP` — single source of truth, declared on `_Worker_Netsuite_Opportunity`.** Maps NS
+`entityStatus` internalId → ClickUp status on the Presales Qualification list (VERIFIED live 2026-06-30):
+
+| NS internalId | NS stage | ClickUp status |
+|---|---|---|
+| 124 | Closed - Won | `opportunity won` |
+| 14 | Closed Lost | `closed lost` |
+| 125/126/122/123/128 | 10% / 25% / 50% / 75% / 95% | `in progress` |
+| 130 | Alternate Quote | *(unmapped)* |
+
+**CRITICAL non-1:1 gotcha:** the five probability stages all collapse to `in progress`, so the reverse
+map `CU_STATUS_TO_NS_STAGE` only covers the **unambiguous terminal** stages (won/lost). CU→NS leaves a
+non-terminal status alone rather than guessing a percentage. The percentage-reverse mapping is an
+**unresolved stakeholder (Aaron) decision** — do not invent one.
+
+**NS→CU now drives the ClickUp task STATUS** from the NS stage via `STAGE_MAP` (previously the stage was
+only rendered in the description text). Applied on both create and update; the update PUT carries
+**only** the changed fields (`name`/`description`/`status`) to stay echo-safe.
+
+**Outbound NS calls** use the `Logs.Api` two-save pattern (`_Model_Core_Logs_Api`, `DB_LOGS`,
+`DIRECTION_OUT`: save the request row, then save the response/failure row), with
+`\Sentry\captureException($e); throw $e;` on failure so `WorkerJobs` records `isSuccess=0`. Logged
+payloads are length-capped. NS access is the **2.0 adapter `_Component_Api_Netsuite`** (GET/PATCH +
+SuiteQL POST with `Prefer: transient`); the **1.0 `App_Api_Netsuite_Rest` / SOAP toolkit are
+deprecated** for production opportunity code.
+
+### CU→NS gotchas
+
+- **SuiteQL over `_Component_Api_Netsuite` has NO placeholder binding.** When a SuiteQL filter value
+  comes from an **external** source (here a ClickUp custom-field `tranId`, not a local PK), sanitize
+  with an **allowlist-and-REJECT-on-mismatch**, not strip-and-use:
+  `$safe = preg_replace('/[^A-Za-z0-9_-]/','',$v); if ($safe!==$v) return null;`. Reject-on-mismatch is
+  the firewall; silently stripping characters is not enough.
+- **Validate `task_id` format at the webhook entry.** ClickUp native task ids are alphanumeric. The
+  legacy `_Worker_Clickup::Webhook` interpolates the raw `$payload->task_id` into Team-DB SQL at ~20
+  sites (a **pre-existing** SQL-injection exposure, NOT introduced here). A single input-boundary
+  format guard at the top of `Webhook()` closes that class for the raw payload id without rewriting
+  each query. **FLAG:** the broader legacy `$taskId`/`$customTaskId` raw-SQL interpolation throughout
+  `Clickup.php` is real pre-existing debt that warrants a dedicated security ticket.
+- **ClickUp opportunity field ids:** list `901111987449` ("Presales Qualification");
+  `Opportunity #` = `a5529cdc-8dbb-4165-8bc5-9f5cc691796a`,
+  `Customer #` = `170dc118-b3fa-413b-826b-2753e9405851`.
+
+### Deferred (documented follow-up)
+
+- **Notes & attachments (CU→NS)** were intentionally deferred — they require NetSuite custom fields
+  (`custentity_cu_synced_notes` / `custentity_cu_synced_files`) + a File Cabinet folder that **do not
+  exist yet**, plus unconfirmed NS REST note/file shapes. Field + stage sync is bidirectional;
+  notes/attachments remain a documented follow-up.
+- **Actor-identity echo hardening** deferred — the difference-check is the current (and sufficient for
+  field/stage) echo-prevention mechanism. A "drop events authored by our own integration user" gate is
+  the planned hardening if/when no-op-safe writes can't fully cover a future field.
+- **Percentage reverse-mapping** (which NS percentage stage a CU `in progress` should map back to) is
+  blocked on the Aaron stakeholder decision noted above.
 
 ## Change history
+- 2026-06-30 — **Built the CU→NS reverse sync + NS→CU stage drive (TRUE-79181) — integration now
+  bidirectional for field + stage.** New `_Worker_Clickup_Opportunity` handler
+  (`worker2/Worker/Clickup/Opportunity.php`), dispatched by `_Worker_Clickup::Webhook` via
+  `_Worker::runTask('Clickup/Opportunity/Process', …)`, gated by ClickUp **list id `901111987449`** for
+  `taskUpdated`/`taskStatusUpdated`. CU→NS is **update-only**: resolve the linked opp by the task's
+  `Opportunity #` (= `tranId`) via one-row SuiteQL, GET it (`expandSubResources=true`) for the current
+  values, PATCH only the differing NS-owned fields (`title`, `stage`). **Echo prevention = difference-check
+  only** (actor-identity hardening explicitly deferred). Added a shared `STAGE_MAP` on
+  `_Worker_Netsuite_Opportunity` (NS entityStatus internalId → ClickUp status; VERIFIED live: 124→won,
+  14→lost, 125/126/122/123/128→`in progress`, 130 unmapped) — its **five-probability-stages-collapse-to-
+  one** non-1:1 means the reverse map covers only the terminal stages; the percentage reverse-mapping is
+  an open Aaron decision. NS→CU now also drives the ClickUp task **status** from the stage (was
+  description-text only), PUT carrying only changed fields to stay echo-safe. Outbound NS calls use the
+  `Logs.Api` two-save OUT pattern + `Sentry::captureException;throw` on failure; NS access via the 2.0
+  `_Component_Api_Netsuite` adapter (1.0 `App_Api_Netsuite_Rest`/SOAP deprecated for prod). Gotchas
+  recorded: **SuiteQL has no placeholder binding** → external filter values need allowlist-**reject-on-
+  mismatch** sanitize; **validate `task_id` format at the webhook boundary** (the legacy `Clickup.php`
+  interpolates the raw payload id into Team-DB SQL at ~20 sites — pre-existing injection debt flagged for
+  a dedicated security ticket). Notes/attachments CU→NS deferred (need NetSuite custom fields +
+  File-Cabinet folder that don't exist yet). (dfranks)
 - 2026-06-25 — **Fixed the Opportunity duplicate-row amplification + added a unique-index guard.**
   Root cause: `_Model::load()` returns TRUE only on an **exactly-one** match (FALSE for 0 *and* 2+),
   so once an nsId had 2 rows the `load()`-then-upsert handler could never re-find it and every

package/package.json

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