toga-ai 1.0.347 → 1.0.348

package/knowledge/2.0/apps/api2/features/tickets-api.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
-owners: ["mhammontree"]
+updated: 2026-07-15
+owners: ["mhammontree", "ajean"]
 files:
   - Component/Api/V2/V2.php
 related:
@@ -53,6 +53,18 @@ with ticket fields at the top level.
 A minimal create needs only `shortDescription`/`longDescription` (+ optional `impact`, `ticketNotes`);
 the FK references are all nullable.
 
+## Reuse in TOGa Desk 2.0
+
+The **TOGa Desk 2.0** build (the 2.0 rebuild of the 1.0 `togadesk` product) **reuses and
+enhances this existing `tickets` Record (`_Model_Client_Ticket`) rather than rebuilding it** —
+including its child arrays (`ticketNotes[]`, `ticketFiles[]`, `ticketUnits[]`, `ticketItems[]`,
+`ticketUsers[]`, `ticketServiceQuestionAnswers[]`). The ticket stays the **atomic unit of work**.
+The three higher-order Desk entities — **Service Request**, **Case**, and **Scope** — are
+**net-new Records** modeled on this same nested child-array pattern (natural-identifier MATCH
+references + inline-created children). Entity hierarchy is **Case → Service Request → Ticket**.
+Before building new SLA behavior, verify/extend whatever this API already supports rather than
+rebuilding it.
+
 ## GET / filtering
 
 `GET /v2/tickets` supports `fields`, `where`, `join`/`ojoin`, `sort`, `group`, pagination
@@ -69,4 +81,5 @@ ticket's own contact: `join=Contacts@Contacts:Contacts.id=Tickets.contactId&wher
 
 ## Change history
 
+- 2026-07-15 — Noted TOGa Desk 2.0 reuses/enhances this `tickets` Record (not a rebuild); Service Request / Case / Scope are net-new Records on the same child-array pattern (Case → SR → Ticket). Planning-only decision. (ajean)
 - 2026-06-23 — Initial capture from the Fordham ticket integration + customer docs (TRUE-79699). (mhammontree)

package/knowledge/2.0/apps/worker2/features/clickup-design-sprint-automation.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-07
+updated: 2026-07-15
 owners: ["ajean"]
 files:
   - worker2/Worker/Clickup/Design.php
@@ -24,20 +24,32 @@ replacing a set of native ClickUp automations. When a task's **Final Design Outc
 drop-down is set to an actionable value, the worker either spawns an iteration task or
 completes the task, and a daily cron reminds the Design Approver of pending reviews.
 
