toga-ai 1.0.274 → 1.0.275

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

@@ -5,7 +5,7 @@
 | [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php |
 | [Automated PR Merger — Concurrent Force-Push Clobber Race](features/automated-pr-merger-force-push-race.md) | The automated PR merger `_Worker_Team_GitHub::Merge` (`worker2` `Worker/Team/Github.php`) merges approved PRs to `_production` by **force-pushing from a clone t | Worker/Team/Github.php |
 | [ClickUp Connectivity Watchdog](features/clickup-connectivity-watchdog.md) | A cron watchdog that emails when the ClickUp integration looks disconnected during business hours. | worker2/Worker/Clickup/Health.php, worker2/Database/ClickupHealthWatchdog.sql |
-| [ClickUp Design Sprint Automation (Final Design Outcome)](features/clickup-design-sprint-automation.md) | `_Worker_Clickup_Design` is meant to drive the design-sprint workflow in ClickUp via the API, replacing a set of native ClickUp automations. | worker2/Worker/Clickup/Design.php, worker2/Worker/Clickup.php |
+| [ClickUp Design Sprint Automation (Final Design Outcome)](features/clickup-design-sprint-automation.md) | `_Worker_Clickup_Design` is meant to drive the design-sprint workflow in ClickUp via the API, replacing a set of native ClickUp automations. | worker2/Worker/Clickup/Design.php, worker2/Worker/Clickup.php, worker2/Controller/ClickupDesignTest.php |
 | [ClickUp GitHub-tab Auto-linking & Ticket-id Branch Naming](features/clickup-github-autolink.md) | How ClickUp surfaces branches/PRs/commits in a ticket's **GitHub tab**, and the branch / PR-title naming convention that triggers it. |  |
 | [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
 | [ClickUp Rich-Text Custom Fields via Quill Delta (API)](features/clickup-richtext-api.md) | ClickUp custom text fields (type `text` and long-text) support rich formatting only through a **Quill Delta** written to the undocumented `value_richtext` key o | test/@dave/clickup_md2delta.js, .claude/skills/plan-ticket/scripts/clickup.js |

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

@@ -6,11 +6,12 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-06
+updated: 2026-07-07
 owners: ["ajean"]
 files:
   - worker2/Worker/Clickup/Design.php
   - worker2/Worker/Clickup.php
+  - worker2/Controller/ClickupDesignTest.php
 related:
   - ./clickup-work-type-automation.md
   - ./team-sprint-management.md
@@ -22,25 +23,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.
 
-**Critical current state (as of 2026-07-06):** the worker's
-`handleFinalDesignOutcome` has been **silently no-opping in production** — the native
-ClickUp automations it was supposed to replace were never disabled and had been doing the
-real work all along, masking the failure. Do not assume the API path is live. See Gotchas
-and the open action item below before touching this code.
+**Current state (as of 2026-07-07):** the silent no-op is **fixed and shipped**
+(worker2 PR #98, branch `fix/clickup-design-outcome-resolver` off `_production`). Root cause
+was a **strict `===` type mismatch** in `resolveFinalDesignOutcomeOptionId`, confirmed and
+corrected. The spurious "Design Review" email (both vectors) is also fixed. Once the worker
+is verified live, the native ClickUp automations that were masking the 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 (currently a
-    silent no-op in prod).
+  - `handleFinalDesignOutcome(...)` — the entry that decides spawn vs. complete.
   - `resolveFinalDesignOutcomeOptionId(...)` (Design.php:298-317) — maps the drop-down value
-    to an option ID.
+    to an option ID; now **string-compares** value/orderindex/id (see Gotchas).
   - `spawnIterationTask(...)` / `carryDesignApprover(...)` — duplicate the task and copy the
     Design Approver.
-  - `completeTask(...)` — closes an approved task.
+  - `completeTask(...)` — closes an approved task (iterated → complete).
   - `SendReviewReminders(...)` — daily reminder cron action.
   - `TRUE_DESIGN_SPRINTS_FOLDER_ID` constant (Design.php:27,50).
-- `Worker/Clickup.php` (dispatcher ~lines 822-875) — routes ClickUp webhooks; the Design
-  Approver / status guard lives at 822-833.
+- `Worker/Clickup.php` — routes ClickUp webhooks.
+  - `shouldEmailDesignApprover($payload, $taskDetails)` — the single predicate gating the
+    "Action Needed: Design Review" email (requires history_items[0] is a Design Approver
+    custom_field change, task status still `iterated`, and user-driven: `user.id != -1`).
+  - `taskUpdated` path (~822) and `taskStatusUpdated` path (~230) both gate the email on this
+    predicate.
+- `Controller/ClickupDesignTest.php` — regression tests reached via the
+  `?controller=ClickupDesignTest` route (worker2 has **no PHPUnit harness**; mirrors the
+  `CompassPeopleTest` convention). Uses `ReflectionMethod` to reach the private methods.
 
 ## How it works
 1. A ClickUp webhook reaches `_Worker_Clickup`; the dispatcher (Clickup.php ~822-875) routes
@@ -68,41 +76,49 @@ undefined-constant theory was ruled out.
 None — internal TOGA Technology (`true`) design-sprint tooling.
 
 ## Gotchas / known issues
-- **Silent no-op masked by native automations (root cause of TRUE-79685).** The worker's
-  docstring claims it replaced the native automations, but they were never disabled. Native
-  automation `c25fd345` ("When Final Design Outcome is Iterated, duplicate the ticket and
-  close the original") was doing the duplicate+close and **hiding** that the worker never
-  spawned. Only after disabling **all** native automations did setting Final Design Outcome →
-  "Iterated – New Task" on TRUE-80046 (prod job 295376, isSuccess=1) produce **no** spawn,
-  exposing the failure.
-- **OPEN — two prime suspects for the silent no-op** (need a combined code + live-API session
-  to confirm/fix):
-  1. **Folder-gate ID mismatch.** `TRUE_DESIGN_SPRINTS_FOLDER_ID = '90115939842'`
-     (Design.php:27,50) vs. the file-header comment naming `90020178491`. `90115939842` is a
-     valid folder (the daily reminder cron GETs `/folder/90115939842/list` successfully) but
-     may not be the folder the automation-test tasks live in — in which case the folder gate
-     returns early on every task. **Verify:** compare `getTaskDetails` `folder.id` for
-     TRUE-80046 against the constant.
-  2. **Strict `===` mismatch in `resolveFinalDesignOutcomeOptionId`** (Design.php:298-317). If
-     `getTaskDetails` returns the `drop_down` value in a shape (string `orderindex`, or an
-     option-id) that matches neither `option->id === value` nor `option->orderindex === value`,
-     it returns `null` → silent no-op. Fix should be an explicit **cast/validate at the
-     ClickUp-payload boundary**, not merely switching `===` to `==`.
-- **Latent bug — spurious "Design Review" email on freshly spawned tasks.** Spawned iteration
-  tasks transiently pass through "iterated" status during creation (a ClickUp list
-  automation), and `spawnIterationTask → carryDesignApprover` copies the Design Approver onto
-  the new task. If that copy lands while the new task is momentarily "iterated", the dispatcher
-  guard (Clickup.php:822-833: `custom_field.name == 'Design Approver' && status == 'iterated'`)
-  fires a **spurious** "Action Needed: Design Review" email. Candidate fix: gate
-  `sendDesignApproverEmail` on the change being user-driven (history `user.id != ClickBot -1`).
-- **Native automations must be disabled once the worker is fixed.** The worker was meant to
-  replace: `c25fd345`, `272f743e` (Automation #39, native "email Aaron when iterated"),
-  `a64c863a`, `7739cc41`, `08570f31`, `70b09962`. Keep sprint-readiness automations only:
-  `10df1786`, `f6214678`. **INTERIM:** if the design team needs the workflow before the worker
-  is fixed, re-enable **only** `c25fd345` (temporary — this reintroduces the Iteration-reset
-  and spurious-email issues).
+- **Never use strict `===` when reading a ClickUp `drop_down` value/orderindex/id (ROOT CAUSE
+  of the silent no-op).** ClickUp returns `value`/`orderindex` with **inconsistent int-vs-string
+  typing** (`"2" !== 2`), so `resolveFinalDesignOutcomeOptionId` matched nothing, returned
+  `null`, and `handleFinalDesignOutcome` hit its early return (job still `isSuccess=1`). Fixed
+  by comparing **as strings**: `(string)$option->orderindex === (string)$field->value` (and the
+  same for `$option->id`). Note that **every other** drop_down reader in `Worker/Clickup.php`
+  relies on PHP **array-key coercion** (`$optionsByIndex[$option->orderindex]` then indexed by
+  `$customField->value`) precisely because of this typing inconsistency — strict `===` anywhere
+  reading a ClickUp drop_down value is a bug. The native automation `c25fd345` had been masking
+  this no-op in prod.
+- **`taskStatusUpdated` switches on `before->status`, NOT `after->status`** (Clickup.php ~71).
+  A `case '<status>'` in that switch therefore fires when a task **LEAVES** that status — the
+  in-code comment claiming "just changed TO iterated" is misleading. This is the trap behind the
+  second spurious-email vector: the `iterated` case fired on `completeTask()`'s
+  `iterated → complete` transition during `spawnIterationTask`. Anyone adding status-transition
+  logic must account for this direction. A correctly-placed "entering iterated" trigger would go
+  under `switch(after->status)` and is **not** currently wired.
+- **Spurious "Design Review" email — fixed on a single predicate.** Both vectors (the
+  `taskUpdated` Design-Approver-field path ~822 and the `taskStatusUpdated` `iterated` path
+  ~230) now gate on `shouldEmailDesignApprover($payload, $taskDetails)`, which requires:
+  `history_items[0]` is a Design Approver custom_field change, task status still `iterated`, and
+  the change is **user-driven** (`user.id != -1`; ClickBot/automation writes carry
+  `user.id == -1`). The dead `$isDesignApproverSet` block was removed. Consequence: a pure status
+  change **into** iterated (approver already set, no field change) no longer emails from the
+  status path — the legitimate review email flows from the `taskUpdated` field handler.
+- **Native automations must stay disabled once the worker is verified.** The worker replaces:
+  `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.
+- **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.
 
 ## Change history
+- 2026-07-07 — Fixed and shipped the silent no-op (worker2 PR #98, branch
+  `fix/clickup-design-outcome-resolver`). Confirmed root cause: strict `===` on ClickUp
+  `drop_down` value/orderindex/id in `resolveFinalDesignOutcomeOptionId` (inconsistent int/string
+  typing) — now string-compared. Fixed the spurious "Design Review" email (both the `taskUpdated`
+  and `taskStatusUpdated` vectors) behind a single `shouldEmailDesignApprover` predicate that
+  requires a user-driven Design-Approver field change on an `iterated` task. Documented that
+  `taskStatusUpdated` switches on `before->status` (fires on LEAVING a status). Added regression
+  tests in `Controller/ClickupDesignTest.php` (run via `?controller=ClickupDesignTest`). Ruled
+  out `_underscore` PR #624 constants as the cause. (ajean)
 - 2026-07-06 — Diagnosed the "design-sprint API automation not running" report (TRUE-79685;
   tests TRUE-80026/80046): `handleFinalDesignOutcome` is silently no-opping in prod, masked by
   never-disabled native automation `c25fd345`. Narrowed to two suspects (folder-gate ID

package/package.json

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