toga-ai 1.0.280 → 1.0.282

package/knowledge/1.0/apps/library/features/netsuite-suiteql-api-reference.md

@@ -262,6 +262,21 @@ work; the pk is `nkey`). Columns: `addr1`, `addr2`, `addressee`, `attention`, `c
 - `entityid` and `companyname` are split in SuiteQL; SOAP concatenated them as
   `"<entityid> <companyname>"`. When they're equal, return the value once (don't duplicate).
 
+## `systemnote` table — field-change forensics
+
+The audit trail of individual field changes — use it to see exactly **who / what / when / how** a
+field changed, **including sublist LINE edits that fire no User Event and therefore no webhook**
+(see the sale-import doc's AMQ line-field blind spot).
+
+- **Performance: filter by `field` + `"date"`, NEVER by `recordid` alone.** A `recordid`-only
+  filter is a pathological full scan (**~279s**); adding a `field` predicate + a `"date"` range
+  drops it to **~1s**.
+- Columns: `context` (`UIF` = user interface; also `CSV`, `WS`, …), `name` (the acting user),
+  `role`, `recordid`, `field`, `linetransactionid`, `lineid`, `oldvalue`, `newvalue`, and `"date"`
+  (a reserved word — quote it). A sublist line-field inline edit (e.g. `MCOSTESTIMATE`) shows up
+  here as a `context='UIF'` row with the acting `name` even though it bumped **no**
+  `lastmodifieddate` and fired no webhook.
+
 ## Custom fields
 
 | NS internalId | Script id | Description |
@@ -339,9 +354,24 @@ numbers. Budget hours for multi-year runs and launch them under `nohup`/`tmux`.
   Measured against the Forecast2 reconciliation checker (TRUE-79968). Use `> 0` / `NVL(col,0) <> 0`
   for a custom ref column you only need to test for presence in an aggregate; reserve `IS NOT NULL`
   for non-aggregate row filters.
+  - **⚠ `> 0` is NOT a universal fix — it is column-dependent.** A predicate on a *different*
+    custom column, `tl.custcol_item_sku > 0`, **never returned even as a STANDALONE aggregate**
+    (not just inside the UNION+MOD fingerprint), while `tl.custcol_sales_rep_line > 0` in the same
+    query stayed fast (~8s). Merely **SELECTing** the custom column is cheap either way. **Durable
+    rule when a custom-column predicate hangs:** keep the fast predicates in SQL, **SELECT** the
+    problem column, and apply that gate in **PHP** — do not assume `> 0` will rescue every custom
+    column. (TRUE-79973, `test/@dave/checker.php` / `fixer.php`.)
 
 ## Change history
 
+- 2026-07-07 — **Added the `systemnote` field-change forensics section and qualified the custom-column
+  perf rule** (Forecast2 SALES profit-drift forensics). `systemnote` filtered by `field`+`"date"` is
+  ~1s vs ~279s by `recordid` alone; it carries `context` (`UIF`), `name` (acting user), `role`,
+  `linetransactionid`, `lineid`, `oldvalue`/`newvalue` — and is the only NetSuite-side record of a
+  sublist line-field inline edit (which bumps no `lastmodifieddate` and fires no webhook). Also
+  qualified the `IS NOT NULL`→`> 0` note: `> 0` is **column-dependent, not universal** —
+  `custcol_item_sku > 0` hung even standalone while `custcol_sales_rep_line > 0` stayed fast; when a
+  custom-column predicate hangs, SELECT the column and gate in PHP (TRUE-79973). (dfranks)
 - 2026-06-30 — **Recorded the `IS NOT NULL` vs `> 0` planner trap for custom `transactionline`
   columns in aggregate queries** (TRUE-79968): a custom employee-ref column filtered with
   `IS NOT NULL` inside a power-sum `GROUP BY` aggregate scanned ~15× slower (~122s) than the

package/knowledge/1.0/apps/togadesk/features/field-service-dispatch.md

@@ -57,6 +57,28 @@ the originating page. Status changes are audited through `RepairHistory` (`repai
 onsite/install started → review → closed; depot repairs add parts/tracking steps. Bulk actions
 exist for closing installs and editing onsite tickets.
 
