toga-ai 1.0.271 → 1.0.272

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

@@ -4,6 +4,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 |
 | [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 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

@@ -0,0 +1,111 @@
+---
+title: ClickUp Design Sprint Automation (Final Design Outcome)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-07-06
+owners: ["ajean"]
+files:
+  - worker2/Worker/Clickup/Design.php
+  - worker2/Worker/Clickup.php
+related:
+  - ./clickup-work-type-automation.md
+  - ./team-sprint-management.md
+---
+
+## Summary
+`_Worker_Clickup_Design` is meant to drive the design-sprint workflow in ClickUp via the API,
+replacing a set of native ClickUp automations. When a task's **Final Design Outcome**
+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.
+
+## 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).
+  - `resolveFinalDesignOutcomeOptionId(...)` (Design.php:298-317) — maps the drop-down value
+    to an option ID.
+  - `spawnIterationTask(...)` / `carryDesignApprover(...)` — duplicate the task and copy the
+    Design Approver.
+  - `completeTask(...)` — closes an approved task.
+  - `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.
+
+## How it works
+1. A ClickUp webhook reaches `_Worker_Clickup`; the dispatcher (Clickup.php ~822-875) routes
+   design-folder events into `_Worker_Clickup_Design`.
+2. The worker acts on **only two** Final Design Outcome values:
+   - **"Iterated – New Task"** (option `3f835ac8…`) → `spawnIterationTask` — duplicates the
+     ticket into a new iteration task and carries over the Design Approver.
+   - **"Approved"** (option `2d17868b…`) → `completeTask`.
+3. The full Final Design Outcome option set is: In Progress, In Review, **Iterated – New
+   Task**, **Approved**, Cancelled. Only the two bolded values are actionable.
+4. A separate ClickUp automation (`a64c863a`) sets the outcome to **"In Review"** when a
+   task's *status* changes to Iterated. "In Review" is **not** actionable — so
+   `status → Iterated` alone never triggers the API. The worker acts only when the Design
+   Approver **manually** selects one of the two actionable outcome values.
+5. Daily reminder cron `Core.CronJobs` id 21 ("Design Review Reminders", `0 9 * * 1-5`,
+   action `Clickup/Design/SendReviewReminders`) nudges the approver about pending reviews.
+
+## Data model
+Configuration lives as ClickUp identifiers (folder IDs, custom-field IDs, drop-down option
+UUIDs), not in the DB. The custom-field / option-ID constants are defined in `_underscore`
+(`_production`) — confirmed present (worker2 PR #80, _underscore PR #624); the
+undefined-constant theory was ruled out.
+
+## Client variations
+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).
+
+## Change history
+- 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
+  mismatch, strict-`===` option resolution) pending a code+live-API fix session. Also
+  identified a latent spurious-email bug on spawned tasks and clarified that only
+  "Iterated – New Task" and "Approved" outcomes are actionable. (ajean)

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 22 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 25 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 26 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/package.json

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