toga-ai 1.0.398 → 1.0.399

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

@@ -6,8 +6,8 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-07-07
-owners: [mhammontree]
+updated: 2026-07-20
+owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/send_ticket_updates.php
   - worker/crons/sync/nycdoe/process_tickets.php
@@ -76,29 +76,55 @@ revert or never reach ServiceNow. It is the status-sync companion to the broader
 - `Hold` has **statusRank 6**, beating `Work in Progress` (rank 5) in the downgrade-guard
   added by TRUE-76812 — so a downstream sync cannot silently demote a held order.
 
-### Status field (ServiceNow side)
-- The SNOW **native `state` field** (human-readable: `On Hold`, `In Progress`, `Assigned`,
-  `Resolved`, …) is the **SLA-bearing, authoritative status**. Read/write this for hold.
-- The custom **`u_status_task`** field is a *separate concept* with a different vocabulary;
-  it can lag/disagree with `state` (observed: native `state="In Progress"` while
-  `u_status_task="Open"`). **Never use `u_status_task` for hold detection.**
-- Numeric `state` codes seen on the wire: INC `On Hold` = **3**, `In Progress` = **2**;
-  RITM `On Hold` = **8**, the scheduled-update state = **"-14"**.
-
-### Outbound (TOGaDesk → ServiceNow)
-- `send_ticket_updates.php` (INC) pushes the hold as `state:3`. The "Assigned → In Progress"
-  auto-start block is **guarded** so it never pushes `state:2` when the local repair order is
-  in any `HOLD_*` status (this is what caused the self-clobber — see Change history).
-- `send_request_item_updates.php` (RITM) pushes `state:"8"` (On Hold) and carries a
-  defensive `HOLD_*` guard on the scheduled-update path so it can't push `state:"-14"` while
-  held.
+### Status fields (ServiceNow side) — CORRECTED 2026-07-20
+> **The earlier "native `state` is authoritative; never use `u_status_task`" model was WRONG**
+> (see Change history 2026-07-20). Both fields exist and both matter, with distinct roles:
+- **`u_status_task` (custom) is the CLIENT-FACING, authoritative incident status** — the field
+  DOE's own ServiceNow views/reporting read (values `Open`, `In Progress`, `On Hold`, …). **A hold
+  MUST be written here or the client never sees it.** It is **writable from any active state**; a
+  controlled test PATCH of `{u_status_task:'On Hold'}` returned success and PERSISTED for days
+  (INC2192842 held 3+ days). **The TOGaDesk inbound sync keys off `u_status_task`**
+  (`process_tickets.php:206` reads `$data->u_status_task`), and the RITM cron checks
+  `u_status_task == 'On Hold'` (`send_request_item_updates.php:224`) — so `u_status_task` **is**
+  the correct field for hold detection.
+- The native **`state`** field is ServiceNow's INTERNAL, SLA-bearing state machine. Setting
+  `state=3` (On Hold) pauses the SNOW SLA clock but is **invisible to the DOE client**. ServiceNow
+  only permits the native On Hold transition **FROM In Progress (`state=2`)** — pushing `state=3`
+  from any other state (Assigned, or already Resolved/Closed/Canceled) is silently rejected (HTTP
+  200, empty body — see the empty-body gotcha). `hold_reason=10` is not a valid choice on this
+  instance and is stored empty/dropped, but native On Hold still sticks without it.
+- Numeric `state` codes seen on the wire: INC `On Hold`=**3**, `In Progress`=**2**;
+  RITM `On Hold`=**8**, the scheduled-update state=**"-14"**.
+
+### Outbound (TOGaDesk → ServiceNow) — INC hold push (worker #1676 + #1677)
+When a DOE repair order is on hold, `send_ticket_updates.php` pushes:
+- **Always set `u_status_task='On Hold'`** — the client-facing field, writable from any active
+  state; on release set it back to `'In Progress'`. This is what actually surfaces the hold to the
+  client. Until the local status stops reverting (the library `qqStatus()` fix below) the outbound
+  never sees `orderIsOnHold=true` and never pushes `u_status_task` at all — hence the deploy
+  dependency.
+- **Set native `state=3` (On Hold) only when the incident is currently `In Progress`** — an SLA
+  pause. Because ServiceNow rejects the transition from any other state (empty-body 200), the cron
+  **defers without advancing `dtSynced`** when the incident is neither On Hold nor In Progress, and
+  re-pushes only once it reaches In Progress.
+- **Closed-incident reconcile:** if the incident is already `Resolved`/`Closed`/`Canceled` on the
+  SNOW side it can no longer be held — the cron **advances `dtSynced`** to accept the remote
+  closure instead of retrying forever. (A canceled incident, INC2190846, had generated **2,392**
+  failed empty-body PATCHes before this.)
+- The "Assigned → In Progress" auto-start block is still guarded so it never pushes `state:2` over
+  a held order (TRUE-79922). Named constants: `SN_STATE_IN_PROGRESS` / `SN_STATE_ON_HOLD` /
+  `SN_HOLD_REASON_DEFAULT` in `send_ticket_updates.php`, plus `SN_TASK_STATUS_ON_HOLD` /
+  `SN_TASK_STATUS_IN_PROGRESS` for the `u_status_task` writes (#1677).
+- `send_request_item_updates.php` (RITM) pushes `state:"8"` (On Hold) and carries a defensive
+  `HOLD_*` guard on the scheduled-update path so it can't push `state:"-14"` while held; its
+  reverse-hold logic keys off `u_status_task == 'On Hold'`.
 
 ### Inbound (ServiceNow → TOGaDesk)
-- `process_tickets.php` determines local status from the native **`$data->state`** field
-  (NOT `u_status_task`): after the `u_status_task` switch — before the completion-preserve
-  step and the `statusRank` downgrade-guard — if native `state` is `On Hold`
-  (case-insensitive) it sets `$newStatus = STATUS_HOLD`. Both inbound "Assigned-force"
-  `patchINC(state:2)` blocks are guarded against a local hold.
+- `process_tickets.php` reads the client-facing **`u_status_task`** field
+  (`$status = $data->u_status_task`, L206) — **NOT** native `state` — and maps `On Hold` to the
+  bare **`STATUS_HOLD`** on the local repair order (this is exactly why the library `qqStatus()`
+  fix below had to recognize bare `HOLD`). Both inbound "Assigned-force" `patchINC(state:2)` blocks
+  are guarded against a local hold.
 
 ### RITM "ETA-in-hold"
 - `send_request_item_updates.php` syncs `scheduled_date` (ETA) to ServiceNow **inside the
@@ -182,9 +208,19 @@ The SNOW round-trip note reconciliation (delete-and-reinsert in `process_tickets
   auto-start fought the hold push — `state:3` then `state:2` pushed seconds apart, every run,
   so SNOW never stayed On Hold. Any future auto-start/auto-status block on these crons MUST
   short-circuit when the local RO is in a `HOLD_*` status.
-- **The wrong-field read (root cause #2 of TRUE-79922):** reading `u_status_task` instead of
-  native `state` meant a hold set on the SNOW side never reached TOGaDesk. Hold detection is
-  on native `state` only.
+- **⚠ SUPERSEDED (see Change history 2026-07-20):** TRUE-79922 originally concluded that reading
+  `u_status_task` (instead of native `state`) was a bug and that hold detection should be on native
+  `state` only. That was **backwards.** `u_status_task` is the client-facing authoritative field
+  and **is** the correct hold-detection field — the live inbound cron reads it at
+  `process_tickets.php:206`. Native `state` is the internal SLA state, pushed only as a secondary
+  pause when the incident is In Progress.
+- **The empty-body 200 (nycd3 `data/tasks` PATCH):** `App_Api_NYCDOEV2::patchINC`/`patchRITM`
+  (both hit `/api/nycd3/data/tasks/{number}`) return **HTTP 200 with an EMPTY body (no `result`
+  object)** when a requested native `state` transition is illegal — e.g. pushing `state=3` from a
+  non-In-Progress state. This is silent: no exception, no error field. A canceled incident
+  (INC2190846) generated **2,392** such failed PATCHes before the closed-incident reconcile was
+  added. Gate native `state=3` on `snState == 'In Progress'`, and reconcile
+  Resolved/Closed/Canceled by advancing `dtSynced`.
 - 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`
@@ -217,6 +253,25 @@ The SNOW round-trip note reconciliation (delete-and-reinsert in `process_tickets
   `repair_orders.status` directly cannot distinguish the six hold variants after a recompute.
 
 ## Change history
+- 2026-07-20 — **Corrected the authoritative-field model and shipped the INC hold push.**
+  Controlled test PATCHes proved the earlier "native `state` is authoritative; never use
+  `u_status_task`" conclusion (TRUE-79922) **backwards**: the custom **`u_status_task`** is the
+  client-facing authoritative incident status (a `{u_status_task:'On Hold'}` PATCH persisted 3+
+  days, INC2192842), the inbound cron reads it (`process_tickets.php:206`), and the RITM cron keys
+  off it (L224). Native `state` is the internal SLA state and only accepts On Hold **from In
+  Progress** — any other transition returns a silent HTTP-200 empty body (a canceled incident,
+  INC2190846, had racked up 2,392 failed PATCHes). Fix: outbound `send_ticket_updates.php` now
+  always writes `u_status_task='On Hold'` (client-facing; `'In Progress'` on release), sets native
+  `state=3` only when In Progress (SLA pause), and reconciles already-closed incidents by advancing
+  `dtSynced` instead of retrying forever; added `SN_STATE_*` / `SN_HOLD_REASON_DEFAULT` /
+  `SN_TASK_STATUS_*` constants. worker PRs **#1676** (merged — retry-storm/closed reconcile + native
+  state gate) and **#1677** (open — `u_status_task` write). (sking)
+- 2026-07-20 — library **#845**: `App_Model_TogaDesk_RepairOrder::qqStatus()` now recognizes all
+  six `HOLD_*` constants in both "on hold" IN-clauses. The inbound sync writes SNOW On Hold as the
+  bare `STATUS_HOLD` ('HOLD'), which the prior 2-of-6 match dropped, silently recomputing the order
+  to `ORDER_ASSIGNED_AWAITING_SCHEDULING` (the local "hold revert"). Additive only. Must ship with/
+  before worker #1677 — until the local status stops reverting, the outbound never sees
+  `orderIsOnHold=true`. (sking)
 - 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

package/package.json

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