+### Status is a denormalized cache (`repair_orders.status`)
+This is **shared, client-agnostic** behavior — every repair-order client is subject to it.
+- Status transitions are **recorded on `repair_order_notes.newstatus`**, not written to
+  `repair_orders.status` directly. `Repair::addNotes`, `Repair::changeStatus`, and
+  `Repair::reworkRepair` (`class.repair.php`) each only create a note — none writes the
+  status column itself.
+- **`repair_orders.status` is a denormalized CACHE**, reconciled from the latest note **only
+  when** `App_Model_TogaDesk_RepairOrder::updateStatus()` runs (fired by the central actions
+  `scheduleDispatch`, `technicianOnsite`, `technicianEnRoute`, `awaitingDispatch`,
+  `reworkAwaitingScheduling`, and the part flows). `updateStatus()` writes via a raw `UPDATE`
+  with no history row (see gotchas).
+- **The LIVE status the UI shows is DERIVED, not the cache:** the grid/detail SELECTs use
+  `qqStatus() AS status` (`repairorder.php` ~L356), recomputing status from the latest note on
+  read. So the UI can show a status the cache column does not currently hold.
+- **Consequence:** any consumer that reads the cached `repair_orders.status` (e.g. the worker
+  sync crons) diverges from the derived UI status whenever a note changed status but no
+  `updateStatus()` ran afterward — the consumer then acts on a **stale** status. This is
+  exactly how a DOE hold set via a comment failed to sync (see
+  [NYCDOE Hold-Status Sync](../../../../clients/nycdoe/features/hold-status-sync.md)).
+- `updateStatus()`'s notification block is **enqueue-only** — it inserts dedup'd
+  `repair_order_notifications` rows; it sends no inline email.
+
 ## UPS shipment / carrier-account billing (Prepare Shipment flow)
 The "PREPARE SHIPMENT" button opens modal `desk/template/modals/central/addTracking.php`,
 whose carrier/account dropdown is built from the constant
@@ -126,6 +148,12 @@ always confirm the client arm before changing shared central logic.
   account-location map noted under *UPS shipment / carrier-account billing*.
 
 ## Change history
+- 2026-07-07 — TRUE-80060 (togadesk portion): documented the durable, client-agnostic
+  status-cache model — status transitions land on `repair_order_notes.newstatus`;
+  `repair_orders.status` is a denormalized cache reconciled only by `updateStatus()`; the UI
+  shows the derived `qqStatus() AS status`, so cache-reading consumers (e.g. worker crons) can
+  act on a stale status when a note changed status without a following `updateStatus()`. Noted
+  `updateStatus()`'s notification block is enqueue-only. (mhammontree)
 - 2026-07-07 — TRUE-80060: documented the shared `qqStatus()`/`updateStatus()` status-recompute
   hold gates (in `library/app/model/togadesk/repairorder.php`) — silent raw-`UPDATE` overwrite,
   hold states must be gated or dropped, the six-hold-variant collapse to base `STATUS_HOLD`, and

package/knowledge/1.0/apps/worker/features/forecast2-netsuite-reconciliation.md

@@ -493,11 +493,42 @@ None — Forecast2 is a single shared dataset.
   `checker.php` (JE arm) and `fixer.php` (both JE queries) with inline comments warning against
   reverting. See the SuiteQL API reference for the general rule. (Use `> 0`, or `NVL(col,0) <> 0`,
   never `IS NOT NULL`, for a custom employee-ref `transactionline` column in a SuiteQL aggregate.)
