toga-ai 1.0.281 → 1.0.282

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/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.281",
+  "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",