toga-ai 1.0.17 → 1.0.18

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

@@ -3,3 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
+| [Error Response Envelope](features/error-response.md) | Every api2 action method returns the same three-key envelope. | api2/Controller/Index.php |
+| [Health Check Endpoint](features/health-endpoint.md) | `GET /health` returns HTTP 200 with an empty JSON object (`{}`). | api2/Controller/Index.php |

package/knowledge/2.0/apps/api2/features/error-response.md

@@ -2,7 +2,7 @@
 title: Error Response Envelope
 framework: "2.0"
 repo: api2
-project: TOGa API
+project: API
 client: shared
 type: feature
 status: active

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

@@ -3,4 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [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 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 |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |

package/knowledge/2.0/apps/worker2/features/clickup-project-routing.md

@@ -0,0 +1,123 @@
+---
+title: ClickUp Project & Opportunity Multi-List Routing
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-09
+owners: [jcardinal]
+files:
+  - worker2/Worker/Clickup/Project.php
+  - worker2/Worker/Clickup.php
+related:
+  - ../architecture.md
+  - ./creating-worker-actions.md
+---
+
+## Summary
+
+Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their
+custom-field values, via the `clickup` webhook. Implemented in `_Worker_Clickup_Project`
+(an abstract worker class) with three independent entry points covering three ClickUp spaces.
+
+**Hybrid design (the central constraint):** ClickUp's public **v2 API forbids changing or
+removing a task's home list** (`400 TASK_035 — Task home list cannot be altered`). So:
+- **Home-list movement** (e.g. moving a Project Hub Epic between phase lists) is owned by
+  **ClickUp native Automations** configured in the ClickUp UI — *not* this worker.
+- **Secondary multi-list ADD/DELETE** (where the list is never the task's home) is owned by
+  **this worker** via `POST /list/{id}/task/{id}` and `DELETE /list/{id}/task/{id}`.
+
+## Key files / entry points
+
+- `worker2/Worker/Clickup/Project.php` — `_Worker_Clickup_Project`, all routing logic.
+- `worker2/Worker/Clickup.php` — delegates from `_Worker_Clickup::Webhook()`:
+  - `taskStatusUpdated` (~L643): calls `handleEpicUpdate($taskId)` unconditionally.
+  - `taskUpdated` (~L826–828): behind a **self-trigger guard**, calls all three handlers.
+
+Three public entry points (all `public static function …(string $taskId): void`):
+
+| Handler | Space (guard) | Driver fields | Effect |
+|---|---|---|---|
+| `handleEpicUpdate` | Project Hub `90113939341` | Project Phase, Business Unit, Project Category | Places top-level Epics into the matching Lifecycle Services folder+list when BU = "Lifecycle Services"; removes from all LS lists otherwise. |
+| `handleOpportunityUpdate` | Opportunity/RFP Hub `90113928591` | Business Unit, Project Category, Opportunity Stage | Adds to the LS folder's **Opportunities** list when BU = "Lifecycle Services", category maps to an LS folder, and stage is not `Closed Lost` / not Won/Signed; removes otherwise. |
+| `handleAmOpportunityUpdate` | Opportunity/RFP Hub `90113928591` | Business Unit, Project Category, Opportunity Stage, Project Phase | Two passes: (1) space-level A&M Opportunities list; (2) A&M folder list driven by Opportunity Stage, with Execution→Completion driven by Project Phase = "Complete". |
+
+## How it works
+
+1. The `clickup` webhook → `_Worker_Clickup::Webhook()` → delegation in `Worker/Clickup.php`.
+2. Each handler fetches task details via `_Worker_Clickup::getTaskDetails()` (a per-invocation
+   `static` cache shared across all handlers in one job), then guards on **space id** and
+   **top-level** (`parent` empty). Epics/tasks are identified structurally — ClickUp Task
+   Types is not enabled, so `task_type` is unreliable.
+3. Custom fields are read by name via `extractCustomFields()` (one pass, last-non-null-wins,
+   trimmed) → mapped to a target list id → reconciled by `applyMultiListPlacement()`:
+   POST the target if absent, DELETE every other in-scope list (DELETE failures are caught
+   and logged, never fatal).
+
+### Custom field extraction — three ClickUp dropdown shapes
+
+`extractDropdownValue()` resolves a field value to its option text across:
+- **Legacy dropdown** — `value` is an integer → match `option->orderindex`.
+- **New dropdown** (`new_drop_down`) — `value` is a UUID string (webhooks) or sometimes still
+  an int (GET responses) → match `option->id`, fall back to `orderindex`.
+- **Labels / multi-select** — `value` is an array of UUIDs → first match wins.
+Option text is read from `option->name`, falling back to `option->label`.
+
+### Self-trigger guard (prevents flapping)
+
+Our own ADD/DELETE calls cause ClickUp to fire `taskUpdated` webhooks with
+`history_items[].field = list_added` / `list_removed`. The guard in `Worker/Clickup.php`
+(~L808) only re-invokes the handlers when a changed field is `custom_field` AND its name is
+one of: **Project Phase, Business Unit, Project Category, Opportunity Stage**. Without it the
+system flaps (POST → webhook → DELETE → webhook → …).
+
+## Data model
+
+None in MySQL — all state lives in ClickUp. Each invocation is recorded as a normal
+`Clickup/Webhook` row in `Core.WorkerJobs` (see worker2 architecture).
+
+ClickUp structure encoded as constants in `Project.php`: 4 LS folders
+(Onsite, Factory, Audio-Visual, Managed Services), 4 A&M folders (Retainer, Security,
+AI & Data Center, Cloud), plus space-level lists. Regenerate with the `DiscoverIds()` /
+`DiscoverAmIds()` diagnostic actions if the ClickUp structure changes.
+
+## Client variations
+
+None — uniform across all clients (shared internal automation for Agilant's ClickUp workspace).
+
+## Gotchas / known issues
+
+- **List-name slash spacing differs by space, intentionally:** LS uses
+  `"Client Scoping / Discovery"` (space before slash); A&M uses `"Client Scoping/ Discovery"`
+  (no space). These match the real ClickUp list names — do not "fix" one to match the other.
+- **String-typed list IDs:** `collectCurrentMemberships()` returns IDs as **strings** and
+  avoids array-key dedup, because PHP coerces numeric-string keys to int and would break the
+  strict `in_array` comparisons against the string constants.
+- **Shared `getTaskDetails()` cache is stale after writes:** all three handlers share one
+  cached task fetch per job. After one handler mutates memberships, the cached `locations`
+  are stale for the others. Currently safe only because the space guards are mutually
+  exclusive (a task lives in one space → exactly one handler does work). Wiring a second
+  handler onto `taskStatusUpdated`, or overlapping list scopes, would break this.
+- **`RATE_LIMIT_DELAY_US` (120ms) is defined but unused** — pacing relies entirely on
+  `_Component_Api_Clickup::send()`'s internal `sleep(1)`. `handleAmOpportunityUpdate` can
+  issue several placement passes (multiple POST/DELETE) per event.
+- **POST failures are fatal, DELETE failures are tolerated** — a failed ADD leaves the task
+  out of its correct list (surfaced as job failure); a failed DELETE (most likely TASK_035,
+  which shouldn't occur on secondary lists) is logged with `[ClickupProject]` and skipped.
+- **Webhook subscriptions** must cover each space. Three exist, all → `webhook.togahub.com/clickup`:
+  legacy sprint space `90020178491`, Project Hub `90113939341`, Lifecycle Services
+  `90114156087`. Opportunity Hub coverage is registered via `RegisterOpportunityWebhook()`.
+
+## Diagnostics
+
+Read-only actions (no writes), invoked via `curl -X POST https://worker.togahub.com/` with
+`{"action":"Clickup/Project/<Method>","parameters":{...}}`:
+`DiagnoseOpportunity`, `DiagnoseAmTask` (routing verdicts), `DiscoverIds`, `DiscoverAmIds`
+(print constant declarations), `RegisterOpportunityWebhook` (one-time setup).
+
+## Related docs
+
+- [Worker (worker2) Architecture](../architecture.md) — always-HTTP-200, commit-before-SQS.
+- [Creating Worker Actions](./creating-worker-actions.md) — the worker-action contract.

package/knowledge/INDEX.md

@@ -10,8 +10,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 2 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 2 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **worker2** (Worker) — 3 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **api2** (API) — 3 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 
 ## Clients
 

package/package.json

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