toga-ai 1.0.279 → 1.0.280

package/knowledge/1.0/apps/togadesk/INDEX.md

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [TOGa Desk Architecture](architecture.md) | TOGa Desk is the staff-facing support desk **and field-service platform** (analysts work at `/desk/`). | desk/index.php, desk/includes/loader.php, desk/config.php, desk/includes/controllers/actions.php, desk/includes/controllers/data.php, desk/includes/controllers/modals.php, desk/includes/classes/class.app.php, desk/includes/classes/class.ticket.php, desk/api/index.php, desk/api/resources/tickets.php, crons/tickets.php |
 | [Email-to-Ticket Intake (crons/tickets.php)](features/email-to-ticket-intake.md) | TOGa Desk ingests support email into tickets through a cron-driven IMAP poller (`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). | crons/tickets.php, crons/tickets_prod.php, crons/pipe.php, desk/includes/classes/class.ticket.php |
-| [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
+| [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairorder.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
 | [Ticket Email Notifications (notifications table)](features/notifications.md) | Which TOGa Desk emails fire for a given client is driven **entirely by data**, not code: the `TOGaDeskSupport.notifications` table holds one row per `(clientid, | desk/includes/classes/class.notification.php, crons/tickets.php, crons/tickets_prod.php |
 | [REST API (RPC-over-POST) & API-Key Auth](features/rest-api.md) | TOGa Desk exposes a programmatic API at `desk/api/`. | desk/api/index.php, desk/api/resources/tickets.php, desk/api/resources/assets.php, desk/api/resources/authenticate.php, desk/includes/classes/class.apikey.php, desk/includes/functions.php |
 | [SMB Contract Editing & the clientMspId Corruption Trap](features/smb-contract-editing.md) | The SMB contracts page (`/desk/?route=toga/smbcontracts&togaClientId=<id>`) edits `TOGA_*.SMBContracts` rows via a modal. | desk/template/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/edit.php |

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

@@ -6,7 +6,7 @@ project: TOGa Desk
 client: shared
 type: feature
 status: active
-updated: 2026-06-15
+updated: 2026-07-07
 owners: ["jcardinal", "mhammontree"]
 files:
   - desk/includes/controllers/actions/central/
@@ -16,6 +16,7 @@ files:
   - desk/template/pages/central.php
   - desk/template/pages/central/view.php
   - desk/template/modals/central/addTracking.php
+  - library/app/model/togadesk/repairorder.php
   - library/app/model/togadesk/repairordertracking.php
   - library/app/api/carrier/ups.php
 related:
@@ -90,6 +91,26 @@ always confirm the client arm before changing shared central logic.
   `controllers/actions/central/*.php` (the default fallback). Check both when tracing an action.
 - Status recomputation is centralized in `updateStatus()` — write paths that bypass it can leave
   an order in an inconsistent state.
+- **`updateStatus()` / `qqStatus()` silently overwrite status via a raw `UPDATE`** (no
+  `repair_order_history` / `repair_order_notes` row). `qqStatus()`
+  (`library/app/model/togadesk/repairorder.php` ~L356) is a computed SQL `CASE` that
+  recomputes `repair_orders.status` from technician / dispatch / ETA / parts data on every
+  `updateStatus()` call (fired by `scheduleDispatch`, `technicianOnsite`, `technicianEnRoute`,
+  `awaitingDispatch`, `reworkAwaitingScheduling`, and part flows). If a status is not
+  explicitly gated inside `qqStatus()`, it will be recomputed away with no audit trail — this
+  is **shared, client-agnostic** logic (no tenant conditional), so a change hits every
+  repair-order client.
+- **Hold states must be gated in `qqStatus()` or they are dropped.** There are six `HOLD_*`
+  constants; `qqStatus()` has hold gates that collapse recognized holds to base `STATUS_HOLD`.
+  TRUE-80060 fixed both `ONSITE_REPAIR`/`ONSITE_SERVICE`-branch gates (~L389, ~L429) recognizing
+  only 2 of the 6. **KNOWN REMAINING GAP:** the `DEPOT_REPAIR` branch (~L799) has **no hold gate
+  at all**, so a depot order set to any hold is still silently recomputed out of hold — a
+  follow-up ticket is needed. (DOE surfacing + full detail:
+  [NYCDOE Hold-Status Sync](../../../../clients/nycdoe/features/hold-status-sync.md).)
+- **The hold sub-reason is lost from `repair_orders.status` after a recompute.** `qqStatus()`
+  collapses all six hold variants to base `HOLD`; the specific sub-reason persists only in
+  `repair_order_notes.newstatus`. Badges/reports/filters reading `repair_orders.status`
+  directly cannot distinguish the variants.
 - Cross-database context: some central data controllers switch the DB link to a client database
   (`App_Model_Client::changeDbLinkToClientDatabase()`).
 - **UPS carrier-account dropdown is NOT honored by the shipment API call.** In
@@ -105,6 +126,11 @@ 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: 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
+  the untouched `DEPOT_REPAIR`-branch gap (follow-up needed). Added `repairorder.php` to files.
+  (mhammontree)
 - 2026-06-15 — documented UPS Prepare Shipment flow: CARRIER_ACCOUNTS dropdown vs hardcoded
   SHIPPER_NUMBER, and the gotcha that the dropdown selection is never forwarded to the UPS API
   (always bills Agilant). Agilant account migrated 135FV5 → 8696XA. (mhammontree)

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

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-06-29
+updated: 2026-07-07
 owners: [mhammontree]
 files:
   - worker/crons/sync/nycdoe/send_ticket_updates.php
@@ -25,9 +25,24 @@ 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 TRUE-79922 fix that made hold persist. 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.
+business rule that governs it, and the two independent defects that let holds silently
+revert. 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:
+> - **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
+>   below. (Still pending deploy at time of writing.)
+> - **TRUE-80060 (`library` shared model):** the local `qqStatus()` recompute silently
+>   demoting the order to a scheduling status (**"Orders Assigned / Awaiting Scheduling"**,
+>   `ORDER_ASSIGNED_AWAITING_SCHEDULING`) whenever `updateStatus()` ran. Fixed; see
+>   *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).
 
 > DOE "tickets" are **`repair_orders`** rows (`App_Model_TogaDesk_RepairOrder`,
 > `db_togadesk` / legacy `TOGaDeskSupport`, **clientid = 16**) — NOT the generic `tickets`
@@ -82,6 +97,26 @@ doc; the underlying crons and `App_Api_NYCDOEV2` plumbing are documented there.
   technician. This mirrors the INC cron, which already sends `u_eta` while holding — keeping
   scheduling metadata flowing while the hold STATE stays asserted.
 
+### Local status recompute (`qqStatus` / `updateStatus`) — TRUE-80060
+- `App_Model_TogaDesk_RepairOrder::qqStatus()` is a computed SQL `CASE` expression that
+  `App_Model_TogaDesk_RepairOrder::updateStatus()` writes to `repair_orders.status`. It
+  recomputes status from technician / dispatch / ETA / parts data. Both live in the shared
+  model `library/app/model/togadesk/repairorder.php` (`qqStatus` ~L356, `updateStatus` ~L181)
+  — **no tenant conditional**, so this path is not DOE-specific.
+- `updateStatus()` is called from the togadesk central actions `scheduleDispatch`,
+  `technicianOnsite`, `technicianEnRoute`, `awaitingDispatch`, `reworkAwaitingScheduling`
+  (and the part flows). Any of these recomputes `repair_orders.status` via `qqStatus()`.
+- `qqStatus()` has two "hold gates" that short-circuit the recompute when an order is held.
+  Before TRUE-80060 they recognized only **2 of the 6** `HOLD_*` constants
+  (`HOLD_AWAITING_APPROVAL`, `HOLD_OTHER`); the base `STATUS_HOLD` and the other three
+  (`HOLD_AWAITING_CUSTOMER_APPROVAL`, `HOLD_ADDITIONAL_INFO_NEEDED`,
+  `HOLD_AWAITING_CUSTOMER_CONTACT`) fell through and were silently recomputed into a
+  scheduling / WIP status. The fix (`repairorder.php` ~L389 and ~L429) expanded **both**
+  gates to all six `HOLD_*` constants, still collapsing to base `STATUS_HOLD` (matching the
+  pre-existing behavior of the two that already worked).
+- The revert is **silent** — `updateStatus()` writes via a raw `UPDATE` with **no**
+  `repair_order_history` / `repair_order_notes` entry.
+
 ## Reference facts (DOE sync debugging)
 
 - **SNOW request/response logs:** logged to the legacy `Logs` schema, **`API` table**
@@ -108,8 +143,33 @@ doc; the underlying crons and `App_Api_NYCDOEV2` plumbing are documented there.
   on native `state` only.
 - Holds are **never auto-released** — if a SNOW user manually changes status, the outbound
   cron correctly re-asserts On Hold; that is intended, not a bug. Clear the hold in TOGaDesk.
+- **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.
+- **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.
+- `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: 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
+  `updateStatus()` ran. Root cause: both `qqStatus()` hold gates recognized only 2 of the 6
+  `HOLD_*` constants; expanded both (~L389, ~L429) to all six, collapsing to base
+  `STATUS_HOLD`. Separate from TRUE-79922 (different repo/mechanism/revert target). Documented
+  the raw-`UPDATE` silent-revert, the `repair_order_history`-gap debugging technique, and the
+  untouched `DEPOT_REPAIR`-branch gap (follow-up ticket needed). php -l clean; php-reviewer 0
+  critical / 0 blocking. (mhammontree)
 - 2026-06-29 — TRUE-79922: fixed DOE holds never persisting (reverted to In Progress, broke
   SLA reporting both sides). Two coupled defects: outbound self-clobber (`send_ticket_updates.php`
   unguarded Assigned→In-Progress pushing `state:2` over a held `state:3`) and inbound

package/package.json

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