+  **⚠ But `> 0` is column-dependent, not a universal fix:** `tl.custcol_item_sku > 0` hung even as a
+  standalone aggregate while `tl.custcol_sales_rep_line > 0` stayed fast (~8s) — when a custom-column
+  predicate hangs, SELECT the column and gate in PHP instead. (TRUE-79973; see the SuiteQL API ref.)
+- **These reconcilers are the ONLY backstop for NetSuite sublist line-field inline edits — the
+  real-time webhook path is structurally blind to them.** Editing a line-level field inline in the
+  NetSuite UI (e.g. estimated cost `TRANLINE.MCOSTESTIMATE`) fires **no** User Event `afterSubmit`
+  (not create/edit/`xedit`) and **does not bump `lastmodifieddate`** — it writes only a `systemnote`
+  (context `UIF`). So the AMQ enqueuer never fires (no webhook) **and** any `lastmodifieddate`-windowed
+  `list*()`/cron sync misses it too — `Forecast.Sales` **cost/profit drifts while revenue reconciles**
+  (the $0-revenue cost-line case). This is the concrete mechanism behind the Summary's "older rows
+  whose NetSuite values change (e.g. cost re-valuation) are never re-pulled." `checker`/`fixer` catch
+  it because they reconcile a chosen `tranDate` range directly against NetSuite by internal id, not by
+  `lastmodifieddate`. Real case: invoice 6715127 (2026-02-20) drifted $3,392.70; recurring/multi-user
+  (~12 line-cost edits/day). See the sale-import doc's AMQ blind-spot section. To pinpoint *who/what/
+  when* changed a line, poll SuiteQL `systemnote` filtered by `field`+`"date"` (see the SuiteQL API ref).
+- **Inbound webhook forensics — `db_logs` `Logs.Webhook`.** Every inbound webhook TOGA receives is
+  logged here (columns: `dtStamp`, `sourceIp`, `method`, `route`, `requestHeaders`, `requestPayload`);
+  NetSuite events are `route='/netsuite'` with payload `{recordType,internalId,eventType,action,timestamp}`.
+  Logging began **~2026-06-18**, so its absence before then is not evidence a webhook didn't fire. Use it
+  to confirm whether a given transaction's edit actually produced an inbound POST (paired with the AMQ
+  enqueuer execution log on the NetSuite side).
 - These tools live in `test/@dave/` (developer tooling), but `trueup_open_orders` has been run
   against production. The `Defaults`/checkpoint mechanics of the scheduled sync are separate.
 
 ## Change history
 
+- 2026-07-07 — **Recorded that these reconcilers are the only backstop for NetSuite sublist
+  line-field inline edits + added `Logs.Webhook` forensics** (SALES profit-drift forensics; invoice
+  6715127, 2026-02-20, $3,392.70). A line-level inline edit (e.g. `TRANLINE.MCOSTESTIMATE`) fires no
+  User Event `afterSubmit` (not create/edit/`xedit`) and does **not** bump `lastmodifieddate` — only
+  a `systemnote` (context `UIF`) — so both the AMQ webhook path and any `lastmodifieddate`-windowed
+  sync miss it; profit drifts while revenue reconciles. `checker`/`fixer` catch it (they reconcile by
+  `tranDate` range + internal id, not `lastmodifieddate`). Documented `db_logs.Logs.Webhook` for
+  inbound-webhook forensics (route `/netsuite`, payload shape; logging began ~2026-06-18) and qualified
+  the custom-column perf rule (`> 0` is column-dependent — `custcol_item_sku > 0` hung even standalone;
+  SELECT + gate in PHP). (dfranks)
 - 2026-06-30 — **Made the fixer the cleanup mechanism for no-rep JE rows + killed a ~15× SuiteQL
   planner trap (TRUE-79968, dfranks).** The importer now keeps only rep-bearing JE lines (see the
   sale-import doc); to let `fixer.php` purge any pre-existing no-rep `Forecast.Sales` JE rows with no

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

