toga-ai 1.0.274 → 1.0.276

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, _underscore/Component/Api/Clickup/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

@@ -6,11 +6,13 @@ 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
+  - _underscore/Component/Api/Clickup/Clickup.php
 related:
   - ./clickup-work-type-automation.md
   - ./team-sprint-management.md
@@ -22,87 +24,170 @@ 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 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.
 
 ## 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; now branches
+    on **all five** FDO options explicitly (no silent fall-through — see How it works).
+  - `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()`.
+  - `isInDesignSprintsFolder(...)` — **new** private folder-gate helper (reused by the
+    iterated-entry trigger).
   - `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.
+    to an option ID; now **string-compares** value/orderindex/id (see Gotchas).
+  - `spawnIterationTask(...)` / `buildIterationCreatePayload(...)` / `carryDesignApprover(...)` /
+    `carryComments(...)` (**new**) — duplicate the task and copy description, Design Approver,
+    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).
-- `Worker/Clickup.php` (dispatcher ~lines 822-875) — routes ClickUp webhooks; the Design
-  Approver / status guard lives at 822-833.
+- `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()`.
+- `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
    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.
+2. `handleFinalDesignOutcome` now branches on **all five** FDO options explicitly:
+   - **"Iterated – New Task"** → `spawnIterationTask` (duplicate) **then** `completeTask` on
+     the source.
+   - **"Approved"** → `completeTask`.
+   - **"Cancelled"** → `completeTask` (terminal; newly handled — Cancelled now closes the task).
+   - **"In Progress" / "In Review"** → explicit no-op.
+   - unrecognized → logged (no more silent implicit-else fall-through).
+3. **Iterated-entry trigger (new):** when a True Design Sprints task ENTERS the "iterated"
+   status, `handleTaskEnteredIterated()` sets FDO = **"In Review"** and increments the
+   **Iteration** custom field by +1. This is what now drives the review state + round count
+   on review submission; previously nothing fired on entering "iterated". Folder-gated.
+4. **Duplicate field carry-over:** the spawned iteration task copies description, Design
+   Approver, and **all user comments** (`carryComments()` — GET `/task/{id}/comment`,
+   re-posted oldest-first with `[Original by <user> on <date>]` attribution, non-fatal). It
+   copies **Iteration unchanged** (omitted if the source has none — the +1 now lives only on
+   the iterated-entry trigger, so a review round is never double-counted) and is set to
+   FDO = **"In Progress"** post-create (POST `/task/{id}/field/{id}` drop_down pattern).
 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.
+(`_Component_Api_Clickup`, `_underscore/Component/Api/Clickup/Clickup.php`) — confirmed
+present (worker2 PR #80, _underscore PR #624).
+
+**New FDO option constants (this session):** `FINAL_DESIGN_OUTCOME__IN_PROGRESS`,
+`FINAL_DESIGN_OUTCOME__IN_REVIEW`, and `FINAL_DESIGN_OUTCOME__CANCELLED` were added to
+`_Component_Api_Clickup` (previously only `..._ITERATED_NEW_TASK` and `..._APPROVED` existed).
+**Cross-repo coupling:** worker2 references these at runtime, so `_underscore` must deploy
+**together with** the worker2 change — deploying worker2 alone against an old _underscore
+throws undefined-constant. Both changes are on branch
+`feature/design-sprint-iterated-automation`.
 
 ## 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).
+- **The ClickUp API auth is a single hard-coded personal token — a dead token silently kills
+  ALL ClickUp automation.** The integration authenticates via one committed class constant,
+  `_Component_Api_Clickup::ACCESS_TOKEN` (in `_underscore/Component/Api/Clickup/Clickup.php`),
+  identical on `_production` and feature branches. This is a known secret-in-committed-code
+  risk. When the token is revoked/expired, `GET /user` and `GET /task` return **HTTP 401
+  "Oauth token not found" / error `OAUTH_019`**; `getTaskDetails` then throws and **every**
+  Clickup/Webhook worker job fails — presenting as "the automation silently does nothing."
+  This actually happened mid-session on 2026-07-07 (~09:49). **Fix:** regenerate the token in
+  ClickUp, update the `ACCESS_TOKEN` constant, and deploy `_underscore`. (Do not record the
+  token value anywhere.)
+- **Iterated-entry trigger is idempotent — order matters.** `handleTaskEnteredIterated()`
+  writes **FDO = In Review FIRST** as the marker, THEN increments Iteration. A re-delivered /
+  retried webhook sees FDO already "In Review" and skips, so **Iteration can never
+  compound-double-increment**. Worst case is a single missed +1, visible as a failed
+  WorkerJob. If you reorder these two writes you reintroduce the double-count risk.
+- **`taskStatusUpdated` dispatch structure (route-safety facts).** The
+  `switch ($historyItem->after->status)` block sits **OUTSIDE** the `if (!is_null($sprintNumber))`
+  guard, so entering-status handlers fire even for design tasks with no "sprint N" tag —
+  **each case must self-guard on `sprintNumber`** (the individual cases do). No webhook loop:
+  custom-field writes emit `taskUpdated` (not `taskStatusUpdated`) and land on the FDO no-op
+  cases; the Iteration write's custom_field is named "Iteration" so it never re-enters the FDO
+  dispatch gate.
+- **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. The "entering iterated" trigger added this session is
+  correctly placed under `switch ($historyItem->after->status)` (`case ...::STATUS_ITERATED` →
+  `handleTaskEnteredIterated()`) — distinct from the `before->status` switch.
+- **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 (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
+  Iteration +1; idempotent, folder-gated via new `isInDesignSprintsFolder()`), wired via a new
+  `case ...::STATUS_ITERATED` under `switch ($historyItem->after->status)` in `Clickup::Webhook`.
+  Moved the Iteration +1 OFF the spawn path (`buildIterationCreatePayload`) so the duplicate
+  copies Iteration unchanged and review rounds are not double-counted; the duplicate now also
+  sets FDO = In Progress post-create and carries over all user comments (`carryComments()`) plus
+  the existing description + Design Approver. `handleFinalDesignOutcome` now handles all five FDO
+  options explicitly (Cancelled now closes the task; In Progress/In Review are explicit no-ops;
+  unrecognized is logged). Added FDO option constants `__IN_PROGRESS`, `__IN_REVIEW`,
+  `__CANCELLED` to `_Component_Api_Clickup` in _underscore (cross-repo coupling — deploy
+  together). **Operational:** discovered the ClickUp `ACCESS_TOKEN` is a single committed
+  constant and was revoked mid-session (HTTP 401 / `OAUTH_019`), taking all ClickUp automation
+  down — documented the symptom and fix (regenerate + redeploy _underscore) as a gotcha. PR #98
+  is now MERGED to `_production` (commit `7a36564`) and live. (ajean)
+- 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.276",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",