toga-ai 1.0.321 → 1.0.323

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

@@ -2,6 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
+| [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |

package/knowledge/2.0/apps/_underscore/architecture/surface-authoring-proposal.md

@@ -0,0 +1,67 @@
+---
+title: Proposed — git-sourced base+overlay JSON authoring for the Surface layer
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: architecture
+status: draft
+updated: 2026-07-13
+owners: [apeterson]
+files:
+  - _underscore/Model/Core/Surface.php
+  - _underscore/Model/Client/SurfaceOverride.php
+related:
+  - ../features/surface-resolver.md
+---
+
+## Summary
+
+A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model
+move off hand-authored SQL against the `SurfaceOverrides` EAV table onto **git-sourced JSON**: a full
+neutral `_base/<surface>.json` per surface plus partial per-client overlay files holding only diffs,
+merged by the resolver at read time. The runtime resolver is kept for the dynamic parts (per-record
+Tier-2 evaluation + ACL element-drop). This doc records the motivation, the design, and interim
+guardrails so the lead dev can decide.
+
+**Critical rules:** This is a **proposal, status: draft — nothing here is implemented.** Do not treat
+any of it as the current system. The live authoring path is still hand-written SQL against
+`SurfaceOverrides`; if you stay on it, apply the interim guardrails below (unique index, strict SQL
+mode, autocommit on, idempotent migrations) or you will hit the silent EAV failure modes.
+
+## Problem
+
+Surface config is authored as hand-written SQL against the `SurfaceOverrides` EAV table. This has:
+- **No git diff / review / rollback** — config changes bypass code review and CI.
+- **No team-merge story** — concurrent work on a shared surface collides with no merge tooling.
+- **Silent DB failure modes** — ENUM coercion of unknown values to `''` (non-strict mode), a missing
+  unique constraint letting duplicate override rows pile up, and autocommit-off swallowing writes.
+
+Cost signal: 2 of ~17 surfaces took ~5 days.
+
+## Recommendation
+
+**Source of truth = git.** For each surface author a full neutral `_base/<surface>.json`, plus partial
+per-client overlay files holding **only diffs**, merged by the resolver at read time. Keep the
+resolver for the dynamic parts it must still compute (per-record Tier-2 evaluation + ACL
+element-drop — see [surface-resolver](../features/surface-resolver.md)).
+
+**Framing: "source of truth = git; read substrate = a choice."** Three read substrates, in order of
+preference:
+1. Read the JSON files directly at read time.
+2. Seed the JSON documents into a DB column at deploy (git still authors; DB is a materialized cache).
+3. (Avoid) DB-as-master authored by hand — the status quo.
+
+## Optional future — bounded live toggles
+
+An admin UI (a screen + a validating API endpoint + an `admin_flags` DB table) that writes a
+**bounded, whitelisted** set of per-client feature toggles, merged at **highest precedence**. This
+gives live no-deploy toggles without undermining git-as-truth, because the whitelist bounds what can
+be changed outside git.
+
+## Interim guardrails (if staying on SQL/EAV)
+
+- Unique index on `SurfaceOverrides(surfaceElementId, attribute, roleId, personaId, languageId)`.
+- Strict SQL mode (so unknown ENUM values error instead of coercing to `''`).
+- Autocommit on.
+- Idempotent, re-runnable migrations.

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-01
+updated: 2026-07-13
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
@@ -137,6 +137,70 @@ breaks logic.
   `_Model_<Client>_*` overrides + `Client_ApiPayloadInterceptor` hooks — the Surface layer does
   **not** absorb business logic.
 
+## Per-client override of the Tier-1 gating RULES (not just static flags)
+
+Originally only static flags (`isVisible`/`isEnabled`) and `config` were per-client overridable
+via `SurfaceOverrides`; the **Tier-1 gating rules** (`visibilityRule`/`enabledRule`) were frozen on
+the Core element. That meant two-stage-approval clients could not be expressed as data — they needed
+per-client PHP. Two new override attributes make the declarative rules per-client overridable so the
+two-stage behavior is **pure data**:
+
+- `_Model_Client_SurfaceOverride` now declares `ATTRIBUTE__VISIBILITY_RULE` and
+  `ATTRIBUTE__ENABLED_RULE` constants.
+- In `Surface.php` `_resolveElement`, the resolver decodes and applies both attributes: the locals
+  are seeded from the Core element's own `visibilityRule`/`enabledRule`, then overridden by any client
+  override row. `_castOverride` decodes them as JSON alongside `CONFIG`.
+
+> **⚠ LOCAL only (as of 2026-07-13).** The `_underscore` code change **and** the ENUM migration below
+> must ship together to beta/prod on promotion. php-reviewer pass + a PHPUnit regression test for the
+> rule-override path are still outstanding.
+
+**Mandatory ENUM migration (ships with the code).** Each client schema's
+`SurfaceOverrides.attribute` ENUM must be widened *before* any rule-override row is inserted:
+`ALTER TABLE Client_*.SurfaceOverrides MODIFY attribute ENUM(...,'VISIBILITY_RULE','ENABLED_RULE') NOT NULL`
+across all 32 `Client_*` schemas. In **non-strict SQL mode** an insert of an unknown ENUM value
+**silently coerces to `''`** — which makes the resolver ignore the rows and `NOT EXISTS` guards never
+match (duplicate rows pile up). Widen the ENUM first, always.
+
+### Override semantics: REPLACE, not deep-merge
+A `CONFIG` (and now `VISIBILITY_RULE`/`ENABLED_RULE`) override **replaces the whole decoded object**
+— it does **not** deep-merge (`Surface.php` ~line 818). So a `CONFIG` override value must carry the
+**full** config (e.g. `role` + `filterKey` + `additionalData`), not just the changed key.
+
+### Two separate gating mechanisms on the sales-order listing (do not conflate)
+- The **Approvals FILTER** on the sales-order listing is driven by `config.additionalData._status`.
+- The **per-button record actions** are gated by `visibilityRule`/`enabledRule`.
+These are separate mechanisms on separate surfaces; a filter change is a `CONFIG` override, a
+button-gating change is a rule override.
+
+## Core re-baselined to a neutral default + per-client diffs (decision, 2026-07-13)
+
+Core was effectively "Client Zero = Compass", not a neutral default, so every client inherited
+Compass's shape. Core was re-baselined as a true shared default so clients store **only diffs**:
+
+1. The approvals gate is governed by the **`navigation-approvals` ACL grant**, not per-tenant
+   `IS_VISIBLE` overrides.
+2. Default approvals filter = `pendingApproval` only (single-stage).
+3. No Tier-2 `config.tier2` caveat baked into Core.
+4. Edit-in-Commerce only for Compass / CompassCanada.
+5. Columns button hidden by default.
+
+Per-client diffs layered on top:
+- **Quad** — Approve + Deny only; filter narrowed to `pendingApproval`; filter button visible.
+- **Compass USA / Compass Canada** — two-stage approvals: record-action `visibilityRule`/`enabledRule`
+  = `in [pendingApproval, pendingInitialApproval]`. **Compass Canada** additionally gets a `CONFIG`
+  override on the approvals filter button (surface `sales-order-listing-actions`) to add
+  `pendingInitialApproval`.
+
+> ⚠ **Regression left open:** the Compass / CompassCanada **non-rule** overrides (Edit-in-Commerce
+> flags, role-8 Manager hides) were **wiped during the rebuilds and not re-added**. The two-stage rule
+> overrides are also LOCAL only (see above).
+
+### Operational gotcha — raw SQL bypasses the cache-bust
+Raw SQL against the surface tables bypasses the model-layer cache-bust, so the on-disk bundle cache
+at `~/toga/cache/surface_meta/*.json` **must be cleared manually** after any raw-SQL surface edit.
+(Cache confusion earlier was a local-setup artifact, not an inherent design issue.)
+
 ## How a surfaces scripted-API call is authorized (route-level gate)
 
 Authorizing a surfaces script (`meta`, `meta-group`, `debug`) is a **two-layer** check. Get the
@@ -234,6 +298,17 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-07-13 — Made the Tier-1 gating RULES per-client overridable: added
+  `ATTRIBUTE__VISIBILITY_RULE`/`ATTRIBUTE__ENABLED_RULE` to `_Model_Client_SurfaceOverride`;
+  `_resolveElement` seeds locals from the Core element's rules then applies overrides;
+  `_castOverride` decodes them as JSON — so two-stage approvals are pure data, not per-client PHP.
+  Requires widening `Client_*.SurfaceOverrides.attribute` ENUM (32 schemas) first (non-strict mode
+  silently coerces unknown ENUM → `''`). Documented override REPLACE-not-merge semantics, the
+  filter (`config.additionalData._status`) vs button-rule split, the raw-SQL cache-bust bypass
+  (`~/toga/cache/surface_meta/*.json`), and the Core neutral-default re-baseline (ACL-gated
+  approvals, single-stage default, per-client diffs: Quad = Approve+Deny, Compass/CC = two-stage).
+  ⚠ Code + ENUM migration are LOCAL only; non-rule Compass/CC overrides wiped in rebuild not yet
+  re-added; php-reviewer + regression test outstanding. (apeterson)
 - 2026-07-01 — Clarified vocabulary/label per-client relabeling (new section): Vocabulary `slug`
   and VocabularyTerm `value` are stable internal ids never shown to users; the displayed label
   always resolves from `Core.Messages`; clients relabel via a `SurfaceOverrides` `LABEL_MESSAGE`

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/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 |
+| [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/SurfaceRowActions.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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-13
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
@@ -27,6 +27,7 @@ files:
   - 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/SurfaceRowActions.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
@@ -245,10 +246,24 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   (the path form 404s EV-6).
 - **Tier-1 only on the client.** Business-logic gates (Tier-2) arrive as resolved booleans from the
   backend (`meta.surface`); never re-encode business rules in the FE evaluator.
+- **A React portal overlay's click bubbles through the COMPONENT tree, not the DOM tree.** The
+  SalesOrders row-actions menu (`SurfaceRowActions.tsx`) renders its dismiss overlay via a portal;
+  an outside-click on that fixed overlay propagated up the React component tree to the row's
+  `handleRowClick` and **opened the record modal**. Fix: call `e.stopPropagation()` (plus close) in
+  the overlay's `onClick`. Portal DOM position does not stop React synthetic-event bubbling.
+- **The sticky row-actions column must be gated on the active filter.** In `SalesOrders.tsx` the
+  `actionColumns` array is only included when `activeFilterKey === APPROVALS_FILTER_KEY`
+  (`"approvals"`); otherwise the row-actions column showed unconditionally.
 - **`tsc` not yet run** this session (the private `@agilant/toga-blox` registry needs npm creds);
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-07-13 — Fixed two SalesOrders row-actions bugs: (1) the portal dismiss overlay in
+  `SurfaceRowActions.tsx` propagated an outside-click up the React component tree to the row handler
+  and opened the record modal — added `e.stopPropagation()` (+ close) on the overlay `onClick`;
+  (2) gated the sticky `actionColumns` array in `SalesOrders.tsx` on
+  `activeFilterKey === APPROVALS_FILTER_KEY` so the row-actions column only shows under the Approvals
+  filter. (apeterson)
 - 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,

package/knowledge/INDEX.md

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

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

@@ -7,6 +7,7 @@
 | [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 MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |
+| [Compass MR/MA Order Auto-Approval & Status Gate](features/mr-ma-order-approval-and-status.md) | 2.0 | Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI pipeline (they do not originate as user-entered SA orders) and must | _underscore/Model/Compass/SalesOrder.php, _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. |  |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, library/app/client/compass.php |

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-16
-owners: ["jcardinal"]
+updated: 2026-07-13
+owners: ["jcardinal", "rgirish"]
 files:
   - _underscore/Model/Compass/PurchaseOrder.php
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
@@ -40,6 +40,15 @@ production data-integrity bug.
   `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.
+- **MA orders — item population in the ODP PO import cron:** the 3a cron
+  (`worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php`) parses ODP
+  EDI 850 POs. Its "Non-SA order handling" block creates the Compass **MA** sales order. Line
+  items are attached to the Compass SO **only in the new-SO branch**, from `$purchaseOrder['items']`
+  (`partNumber` + `UUID_ITEM_CATALOG` Compass catalog + `qtyOrdered` + `unitPrice`), mirroring the
+  ODP-facing SO item payload built lower in the same cron. The item-linking block that maps ODP
+  items back to the Compass side runs only `if (… == 'SA' || … == 'MR')` — MA is excluded there
+  because SA/MR originate in Compass (their Compass SO+items pre-exist) whereas MA is
+  ODP-originated, so nothing else would populate it.
 
 ## Data model
 - `SalesOrderItems_PurchaseOrderItems` (`Client_Compass`): `uuid`, `salesOrderItemId`,
@@ -115,7 +124,22 @@ USA and Canada share the parent handler unchanged.
   off-by-one bridge fingerprint (a `SalesOrderItems_PurchaseOrderItems` PO item linked to two
   adjacent SO items). Only SA132763 was remediated; a broader reviewed backfill is pending.
 
+- **Empty MA orders (fixed 2026-07-13 — forward only).** The 3a cron's new-SO branch created MA
+  Compass sales orders with **no** `salesOrderItems`, because item population lived only on the
+  ODP-facing SO and the back-linking block excludes MA (`if (… == 'SA' || … == 'MR')`). Empty MA
+  (and MR) shells then stick at "Pending Initial Approval" because Compass `_status` gates on
+  approvals first — see
+  [MR/MA Order Auto-Approval & Status Gate](mr-ma-order-approval-and-status.md). **Fix:** build a
+  `salesOrderItems` array from `$purchaseOrder['items']` in the new-SO branch (partNumber +
+  `UUID_ITEM_CATALOG` + qtyOrdered + unitPrice), mirroring the ODP SO item payload. Only the
+  new-SO branch changed; the SO-already-exists branch was intentionally left alone. `php -l`
+  passes. This stops NEW empty MA orders; it does **not** repair the 192 historical empties (which
+  need item backfill from the sibling ODP SO first).
+
 ## Change history
+- 2026-07-13 — Fixed empty MA orders: the 3a ODP-PO-import cron's new-SO branch now builds
+  `salesOrderItems` from the 850 PO items (the MA back-linking block excludes MA by design).
+  Forward-only; 192 historical empties still need item backfill. (rgirish)
 - 2026-06-16 — Found and fixed a SECOND source of cross-part bridge links: the Office Depot
   worker cron `3a_import_office_depot_purchase_orders.php` paired API-returned PO items to SO
   items by array index; now pairs by lineNumber. Remediated SA132763's spurious bridge +

package/knowledge/clients/compass-usa/features/mr-ma-order-approval-and-status.md

@@ -0,0 +1,124 @@
+---
+title: Compass MR/MA Order Auto-Approval & Status Gate
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-07-13
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Compass/SalesOrder.php
+  - _underscore/Model/Compass/PurchaseOrder.php
+  - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
+related:
+  - mits-po-to-so-item-linking.md
+  - ../workflows/odp-order-pipeline-to-netsuite.md
+  - ../workflows/order-lifecycle-and-data-integrity.md
+  - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
+---
+
+## Summary
+Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI
+pipeline (they do not originate as user-entered SA orders) and must **skip human approval
+entirely**. Compass's `_status` calculated field gates on **approvals FIRST**: if any stage of
+the active `ApprovalTemplate` has no `ApprovalDecision`, `_status` returns the pending-stage slug
+(`pendingInitialApproval`) *before* it ever evaluates fulfillment. So an MR/MA order that has an
+`Approval` row but no decisions is stuck at "Pending Initial Approval" regardless of shipment.
+
+Two independent root causes produced the stuck-order population, and both are addressed at the
+source (auto-approval + item population), **not** in the status SQL.
+
+## Key files / entry points
+- **`_underscore/Model/Compass/SalesOrder.php`**
+  - `_status` calculated field — approval gate runs before the shipped-only fulfillment machine
+    (see [IF stage lifecycle & order status](../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md)
+    for the fulfillment half).
+  - `postPost` — the `if ($isMrOrder)` block loops `foreach ([1,2] as $step)` and issues two
+    `internalApiRequest('POST', '/approval-decisions', …)` with `isApproved=true`,
+    note `'Auto-approved: MR order'`. **Went live 2026-06-03.**
+- **`_underscore/Model/Compass/PurchaseOrder.php`** — MR handling (`handleMrOrder`); MR/MA order
+  detection.
+- **`worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php`** — the
+  hourly ODP 850 import that creates MA orders (see the item-population fix in
+  [MITS PO → SO Item Linking](mits-po-to-so-item-linking.md)).
+
+## How it works
+### The approval gate (why empty + un-decided orders stick)
+Prod `Client_Compass` has one active `ApprovalTemplate` (id 1, `salesOrders`) with two stages —
+stage 1 = `step1` = `pendingInitialApproval`, stage 2 = `step2` = `pendingApproval`;
+`APPROVAL_DECISION_TYPE = 1`. The base `_Model_Client_SalesOrder::postPost` creates an `Approval`
+row on **any** order whenever an active template exists. Compass `_status` then requires an
+`ApprovalDecision` for every active-template stage before it will look at fulfillment. No
+decision on a stage ⇒ `_status` short-circuits to that stage's slug.
+
+### Auto-approval (the intended MR path)
+`_Model_Compass_SalesOrder::postPost` auto-approves MR orders by POSTing an approval decision for
+each of the two stages (`isApproved=true`). `_status` only checks `isApproved` on the decision —
+never the `assignedToUserId` / `decidedByUserId` columns — so a system decision with NULL user
+columns is fully valid.
+
+## Client variations
+- **MR** orders originate in Compass; their Compass SO + items pre-exist. Auto-approval covers them
+  from 2026-06-03 onward.
+- **MA** orders are **Office-Depot-originated** (created by the 3a cron) and were **never**
+  auto-approved — the `isMrOrder` check only matches numbers starting `MR`, so MA falls through
+  the gate. MA orders were additionally created as **empty shells** (see below).
+
+## Gotchas / known issues
+- **The stuck orders are EMPTY (zero `SalesOrderItems`).** All stuck MR+MA orders (and their linked
+  Compass PO) have no line items — the real line items live on a sibling **Office-Depot-facing SO**
+  (`customerId = OfficeDepot`) reachable via `SalesOrders_PurchaseOrders → PurchaseOrders_SalesOrders`.
+  A fulfilled-short-circuit in `_status` therefore does **nothing** for them (nothing to fulfill).
+- **Do NOT "fix" this in `_status`.** A speculative fulfilled-short-circuit (plus an extracted
+  `_isFullyFulfilledSql` helper) was added and then **reverted** this session: because the stuck
+  orders are empty, the short-circuit never fires. The real fix is item population + approval
+  decisions at the source.
+- **MA is still creating stuck orders until the item-population cron fix ships** — see
+  [MITS PO → SO Item Linking](mits-po-to-so-item-linking.md). Auto-approval for MA is not yet
+  implemented (the `isMrOrder` check does not match `MA`).
+
+## Prod status buckets (2026-07-13)
+| Type | NO_APPROVAL (correct — pre-template, gate falls through) | APPROVAL_NO_DECISION (STUCK) | FULLY_APPROVED |
+|---|---|---|---|
+| MR | 5922 (Sep 2025–Jan 2026) | 2927 | 583 |
+| MA | 176 | 192 | 0 |
+
+- The 5922 MR + 176 MA `NO_APPROVAL` orders pre-date the active template; they have **no**
+  `Approval` row, so `_status` skips the gate and reads correctly. They must **NOT** get an
+  `Approval` created.
+- Total stuck: **3119** (2927 MR + 192 MA). A CSV of all 3119 (type, orderNumber, orderUuid,
+  dateCreated, compassPurchaseOrder, officeDepotSalesOrder_sourceOfItems) was handed to
+  ops/integration for remediation.
+
+## Historical MR remediation (approval-decision backfill)
+A one-off, idempotent, transaction-wrapped SQL backfill unsticks the 2927 historical MR orders by
+inserting the two auto-approval `ApprovalDecisions` (one per stage, mirroring `postPost`'s
+`foreach([1,2])`). Each row: `approvalTemplateStageId` 1/2, `approvalDecisionTypeId=1`,
+`isApproved=1`, `assignedToUserId`/`decidedByUserId` NULL, note
+`'Auto-approved: MR order (historical backfill)'`, `dtDecision NOW()`.
+
+Safe scoping baked in — **decisions only, never Approvals**:
+- **`INNER JOIN Approvals` (`recordId=14`)** so it can only add decisions to orders that *already*
+  have an `Approval`. Structurally it cannot touch the `NO_APPROVAL` orders (which are already
+  correct and must not get an Approval).
+- **Per-stage `NOT EXISTS`** ⇒ idempotent / re-runnable.
+- Includes a PREVIEW count query (prod: 2927 orders → 2927 step-1 + 2927 step-2 rows). Workflow:
+  run on beta, verify, COMMIT; then production.
+- Does **not** create Approvals; does **not** handle MA (MA orders are empty and need item backfill
+  from the sibling ODP SO first).
+
+## Change history
+- 2026-07-13 — Diagnosed the MR/MA "Pending Initial Approval" stuck-order bug: `_status` gates on
+  approvals before fulfillment; MR orders created 2026-02-04..2026-06-02 got an Approval but no
+  decisions (auto-approval only live from 2026-06-03), and MA orders were never auto-approved and
+  are empty shells. Reverted a speculative `_status` fulfilled-short-circuit (stuck orders are
+  empty, so it never fires). Built an idempotent, decisions-only MR approval-decision backfill
+  (2927 orders) scoped by `INNER JOIN Approvals` so it can never create an Approval, and a CSV of
+  all 3119 stuck orders for ops. MA item population fixed separately at the 3a cron. (rgirish)
+
+## Related docs
+- [Compass MITS PO → SO Item Linking](mits-po-to-so-item-linking.md) — the 3a cron item-population fix that stops NEW empty MA orders.
+- [Compass ODP Order Pipeline to NetSuite](../workflows/odp-order-pipeline-to-netsuite.md)
+- [IF Stage Lifecycle & Order Status](../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md) — the shipped-only fulfillment half of Compass `_status`.

package/package.json

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