toga-ai 1.0.150 → 1.0.152

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

@@ -7,4 +7,4 @@
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |
-| [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql |
+| [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
+updated: 2026-06-19
 owners: ["jcardinal", "mhammontree", "dfranks"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -22,6 +22,8 @@ files:
   - dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql
   - dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql
   - dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql
+  - dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
+  - dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
 related:
   - recursive-item-fulfillments.md
 ---
@@ -98,6 +100,15 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   posts unit tracking + header tracking via the bridge routes; `Model/Compass/SalesOrder.php::_trackingNumbers`
   reads through the bridges. The `item-fulfillments-for-sales-order-items` TableView was rebuilt
   (see the compass-usa client doc).
+- **NYCHH (Client_Nychh) & Quad (Client_Quad):** the same two item-fulfillment TableViews
+  (`item-fulfillments-for-sales-orders` id 12, `item-fulfillments-for-sales-order-items` id 13)
+  were rebuilt to mirror Compass's final state — re-rooted at `ItemFulfillmentItems` (29) with
+  OUTER unit/tracking chain and tracking via the item-level bridge **318** (`dbchanges2/Client_Nychh/2026-06-19a`,
+  `dbchanges2/Client_Quad/2026-06-19a`). NYCHH had no custom columns; Quad preserves three
+  Units-level customs (`c_hostIdentifier`/CustomRecordFields 1, `c_pkIdentifier`/2, `macAddress`/rf 1432),
+  re-attached to the Units join. **Caveat — record 318 is empty in both client DBs today** (see the
+  portability gotcha below), so the re-root immediately fixes the "0 records" bug but the
+  Outbound Tracking # / Carrier columns stay blank until item-level tracking is backfilled.
 - **Prudential (Client_Prudential):** Dell posts the legacy `advanceShippingNoticeUnits` key with flat
   tracking — a PRE/POST interceptor rewrites it (see the prudential client doc).
 - **NetSuite-integrated clients:** `Trait/Netsuite/ItemFulfillment.php` now reads
@@ -143,7 +154,10 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
     **Quad** (`Client_Quad/2026-06-18a - ...`, all of 317-322) so far. Each new client is whack-a-mole until
     the chain is folded back into the base migration + blank-client template.
 
+- **Porting the item-fulfillment TableView fix to another client is two independent decisions, not a copy-paste.** The **re-root** (Units 31 → ItemFulfillmentItems 29 + OUTER unit chain) is universally portable and fixes the "0 records" bug everywhere. The **tracking source is client-specific**: Compass writes one tracking number per item fulfillment at the **item level (318)**, so its views read 318. Other clients populate different bridge levels — verify with `SELECT COUNT(*)` per bridge before choosing. As of 2026-06-19, **record 318 is empty in `Client_Nychh` and `Client_Quad`**; their tracking lives at the **IF/shipment level (317)** (covers IFIs: NYCHH 7955/10049 ≈ 79%, Quad 4878/4967 ≈ 98%) and the **unit level (319)** (≈ 7–9% — serialized only). Copying Compass's 318 join into a client that doesn't write 318 yields a structurally-correct view with permanently blank tracking until 318 is backfilled. (NYCHH's pre-fix view pointed at the now-deleted record 41 = old IF-level/package bridge, i.e. it originally intended IF-level 317.)
+
 ## Change history
+- 2026-06-19 — Applied the Compass item-fulfillment TableView fix to **NYCHH** and **Quad** (`Client_Nychh`/`Client_Quad` `2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql`): re-rooted views 12 & 13 at ItemFulfillmentItems, item-level tracking via 318, preserving Quad's three Units-level custom columns. Confirmed read-only that record 318 is empty for both clients (tracking blank until backfilled) — their data is at 317 (IF-level, ~79%/~98% coverage) and 319 (unit-level); recorded the portability gotcha. (jcardinal)
 - 2026-06-18 — Quad's NetSuite TOGa Supply sync (`sync_togasupply_quad.php`) hit the bridge ACL gap in prod: 403 EZ-1 on `item-fulfillment-tracking-numbers` (Sentry 7559037554, 46×, since the 2026-06-15 deploy). Confirmed `Client_Quad` perms 380-385 (recs 317-322, role 1) had 0 logic groups; added the chain via `Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql` (all 6 bridges, idempotent, RANDOM_BYTES uuids). Noted the gap surfaces via the per-client sync, not only UI reads. (dfranks)
 - 2026-06-16 — Caught a migration code-update miss: four queries in `Model/Client/ItemFulfillment.php` (`upsShipmentApi`, `fedexShipmentApi`, `fulfill`, `createNetsuiteItemFulfillment`) still joined the dropped `ItemFulfillmentPackages` table to resolve tracking — repointed to `ItemFulfillments_TrackingNumbers`. See the carrier-shipping-labels doc. (mhammontree)
 - 2026-06-16 — Found + documented the bridge ACL gap: the migration creates bridge `AclRecordPermissions` (317–322) but not their `AclLogicGroups`/`AclLogicGroupExpressions`/`AclRecordExpressions` chain → 403 "No ACL Logic Groups defined" for non-Super-User reads (confirmed prod + all clients). Recorded the `slug='all'`/`sqlExpression='1'` fix for Core + per-client, plus the Client-DB `Records`-table caveat. (mhammontree)

package/knowledge/INDEX.md

@@ -40,8 +40,10 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)
 - **GroWrk** (`growrk`) → [clients/growrk/INDEX.md](clients/growrk/INDEX.md)
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
+- **NYC Health & Hospitals** (`nychh`) → [clients/nychh/INDEX.md](clients/nychh/INDEX.md)
 - **Office Depot** (`office-depot`) → [clients/office-depot/INDEX.md](clients/office-depot/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
+- **Quad Graphics** (`quad`) → [clients/quad/INDEX.md](clients/quad/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
 - **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
 

package/knowledge/clients/nychh/INDEX.md

@@ -0,0 +1,5 @@
+# Client: NYC Health & Hospitals `nychh`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. |  |

package/knowledge/clients/nychh/profile.md

@@ -0,0 +1,40 @@
+---
+title: "NYC Health & Hospitals"
+framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - toga2-supply
+  - dbchanges2
+project: _Underscore
+client: nychh
+type: profile
+status: active
+updated: 2026-06-19
+owners: ["jcardinal"]
+files: []
+related:
+  - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
+---
+
+## Summary
+NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema
+`Client_Nychh`. Their supply-chain / fulfillment data drives the TOGa Supply item-fulfillment
+table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
+
+## Platforms & data
+- **2.0:** `_underscore` backend, prod schema `Client_Nychh`. Item fulfillments, units, and
+  tracking numbers follow the shared tracking-number bridge model.
+
+## Key features (this client)
+- Item-fulfillment table views (`item-fulfillments-for-sales-orders`,
+  `item-fulfillments-for-sales-order-items`) rebuilt 2026-06-19 to mirror the Compass fix —
+  re-rooted at `ItemFulfillmentItems` with item-level (record 318) tracking. See
+  [Tracking-Number Bridge Migration](../../2.0/apps/_underscore/features/tracking-number-bridges.md)
+  (Client variations + the TableView portability gotcha).
+
+## Notes
+- Tracking data: record 318 (item-level) is currently empty for this client; their tracking
+  populates the IF/shipment level (record 317). The rebuilt views use 318 (per the Compass
+  pattern) and will show tracking once item-level tracking is backfilled.
+- This profile is a starting point; expand as more NYCHH-specific behavior is captured.

package/knowledge/clients/quad/INDEX.md

@@ -0,0 +1,5 @@
+# Client: Quad Graphics `quad`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Quad Graphics](profile.md) | 2.0 | Quad Graphics is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Quad`. |  |

package/knowledge/clients/quad/profile.md

@@ -0,0 +1,46 @@
+---
+title: "Quad Graphics"
+framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - toga2-supply
+  - dbchanges2
+project: _Underscore
+client: quad
+type: profile
+status: active
+updated: 2026-06-19
+owners: ["jcardinal"]
+files: []
+related:
+  - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
+---
+
+## Summary
+Quad Graphics is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Quad`.
+Their supply-chain / fulfillment data drives the TOGa Supply item-fulfillment table views.
+Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
+
+## Platforms & data
+- **2.0:** `_underscore` backend, prod schema `Client_Quad`. Item fulfillments, units, and
+  tracking numbers follow the shared tracking-number bridge model.
+- **NetSuite TOGa Supply sync:** the per-client worker cron exercises the IF/IR tracking-number
+  bridge routes (see the bridge-migration doc's ACL-gap notes — Quad hit the 403 EZ-1 gap in prod).
+
+## Key features (this client)
+- **Unit-level custom fields** on the item-fulfillment views: `c_hostIdentifier`
+  (CustomRecordFields id 1), `c_pkIdentifier` (id 2), and `macAddress` (RecordField 1432) —
+  all defined on the Units record (31).
+- Item-fulfillment table views (`item-fulfillments-for-sales-orders`,
+  `item-fulfillments-for-sales-order-items`) rebuilt 2026-06-19 to mirror the Compass fix —
+  re-rooted at `ItemFulfillmentItems` with item-level (record 318) tracking, preserving the
+  three Units-level custom columns. See
+  [Tracking-Number Bridge Migration](../../2.0/apps/_underscore/features/tracking-number-bridges.md).
+
+## Notes
+- Tracking data: record 318 (item-level) is currently empty for this client; their tracking
+  populates the IF/shipment level (record 317, ~98% coverage) and unit level (record 319). The
+  rebuilt views use 318 (per the Compass pattern) and will show tracking once item-level
+  tracking is backfilled.
+- This profile is a starting point; expand as more Quad-specific behavior is captured.

package/package.json

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

package/skills/capture/SKILL.md

@@ -103,6 +103,35 @@ not just one. Always include `AUTHOR_USERNAME`, and treat the field as cumulativ
    - If the repo is **not registered**, run **New-repo onboarding** (below) — ask everything.
    - If you cannot confidently determine the repo/framework/project/client, **ask**.
 
+## Step 2c — Detect new & modified clients (automatic — never wait to be asked)
+
+Client coverage is **your** responsibility, not the developer's. They will mention clients in
+passing ("for the NYCHH client", "Client_Quad", "Compass and also Rate") and **expect the KB to
+end up correct without being told to add anything.** On every capture, before Step 3:
+
+1. **Scan the whole conversation** for every client referenced in any form — formal name
+   ("NYC Health & Hospitals"), short name ("NYCHH", "Quad"), slug (`nychh`), or database name
+   (`Client_Nychh` / `Logs_Nychh` / `Archive_Nychh` → tenant `Nychh` → slug `nychh`). Build the
+   full set; there may be **several** new clients in one session — handle **all** of them.
+2. **Resolve each** to a slug and check `knowledge/clients/<slug>/`. Cross-check the manifest
+   (`knowledge.js manifest`) so a client that exists under a different slug spelling isn't
+   duplicated.
+3. **For each client with no folder → run New-client onboarding automatically** (below). Do
+   **not** wait for the developer to say "add this client." Capture the **formal name** from
+   what the developer already wrote in the conversation; **only ASK if the formal name was never
+   stated** (you may ask once, listing all unknown clients together: "What are the formal names
+   for <slug-a>, <slug-b>?"). Create `clients/<slug>/profile.md`, seed `apps` from the repos this
+   session touched for that client.
+4. **For each existing client whose behavior this session changed** (a new client-specific
+   override, a corrected workflow, a new client-scoped migration, an `apps` repo now in play) →
+   **UPDATE that client's profile / client-feature / workflow automatically** (and its `apps` per
+   Step 5b). Modifications to an existing client are captured without being asked, same as
+   additions.
+
+This step is **mandatory and auto-applied** (it is ordinary non-elevated client-doc work per
+Step 4) — the only permitted interruption is asking for a formal name you genuinely cannot find
+in the conversation. Report every client added or modified in the Step 7 summary.
+
 ## Step 3 — Match against existing knowledge
 
 For each distinct thing worked on, search for a doc that already covers it:
@@ -382,8 +411,9 @@ Append the entry to `registry.json`, then continue. `validate` will confirm cons
 
 ## New-client onboarding (client has no `knowledge/clients/<slug>/` folder yet)
 
-When this session's work is for a client with no `clients/<slug>/` folder, before writing
-any client docs:
+**Triggered automatically by Step 2c** for every new client detected in the conversation — run
+it for **each** one without being asked, however many there are. When a referenced client has no
+`clients/<slug>/` folder, before writing any client docs:
 
 1. **Slug** — confirm the folder slug (lowercase, hyphenated, e.g. `compass-usa`). The slug
    is used only for the folder name.