-**Current state (as of 2026-07-07):** the silent no-op fix is **shipped and live** —
-worker2 PR #98 was merged to `_production` (commit `7a36564`); the type-tolerant resolver
-and the ClickBot email guard are now in production. On top of that, the review workflow was
-extended: entering the **"iterated"** status now auto-drives the review state and iteration
-count, `handleFinalDesignOutcome` now handles **all five** FDO options explicitly, and the
-spawned duplicate carries over more fields. This new work is on branch
-`feature/design-sprint-iterated-automation` in **both** worker2 and _underscore (committed +
-pushed; PRs to be opened manually — must deploy together, see Data model). The native ClickUp
-automations that were masking the no-op must stay disabled — see Gotchas.
+**Current state (as of 2026-07-15):** the silent no-op fix (worker2 PR #98, commit `7a36564`)
+and the extended iterated-automation review workflow are shipped and live. On top of that, an
+intermittent "setting FDO to *Iterated – New Task* does NOT spawn" failure was fixed end-to-end
+on **worker2 PR #113 + _underscore PR #669** (deploy together — see Data model). Two root causes
+were fixed: (1) the spawn gate ignored design tasks living in a **Backlog Design list** (only the
+True Design Sprints folder / hardcoded list IDs were admitted), and (2) `handleFinalDesignOutcome`
+resolved the FDO from a stale per-process `getTaskDetails` snapshot taken before ClickUp reflected
+the drop-down write (read-after-write race) — now the webhook's authoritative `after` value is
+threaded in. Also hardened the shared `_Component_Api_Clickup::send()` reliability path and added
+observability breadcrumbs. 55 test assertions pass; `php -l` clean. The native ClickUp automations
+that were masking the original no-op must stay disabled — see Gotchas.
 
 ## Key files / entry points
 - `Worker/Clickup/Design.php` → `_Worker_Clickup_Design` — the design-sprint engine.
-  - `handleFinalDesignOutcome(...)` — the entry that decides spawn vs. complete; now branches
-    on **all five** FDO options explicitly (no silent fall-through — see How it works).
+  - `handleFinalDesignOutcome(string $taskId, ?string $webhookFdoValue = null)` — the entry that
+    decides spawn vs. complete; branches on **all five** FDO options explicitly (no silent
+    fall-through — see How it works). The optional `$webhookFdoValue` is the authoritative new value
+    from the webhook, preferred over the (possibly stale) snapshot — see Gotchas (read-after-write).
+  - `isDesignSprintTask(...)` — the spawn/handler gate. Admits: the True Design Sprints folder,
+    **OR** (the Backlog folder `BACKLOG_FOLDER_ID` AND the list name matches `DESIGN_LIST_NAME_PATTERN`),
+    **OR** the `DESIGN_LIST_IDS` allowlist (fallback). Fixes the "backlog Design list silently skipped"
+    root cause — see Gotchas.
+  - `resolveFinalDesignOutcomeOptionId(object $taskDetails, ?string $overrideValue = null)` — maps the
+    drop-down value to an option ID; **string-compares** value/orderindex/id (see Gotchas). When
+    `$overrideValue` is given (the webhook `after` value) it wins over the snapshot's field value; the
+    option *list* is still read from the snapshot.
   - `handleTaskEnteredIterated()` — **new**; fired when a task ENTERS "iterated" status. Sets
     FDO = "In Review" then increments the Iteration custom field by +1 (idempotent — see
     Gotchas). Folder-gated via `isInDesignSprintsFolder()`.
@@ -50,8 +62,17 @@ automations that were masking the no-op must stay disabled — see Gotchas.
     and now all user comments; the duplicate no longer bumps Iteration (moved to the
     iterated-entry trigger) and is set to FDO = "In Progress" post-create.
   - `completeTask(...)` — closes an approved / cancelled task (also used on iterated → complete).
-  - `SendReviewReminders(...)` — daily reminder cron action.
-  - `TRUE_DESIGN_SPRINTS_FOLDER_ID` constant (Design.php:27,50).
+  - `SendReviewReminders(...)` — daily reminder cron action; now also fetches the Backlog folder's
+    lists and includes those matching `DESIGN_LIST_NAME_PATTERN`, mirroring `isDesignSprintTask()` so
+    newly-created backlog Design lists get reminders without a code change.
+  - `findExistingSpawnedIteration(...)` — its previously-silent `catch` now logs.
+  - `TRUE_DESIGN_SPRINTS_FOLDER_ID`, `BACKLOG_FOLDER_ID` (`'90116192732'`), and
+    `DESIGN_LIST_NAME_PATTERN` (`/(?<!non-)\bdesign\b/i`) constants.
+- `Worker/Clickup.php` `_Worker_Clickup::extractCustomFieldAfterValue(object $historyItem): ?string`
+  (**new**) — normalizes a webhook `history_items[].after` custom-field value (scalar orderindex /
+  object / JSON array with `id`|`orderindex`). Distinguishes a **missing** `after` (returns `null` →
+  caller falls back to the snapshot) from an **explicit null** `after` (returns `''` sentinel → field
+  was cleared → resolve to no outcome, do NOT act on the stale previous option).
 - `Worker/Clickup.php` `Webhook` — the `switch ($historyItem->after->status)` block (see
   Gotchas re: after vs. before) now has a `case _Worker_Clickup_Design::STATUS_ITERATED`
   dispatching to `handleTaskEnteredIterated()`.
@@ -102,6 +123,14 @@ present (worker2 PR #80, _underscore PR #624).
 throws undefined-constant. Both changes are on branch
 `feature/design-sprint-iterated-automation`.
 
+**Backlog Design lists (2026-07-15):** design tasks also live under the **Backlog folder**
+`BACKLOG_FOLDER_ID = '90116192732'` in lists whose name matches `DESIGN_LIST_NAME_PATTERN`
+(`/(?<!non-)\bdesign\b/i`). No DB/config change — these are ClickUp identifiers on
+`_Worker_Clickup_Design`. **PR #113 (worker2) + #669 (_underscore) deploy together** as the two
+halves of one fix; note the send() reliability change introduced **no** new shared symbol
+(the earlier `_Exception_Api_Transient` idea was dropped — see Gotchas), so this pairing is
+operational, not a hard undefined-symbol coupling like the FDO constants above.
+
 ## Client variations
 None — internal TOGA Technology (`true`) design-sprint tooling.
 
@@ -158,11 +187,64 @@ None — internal TOGA Technology (`true`) design-sprint tooling.
   `c25fd345`, `272f743e`, `a64c863a`, `7739cc41`, `08570f31`, `70b09962`. Keep sprint-readiness
   automations only: `10df1786`, `f6214678`. Re-enabling any of the replaced set reintroduces the
   duplicate+close and spurious-email behavior.
+- **The spawn gate must admit Backlog Design lists — folder + name, not just the sprint folder
+  (ROOT CAUSE of the 2026-07-15 intermittent no-spawn).** `isDesignSprintTask()` originally accepted
+  only the True Design Sprints folder or two hardcoded `DESIGN_LIST_IDS`, so a design task living in a
+  **Backlog Design list** was silently skipped (no iteration spawned). The gate now also admits
+  `BACKLOG_FOLDER_ID = '90116192732'` when the list name matches `DESIGN_LIST_NAME_PATTERN`. **Regex
+  trap:** the pattern is `/(?<!non-)\bdesign\b/i` — a bare `\bdesign\b` wrongly matched **"Non-Design
+  Overflow"** because the hyphen is itself a word boundary, so the negative-lookbehind `(?<!non-)` is
+  required; the `\b` boundary also correctly excludes **"Redesign"**. `SendReviewReminders()` applies
+  the same folder+pattern so new backlog Design lists get reminders without a code change.
+- **Resolve the FDO from the webhook `after` value, NOT the per-process snapshot (read-after-write
+  race — second root cause of the 2026-07-15 failure).** `handleFinalDesignOutcome` used to resolve
+  the outcome from the cached `getTaskDetails` snapshot fetched early in the request, which can
+  **predate** ClickUp reflecting the drop-down write → it read the OLD value → silent skip. The
+  webhook's authoritative new value (`history_items[].after`) is now threaded through
+  `handleFinalDesignOutcome(..., ?string $webhookFdoValue)` →
+  `resolveFinalDesignOutcomeOptionId(..., ?string $overrideValue)` (override wins over the snapshot
+  value; the option *list* is still read from the snapshot). `_Worker_Clickup::extractCustomFieldAfterValue()`
+  normalizes the `after` shape and — critically — distinguishes a **missing** `after` (→ `null` → fall
+  back to snapshot) from an **explicit null** `after` (→ `''` sentinel → field was cleared → resolve to
+  no outcome; do NOT act on the stale previous option). The previously-silent resolver-null return now
+  logs a `[ClickupDesign]` breadcrumb.
+- **`_Component_Api_Clickup::send()` throws on transient failures — it no longer silently returns
+  NULL (shared-core, `_underscore` PR #669).** The old retry loop never actually retried and returned
+  NULL on HTTP `>= 502`, **silently dropping** the API call. Now transient failures — HTTP 502/503/504,
+  429, and transport-level errors (`responseCode === 0` / cURL failure) — **throw** so the worker job
+  fails loudly and the **queue** retries; other non-2xx still throw. Retry is intentionally left to the
+  queue (no in-worker sleep-and-retry; CTO Option C). **It throws the base `Exception`** — the same type
+  every other `_Component_Api` client throws and the framework error handler / Sentry already track — NOT
+  a bespoke exception class. (A `_Exception_Api_Transient` subclass was prototyped and then dropped
+  precisely because a new type sits outside the existing Sentry/error path.) Exception messages never
+  embed the full `$response` body (task/user PII); the private `summarizeApiError()` surfaces only
+  ClickUp `err`/`ECODE` with a bounded/truncated fallback. This affects **every** caller of `send()`
+  across the 2.0 apps — grep `_Component_Api_Clickup::send(` before assuming a caller tolerated the old
+  null-on-failure return.
 - **Not the bug (ruled out):** `_underscore` PR #624 field/option constants were confirmed
   present and correct — no `_underscore` change was needed. The earlier folder-gate ID-mismatch
-  suspicion was also not the cause.
+  suspicion was also not the cause. For the 2026-07-15 failure, additionally ruled out: the strict-`===`
+  resolver typing bug (already fixed & deployed on `_production`) and a cross-repo FDO-constant deploy
+  gap (all five FDO option constants confirmed present on `_underscore` `_production`).
 
 ## Change history
+- 2026-07-15 — **Fixed intermittent "Iterated – New Task does not spawn" end-to-end (worker2 PR #113
+  + _underscore PR #669, deploy together).** Root cause 1: `isDesignSprintTask()` skipped design tasks
+  in **Backlog Design lists** — gate now admits `BACKLOG_FOLDER_ID` + name matching
+  `DESIGN_LIST_NAME_PATTERN` (`/(?<!non-)\bdesign\b/i`; word-boundary lookbehind excludes "Non-Design"
+  and "Redesign"); `SendReviewReminders` mirrors it. Root cause 2 (read-after-write race): FDO was
+  resolved from a stale per-process `getTaskDetails` snapshot — now the webhook `history_items[].after`
+  value is threaded via `handleFinalDesignOutcome(..., $webhookFdoValue)` /
+  `resolveFinalDesignOutcomeOptionId(..., $overrideValue)` and a new
+  `_Worker_Clickup::extractCustomFieldAfterValue()` (missing `after` → snapshot fallback; explicit-null
+  → cleared-field no-op, not stale-value action). Added `[ClickupDesign]` breadcrumbs and logging to the
+  previously-silent resolver-null and `findExistingSpawnedIteration` catch. Shared-core: hardened
+  `_Component_Api_Clickup::send()` so transient failures (502/503/504, 429, transport `responseCode 0`)
+  **throw** instead of silently returning NULL; retry left to the queue; PII-safe `summarizeApiError()`.
+  **The transient path reuses the base `Exception`** (Sentry/error-path parity) — an initially-prototyped
+  `_Exception_Api_Transient` class was dropped and removed. 55 assertions pass (Cases 6–8 added to
+  `ClickupDesignTest`); `php -l` clean. Two PHP reviews + a CTO second opinion; ruled out the (already
+  fixed) strict-`===` bug and an FDO-constant deploy gap. (ajean)
 - 2026-07-07 (later) — **Extended the review workflow (branch
   `feature/design-sprint-iterated-automation`, worker2 + _underscore; PRs pending manual open).**
   Added the iterated-entry trigger `handleTaskEnteredIterated()` (FDO → In Review, then

package/package.json

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