@@ -9,7 +9,7 @@
 | [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 |
 | [Error Reporting — Issue/Event Aggregation (exceptionHandler)](features/error-reporting-issue-event.md) | `_underscore`'s global exception handler persists every uncaught exception into a two-table **Issue / Event** model in the **shared Core Logs DB** (`_underscore | _underscore/Error.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |
-| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
+| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |

package/knowledge/2.0/apps/_underscore/features/forecast-sale-import.md

@@ -30,8 +30,8 @@ files:
   - test/@dave/probe_je_accounts.php
   - test/@dave/probe_je_shape.php
   - test/@dave/fixer.php
-  - test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js
-  - test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js
+  - test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js
+  - test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js
 related:
   - ../architecture.md
   - ../../worker2/architecture.md
@@ -295,6 +295,39 @@ events as specific **subtypes** (`inventoryItem`, `nonInventoryResaleItem`, `kit
 would be needed only for a future real-time item webhook, **not** for this Sales importer
 (which keeps items fresh via the hourly item pull cron plus the inline self-heal).
 
+### AMQ enqueuer trigger behavior + the line-field inline-edit blind spot (durable — read for any real-time NS→TOGA sync debugging)
+The enqueuer is `customscript_ue_amq_enqueue` (**script id 2618**), a UserEvent `afterSubmit`
+deployed **one-per-record-type** (invoice/cashSale/creditMemo/cashRefund/journalEntry/salesOrder/
+opportunity/items/…). The **invoice** deployment (primarykey **16019**) is **RELEASED**,
+`allroles=T`, `allemployees=T`, with **every execution context enabled** — so it is NOT
+restricted by user/role/context.
+
+**What DOES fire it:** record `create` / `edit` / `delete`, **and `xedit`** — a BODY-field inline
+edit (this is the source of the `eventType:"xedit"` webhooks, built by the script's own
+`buildPayload`). On fire it logs `AMQ enquerer triggered by "<context.type>" event` then
+`AMQ enqueued {recordType,internalId,action}`, enqueues to custom record
+`customrecordcustomrecord_api_msg_queue` (**internal id 1185**), and kicks the drainer
+`customscript_ss_amq_drain`.
+
+**What does NOT fire it — the structural blind spot:** editing a **sublist LINE field**
+(e.g. estimated cost `TRANLINE.MCOSTESTIMATE`) inline via the NetSuite UI raises **NO** record
+User Event `afterSubmit` — **not `create`, not `edit`, not `xedit`**. It also does **NOT** bump
+the transaction's `lastmodifieddate`; it writes only a **`systemnote`** (context `UIF`). So the
+enqueuer never fires → no AMQ row → no `webhook.togahub.com/netsuite` POST → `Forecast.Sales`
+cost/profit **silently drifts**. When the edited line is $0-revenue (a fee/cost line), **revenue
+reconciles while profit drifts** — the classic symptom. Proven with live enqueuer execution-log
+evidence: two invoices whose ONLY change that day was a cost line-edit had **zero** "triggered by"
+entries, while 8 other cost-edited invoices that also had normal create/edit activity **did** fire
+and synced. This is recurring/multi-user (~12/day; 35 `MCOSTESTIMATE` edits in 3 days by 9 users).
+
+**Corollary gotcha: `lastmodifieddate` is NOT a reliable change signal for line-cost edits** — a
+line-field inline edit leaves it untouched, so **both** the webhook pipeline **and** any
+`lastmodifieddate`-windowed `list*()`/cron sync miss it entirely. **Only reconciliation**
+(`checker`/`fixer` — see the reconciliation doc) **or a `systemnote` poll** catches this drift.
+Forensic tool for who/what/when/how a line changed: SuiteQL `systemnote` filtered by `field` +
+`"date"` (see the SuiteQL API-reference `systemnote` section — filtering by `recordid` alone is a
+~279s full scan; by `field`+`"date"` it's ~1s).
+
 ## E2E testing playbook + harness inventory (run this cold)
 This section is the reusable procedure for verifying the NetSuite → `Forecast.Sales` path
 end-to-end against a **local** Forecast mirror. It is written to be runnable in a future
@@ -452,6 +485,18 @@ record is deleted in NetSuite.)
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 2026-07-07 — **Documented the AMQ enqueuer's line-field inline-edit blind spot** (Forecast2 SALES
+  profit-drift forensics; invoice 6715127 / 2026-02-20 / $3,392.70). Editing a **sublist LINE
+  field** (e.g. cost `TRANLINE.MCOSTESTIMATE`) inline in the NetSuite UI raises **no** record UE
+  `afterSubmit` (not create/edit/**xedit**), does **not** bump `lastmodifieddate`, and writes only a
+  `systemnote` (context `UIF`) — so `customscript_ue_amq_enqueue` never fires and `Forecast.Sales`
+  cost/profit silently drifts (revenue reconciles when the line is $0-revenue). Proven via live
+  enqueuer execution logs (2 cost-line-only-edited invoices had zero "triggered by" entries vs 8
+  that had other activity and synced); recurring/multi-user (~12/day). Corollary:
+  `lastmodifieddate` is not a reliable change signal for line-cost edits — only reconciliation or a
+  `systemnote` poll catches them. Also recorded the enqueuer's exact trigger surface (script id
+  2618; invoice deployment pk 16019 RELEASED/allroles/allemployees; fires create/edit/delete +
+  `xedit` BODY edits; enqueues to custom record 1185; kicks `customscript_ss_amq_drain`). (dfranks)
 - 2026-07-07 — **CORRECTION: JE lines DO carry an item — in the custom column
   `custcol_item_sku`, not the native item field** (TRUE-79973, dfranks). Live probe
   2026-07-07 confirmed native `transactionline.item` / REST `line.item` is empty on **all

package/knowledge/clients/nycdoe/INDEX.md

@@ -2,6 +2,6 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [NYCDOE Ticket Hold-Status Sync (ServiceNow ⇄ TOGaDesk)](features/hold-status-sync.md) | 1.0 | DOE ticket **hold** status must round-trip between ServiceNow (SNOW) and TOGaDesk and **stay held** — holds are SLA-bearing in both systems. | worker/crons/sync/nycdoe/send_ticket_updates.php, worker/crons/sync/nycdoe/process_tickets.php, worker/crons/sync/nycdoe/send_request_item_updates.php, library/app/model/togadesk/repairorder.php, library/app/api/nycdoev2.php |
+| [NYCDOE Ticket Hold-Status Sync (ServiceNow ⇄ TOGaDesk)](features/hold-status-sync.md) | 1.0 | DOE ticket **hold** status must round-trip between ServiceNow (SNOW) and TOGaDesk and **stay held** — holds are SLA-bearing in both systems. | worker/crons/sync/nycdoe/send_ticket_updates.php, worker/crons/sync/nycdoe/process_tickets.php, worker/crons/sync/nycdoe/send_request_item_updates.php, library/app/model/togadesk/repairorder.php, library/app/api/nycdoev2.php, togadesk/desk/includes/classes/class.repair.php |
 | [NYCDOE ServiceNow / ASN Integration](features/servicenow-integration.md) | 1.0 | The NYCDOE/ServiceNow integration mirrors DOE's ServiceNow tickets (Incidents + RITMs) into local tables, turns vendor shipment notices into NetSuite Sales Orde | worker/crons/sync/nycdoe/import_asn.php, worker/crons/sync/nycdoe/import_inc.php, worker/crons/sync/nycdoe/legacy_import_asn.php, worker/crons/sync/nycdoe/legacy_process_asn_queue.php, worker/crons/sync/nycdoe/process_tickets.php, worker/crons/sync/nycdoe/1_send_asn_to_netsuite.php, worker/crons/sync/nycdoe/2_send_serials_to_netsuite.php, worker/crons/sync/nycdoe/3_create_installation_ticket.php, worker/crons/sync/nycdoe/send_ticket_updates.php, worker/crons/sync/nycdoe/send_request_item_updates.php, worker/crons/sync/nycdoe/send_nycdoe_proof_of_delivery.php, worker/crons/sync/nycdoe/sync_nycdoe_locations.php, worker/crons/sync/nycdoe/receive_edi_purchase_orders.php, worker/crons/sync/nycdoe/send_edi_open_invoices.php, worker/crons/notifications/nycdoe/, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.notification.json, library/app/api/nycdoe.php, library/app/api/nycdoev2.php, library/app/asnprocessor/manufacturer.php, library/app/asnprocessor/apple.php, library/app/asnprocessor/lenovo.php, library/app/asnprocessor/lexmark.php, library/app/asnprocessor/acer.php, library/app/edi.php |
 | [New York City Department of Education](profile.md) | 1.0 | NYC DOE (New York City Department of Education) is a TOGA client whose entire integration runs in the **1.0 worker tier** (~30 cron scripts under `worker/crons/ |  |

package/knowledge/clients/nycdoe/features/hold-status-sync.md

@@ -14,6 +14,7 @@ files:
   - worker/crons/sync/nycdoe/send_request_item_updates.php
   - library/app/model/togadesk/repairorder.php
   - library/app/api/nycdoev2.php
+  - togadesk/desk/includes/classes/class.repair.php
 related:
   - servicenow-integration.md
   - ../profile.md
@@ -25,14 +26,14 @@ related:
 DOE ticket **hold** status must round-trip between ServiceNow (SNOW) and TOGaDesk and
 **stay held** — holds are SLA-bearing in both systems. This doc covers the bidirectional
 hold-status sync for DOE Incidents (INC) and Request Items (RITM), the authoritative
-business rule that governs it, and the two independent defects that let holds silently
-revert. It is the status-sync companion to the broader
+business rule that governs it, and the three independent defects that let holds silently
+revert or never reach ServiceNow. It is the status-sync companion to the broader
 [ServiceNow / ASN integration](servicenow-integration.md) doc; the underlying crons and
 `App_Api_NYCDOEV2` plumbing are documented there.
 
-> **Two distinct hold-revert paths — different repos, mechanisms, and revert targets.**
-> A held DOE order could be knocked out of hold by *either* of two unrelated code paths;
-> both had to be closed:
+> **Three distinct hold-failure paths — different repos, mechanisms, and symptoms.**
+> A held DOE order could fail to persist/propagate via *any* of three unrelated code paths;
+> all three had to be closed (see *Coordinated three-repo fix & deploy ordering* below):
 > - **TRUE-79922 (worker crons):** the SNOW-side `state` 3⇄2 oscillation — an outbound
 >   self-clobber pushing `state:2` over a held `state:3`, plus an inbound wrong-field read
 >   — reverted the order to **"In Progress"**. Fixed; see *Change history* + the sections
@@ -43,6 +44,14 @@ revert. It is the status-sync companion to the broader
 >   *Local status recompute* below. This defect is in a **shared, client-agnostic** model
 >   method — surfaced by DOE but affecting every TogaDesk repair-order client; the durable
 >   mechanism lives in [Field-Service Dispatch](../../../1.0/apps/togadesk/features/field-service-dispatch.md).
+> - **TRUE-80060 (`togadesk` desk app):** a hold set **via a note/comment**
+>   (`Repair::addNotes`) never reached ServiceNow at all. `addNotes` recorded the new status
+>   only on `repair_order_notes.newstatus` — never writing the `repair_orders.status` cache
+>   nor calling `updateStatus()` — and the TRUE-75199 real-time-sync optimization suppressed
+>   `repair_orders.dtUpdated`. The worker reads the **cached** `repair_orders.status` and
+>   selects orders by `dtUpdated >= dtSynced`, so an on-hold-with-comment order left a stale
+>   non-hold cache **and** an un-bumped `dtUpdated` — the worker never selected it and never
+>   pushed `state:3`. Fixed; see *Hold set via a note/comment* below.
 
 > DOE "tickets" are **`repair_orders`** rows (`App_Model_TogaDesk_RepairOrder`,
 > `db_togadesk` / legacy `TOGaDeskSupport`, **clientid = 16**) — NOT the generic `tickets`
@@ -117,6 +126,41 @@ revert. It is the status-sync companion to the broader
 - The revert is **silent** — `updateStatus()` writes via a raw `UPDATE` with **no**
   `repair_order_history` / `repair_order_notes` entry.
 
+### Hold set via a note/comment (`addNotes`) — TRUE-80060 (togadesk)
+- In TOGaDesk a status change carried on a comment goes through `Repair::addNotes`
+  (`togadesk/desk/includes/classes/class.repair.php`), which records the new status on
+  `repair_order_notes.newstatus`. Because `repair_orders.status` is a denormalized cache
+  reconciled only by `updateStatus()` (see
+  [Field-Service Dispatch](../../../1.0/apps/togadesk/features/field-service-dispatch.md)),
+  a hold set this way did **not** update the cache the worker reads.
+- Compounding it, the **TRUE-75199** real-time comment-sync optimization suppressed
+  `repair_orders.dtUpdated`, so the order also failed the worker's `dtUpdated >= dtSynced`
+  selection — the hold never even entered the outbound cron.
+- **Fix (scoped to `clientid == 16`):** (a) suppress `dtUpdated` only for a **pure comment**
+  (`newstatus == oldStatus`); keep it bumped when the status changed, so the worker selects
+  the order — the worker's work-note query filters `referenceId IS NULL`, so a
+  real-time-reconciled comment is not re-sent; (b) after a **status-changing** note, call
+  `App_Model_TogaDesk_RepairOrder::updateStatus()` to reconcile `repair_orders.status` from
+  the latest note. This reconcile depends on the library TRUE-80060 `qqStatus()` fix — see
+  deploy ordering below.
+
+## Coordinated three-repo fix & deploy ordering (TRUE-79922 / TRUE-80060)
+Making DOE holds persist took a change in **three repos**, with a **deploy-order dependency**:
+- **worker — TRUE-79922:** stop the SNOW `state` 3⇄2 oscillation (outbound self-clobber +
+  inbound wrong-field read). *(failure path #1 above)*
+- **library — TRUE-80060:** `qqStatus()` recognizes all six `HOLD_*` on recompute so
+  `updateStatus()` can't demote a hold. *(failure path #2 above)*
+- **togadesk — TRUE-80060:** `addNotes` reconciles the cache + keeps `dtUpdated` so a
+  note-set hold reaches the worker. *(failure path #3 above)*
+
+> **DEPLOY ORDER: `library` must ship WITH or BEFORE `togadesk`.** The togadesk `addNotes`
+> change calls `updateStatus()`, which relies on the library `qqStatus()` fix. Ship togadesk
+> first and `updateStatus()` recomputes a base hold **out of** hold — reintroducing failure
+> path #2 on every note-set hold.
+
+The SNOW round-trip note reconciliation (delete-and-reinsert in `process_tickets`) is
+**intentionally kept** as a failover for SNOW API unreliability — not removed by this work.
+
 ## Reference facts (DOE sync debugging)
 
 - **SNOW request/response logs:** logged to the legacy `Logs` schema, **`API` table**
@@ -146,21 +190,42 @@ revert. It is the status-sync companion to the broader
 - **Diagnosing which writer dropped a hold:** `repair_order_history`
   (`repairid, userid, dtStamp, note`) records *user-driven* status changes. A hold reverting
   with **no** history row between the hold and the revert = a raw-`UPDATE` writer
-  (`updateStatus`/`qqStatus`), **not** the note/reply path (`class.repair.php::addNotes` syncs
-  replies to SNOW but never writes `repair_orders.status`) and **not** the worker inbound cron
-  (`process_tickets.php` contains no reference to `ORDER_ASSIGNED_AWAITING_SCHEDULING`). This
-  is how TRUE-80060 was pinned to `qqStatus()` rather than the SNOW round-trip.
+  (`updateStatus`/`qqStatus`), **not** the worker inbound cron (`process_tickets.php` contains
+  no reference to `ORDER_ASSIGNED_AWAITING_SCHEDULING`). Note that **since TRUE-80060** a
+  *status-changing* `class.repair.php::addNotes` now **calls** `updateStatus()` (so it too can
+  move the cache via that raw `UPDATE`); a **pure comment** still writes nothing to
+  `repair_orders.status`. This history-gap technique is how TRUE-80060 was pinned to
+  `qqStatus()` rather than the SNOW round-trip.
 - **KNOWN REMAINING GAP (needs a follow-up ticket):** both `qqStatus()` hold gates live inside
   the `type IN (ONSITE_REPAIR, ONSITE_SERVICE)` branch. The `DEPOT_REPAIR` branch
   (`repairorder.php` from ~L799) has **no hold gate at all**, so a `DEPOT_REPAIR` order set to
   any hold status is still silently recomputed out of hold by `updateStatus()` — the same
   class of bug, untouched by TRUE-80060.
+- **KNOWN REMAINING GAP (needs a follow-up ticket) — inbound note reconciliation is paged too
+  small.** `process_tickets.php`'s inbound comment reconciliation fetches only `page_size=50,
+  page_number=1` of the SNOW journal, then **deletes any local note not in that set** (the
+  remainder-delete ~L1326–1330). An order with **>50** comments/work_notes can have local
+  notes silently deleted. It is also inconsistent with `addNotes`, which fetches
+  `page_size=100`.
+- **KNOWN REMAINING GAP — `buildDoubleFieldArray` collapses unsynced notes.** In
+  `process_tickets`, `buildDoubleFieldArray` keys on `IFNULL(referenceId,0)`, so **all**
+  NULL-`referenceId` notes collapse to key `'0'`, making the remainder-delete handle multiple
+  unsynced notes inconsistently.
 - `qqStatus()` collapses all recognized hold sub-statuses to base `HOLD` in
   `repair_orders.status`; the specific hold **sub-reason persists only in
   `repair_order_notes.newstatus`**. Any status badge / report / filter reading
   `repair_orders.status` directly cannot distinguish the six hold variants after a recompute.
 
 ## Change history
+- 2026-07-07 — TRUE-80060 (togadesk portion): closed the **third** DOE hold-failure path — a
+  hold set via a note/comment (`Repair::addNotes`) never reaching SNOW. `addNotes` recorded
+  status only on `repair_order_notes.newstatus` (never the `repair_orders.status` cache the
+  worker reads), and the TRUE-75199 optimization suppressed `dtUpdated`, so the worker's
+  `dtUpdated >= dtSynced` selection skipped it. Fix (clientid 16): suppress `dtUpdated` only
+  for a pure comment; call `updateStatus()` after a status-changing note. Documented the
+  coordinated three-repo fix + `library`-before-`togadesk` deploy order, and two new
+  `process_tickets` reconciliation gaps (page_size=50 remainder-delete; `IFNULL(referenceId,0)`
+  collapse). php -l clean; php-reviewer 0 blocking. (mhammontree)
 - 2026-07-07 — TRUE-80060: closed the **second** DOE hold-revert path — the local
   `qqStatus()` recompute (in the shared model `library/app/model/togadesk/repairorder.php`)
   silently demoting held orders to `ORDER_ASSIGNED_AWAITING_SCHEDULING` whenever

package/knowledge/clients/nycdoe/profile.md

@@ -4,11 +4,12 @@ framework: "1.0"
 apps:
   - worker
   - library
+  - togadesk
 project: Worker
 client: nycdoe
 type: profile
 status: active
-updated: 2026-06-10
+updated: 2026-07-07
 owners: [mhammontree]
 files: []
 related:

package/package.json

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