toga-ai 1.0.171 → 1.0.173

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

@@ -3,6 +3,7 @@
 | 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 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 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 Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work Type** custom field — `Committed`, `Conditional`, or `Stretch` — base | worker2/Worker/Clickup.php, worker2/Tests/Worker/ClickupWorkTypeTest.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-connectivity-watchdog.md

@@ -0,0 +1,81 @@
+---
+title: ClickUp Connectivity Watchdog
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [ajean]
+files:
+  - worker2/Worker/Clickup/Health.php
+  - worker2/Database/ClickupHealthWatchdog.sql
+related:
+  - ./clickup-project-routing.md
+  - ../architecture.md
+---
+
+## Summary
+
+A cron watchdog that emails when the ClickUp integration looks disconnected during business
+hours. Implemented in `_Worker_Clickup_Health` (action `Clickup/Health/Check`). It exists
+because the ClickUp webhook subscriptions can silently die (a dropped subscription, a ClickUp
+outage, or our endpoint failing), and nobody notices until reporting/automations drift.
+
+## Key files / entry points
+
+- `worker2/Worker/Clickup/Health.php` — `_Worker_Clickup_Health::Check(): string` (the cron
+  action) + `initialize()` (registers the `Team` DB, same pattern as `_Worker_Team_Transcripts`).
+- `worker2/Database/ClickupHealthWatchdog.sql` — run-once reference: the `Team.ClickUpHealthState`
+  table + the `Core.CronJobs` row. Canonical migrations live in `dbchanges2`
+  (`Team/2026-06-23a …`, `Core/2026-06-23a …`).
+
+## How it works
+
+Scheduled every 15 min on weekdays 09:00–16:45 Central (cron `0,15,30,45 9-16 * * 1-5`).
+`Check()` evaluates two signals and emails `ajean@togatech.com` if either fires:
+
+1. **Inbound silence** — `MAX(dtCreated)` of `Core.WorkerJobs WHERE action = 'Clickup/Webhook'`
+   (exact match, so the watchdog's own `Clickup/Health/Check` rows don't count). Elapsed minutes
+   are computed by **MySQL `TIMESTAMPDIFF`** (no PHP/DB timezone mismatch). Alerts when ≥ 60 min
+   silent, but only from the **second business hour onward** (a one-hour warm-up so the expected
+   overnight gap isn't flagged at 09:00).
+2. **Webhook health** — `GET /team/{id}/webhook`; any subscription whose endpoint contains
+   `togahub.com` with `health->status == 'failing'`. The probe is wrapped in try/catch — if the
+   probe call itself throws, that is treated as a connectivity signal too.
+
+De-duplication: `Team.ClickUpHealthState` (single row) records `dtLastAlerted`; an ongoing
+outage re-emails at most once per 60 min (`shouldAlert`), and the flag is cleared when ClickUp
+is healthy again (`clearAlert`) so each fresh outage notifies once.
+
+## Data model
+
+- **`Team.ClickUpHealthState`** — single-row alert state: `id`, `uuid`, `dtCreated`, `dtUpdated`,
+  `dtLastAlerted` (NULL when healthy), `lastReason`. The row is created lazily on first alert.
+- **`Core.CronJobs`** — one row, action `Clickup/Health/Check`, `maxExecutionTime` 120.
+
+## Client variations
+
+None — internal monitoring for Agilant's ClickUp workspace.
+
+## Gotchas / known issues
+
+- **Detects ClickUp-side problems only.** It runs *inside* the worker/cron pipeline, so it
+  assumes that pipeline is healthy. It will **not** fire if the EB worker tier, the CronScheduler
+  Lambda, or the database is itself down — full worker-down detection needs an external uptime
+  monitor (not built).
+- **The inbound query must match `Clickup/Webhook` exactly.** A `LIKE 'Clickup/%'` would also
+  match the watchdog's own `Clickup/Health/Check` rows and the timer would never expire.
+- **Email identifier is `'True'`** (the internal/team `clientIdentifier`, consistent with other
+  team alerts via `_Worker_Notification_Email::Send`).
+- **Business window is enforced in code too** (Mon–Fri, 09:00–17:00 Central), not just in the
+  cron schedule, so a manual run outside hours is a safe no-op.
+
+## Change history
+- 2026-06-23 — Created. Watchdog cron emails on 60-min inbound webhook silence or a failing subscription during business hours; deduped via `Team.ClickUpHealthState`. (ajean)
+
+## Related docs
+
+- [ClickUp Project & Opportunity Multi-List Routing](./clickup-project-routing.md) — the integration this watches.
+- [Worker (worker2) Architecture](../architecture.md) — CronJobs, WorkerJobs, always-HTTP-200.

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

@@ -6,21 +6,23 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-09
-owners: [jcardinal]
+updated: 2026-06-23
+owners: [jcardinal, ajean]
 files:
   - worker2/Worker/Clickup/Project.php
   - worker2/Worker/Clickup.php
 related:
   - ../architecture.md
   - ./creating-worker-actions.md
+  - ./clickup-connectivity-watchdog.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.
+(an abstract worker class) with three independent routing entry points covering three ClickUp
+spaces, plus a **hub-placement guard** that keeps Epics/Opportunities anchored to their hub.
 
 **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:
@@ -35,8 +37,9 @@ removing a task's home list** (`400 TASK_035 — Task home list cannot be altere
 - `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.
+  - `taskCreated` and `taskMoved`: call `enforceHubPlacement($taskId)` (the guard, below).
 
-Three public entry points (all `public static function …(string $taskId): void`):
+Three routing entry points (all `public static function …(string $taskId): void`):
 
 | Handler | Space (guard) | Driver fields | Effect |
 |---|---|---|---|
@@ -44,13 +47,39 @@ Three public entry points (all `public static function …(string $taskId): void
 | `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". |
 
+### Hub-placement guard — `enforceHubPlacement(string $taskId): void` (added 2026-06-23)
+
+Keeps **Epics in Project Hub** and **Opportunities in Opportunity/RFP Hub**. Called from the
+`taskCreated` and `taskMoved` cases in `Worker/Clickup.php`. Unlike the three routing handlers
+(which identify tasks structurally), it identifies the type by **custom Task Type**
+(`custom_item_id`, configured via the `TASK_TYPE_EPIC_ID` / `TASK_TYPE_OPPORTUNITY_ID`
+constants). A task is **misplaced** when its **home** `space->id` is not its hub — i.e. it was
+created in, or moved into, Lifecycle Services / Advisory & Modernization (or any other space).
+
+For a misplaced top-level task it:
+1. **Backfills metadata** (best-effort, LS/A&M only) — Business Unit from the home space
+   (`getBusinessUnitForSpaceId()`), Project Category from the home folder
+   (`getProjectCategoryForFolderId()`, the **inverse** of `getLsFolderKey`/`getAmFolderKey` —
+   keep them in sync). Written via `setDropdownFieldByName()`, which handles both `drop_down`
+   and `labels` field shapes and writes only when the value differs.
+2. **Re-adds the correct hub intake list** as a secondary membership (Epic →
+   `PROJECT_HUB_INTAKE_LIST_ID`, Opportunity → `OPPORTUNITY_HUB_INTAKE_LIST_ID`). The home list
+   itself cannot be moved by the API (TASK_035) — a human must do that.
+3. **Posts a one-time comment** (only when it actually just added the membership) telling the
+   user to move the home list back manually.
+
+**Ships inert**: with `TASK_TYPE_*_ID` both `null` it is a no-op, so it can deploy before the
+ids are discovered. Configure via the `DiscoverTaskTypes()` / `DiscoverIds()` actions, then
+`RegisterHubGuardWebhooks()`.
+
 ## 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.
+   **top-level** (`parent` empty). The three routing handlers identify Epics/tasks
+   **structurally** (space + top-level). Custom **Task Types are now configured**, and the
+   newer `enforceHubPlacement` guard keys on `custom_item_id` to recognize Epics/Opportunities.
 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
@@ -80,8 +109,9 @@ None in MySQL — all state lives in ClickUp. Each invocation is recorded as a n
 
 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.
+AI & Data Center, Cloud), plus space-level lists, the hub intake lists, and the Epic/Opportunity
+custom Task Type ids. Regenerate with the `DiscoverIds()` / `DiscoverAmIds()` /
+`DiscoverTaskTypes()` diagnostic actions if the ClickUp structure changes.
 
 ## Client variations
 
@@ -89,38 +119,52 @@ None — uniform across all clients (shared internal automation for Agilant's Cl
 
 ## Gotchas / known issues
 
+- **Hub-guard correctness rests on the HOME space:** `enforceHubPlacement` filters on
+  `taskDetails->space->id`, which always follows the task's **home** list. A hub Epic that the
+  routing handlers mirror into LS/A&M as a *secondary* membership still reports its home hub as
+  the space, so the guard correctly ignores it. Filtering on home space is what stops the guard
+  from fighting the secondary-membership routing.
+- **`getProjectCategoryForFolderId()` must stay in sync** with `getLsFolderKey`/`getAmFolderKey`
+  and the `*_FOLDER_*` constants — it is their inverse (folder id → Project Category value).
 - **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.
+  strict `in_array` comparisons against the string constants. (`getProjectCategoryForFolderId`
+  relies on that same numeric-string→int coercion being *consistent* between map keys and the
+  lookup, so it is correct; a hidden/leading-zero folder id falls through to `null`.)
+- **Shared `getTaskDetails()` cache is stale after writes:** all handlers share one cached task
+  fetch per job. After one handler mutates memberships, the cached `locations` are stale for the
+  others. Safe today because the space guards are mutually exclusive (a task lives in one space →
+  exactly one handler does work).
+- **`RATE_LIMIT_DELAY_US` (120ms):** now used by `enforceHubPlacement` / `setDropdownFieldByName`
+  (`usleep`); the three routing handlers still rely on `_Component_Api_Clickup::send()`'s internal
+  `sleep(1)`.
 - **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`:
+- **Webhook subscriptions** must cover each space, all → `webhook.togahub.com/clickup`. Routing:
   legacy sprint space `90020178491`, Project Hub `90113939341`, Lifecycle Services
-  `90114156087`. Opportunity Hub coverage is registered via `RegisterOpportunityWebhook()`.
+  `90114156087`; Opportunity Hub via `RegisterOpportunityWebhook()`. The hub guard additionally
+  needs **`taskCreated` on LS + A&M** and a **workspace-wide `taskMoved`**, registered via
+  `RegisterHubGuardWebhooks()` (which skips any already covered to avoid double-delivery).
 
 ## Diagnostics
 
-Read-only actions (no writes), invoked via `curl -X POST https://worker.togahub.com/` with
+Read-only / setup actions, 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).
+`DiagnoseOpportunity`, `DiagnoseAmTask` (routing verdicts), `DiscoverIds`, `DiscoverAmIds`,
+`DiscoverTaskTypes` (print constant declarations / custom-task-type ids),
+`TestHubGuardMappings` (pure self-test of the folder→category & space→BU maps; expect
+`RESULT: PASS`), `RegisterOpportunityWebhook` and `RegisterHubGuardWebhooks` (one-time setup).
 
 ## Change history
+- 2026-06-23 — Added the hub-placement guard (`enforceHubPlacement` on `taskCreated`/`taskMoved`): re-anchors misplaced Epics/Opportunities to their hub by custom Task Type + home space, backfills Business Unit/Project Category, and notifies. Added `DiscoverTaskTypes`, `RegisterHubGuardWebhooks`, `TestHubGuardMappings`. Corrected the earlier "Task Types not enabled" note. (ajean)
 - 2026-06-09 — Documented ClickUp secondary multi-list routing (hybrid native-automation + worker design, three space handlers, self-trigger guard). (jcardinal)
 
 ## Related docs
 
 - [Worker (worker2) Architecture](../architecture.md) — always-HTTP-200, commit-before-SQS.
 - [Creating Worker Actions](./creating-worker-actions.md) — the worker-action contract.
+- [ClickUp Connectivity Watchdog](./clickup-connectivity-watchdog.md) — the email-alert health check.

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 11 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 10 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 11 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 4 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 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.171",
+  "version": "1.0.173",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/skills/session-resume/SKILL.md

@@ -47,7 +47,12 @@ to change the threshold. If it prints "No team sessions saved yet.", say so and
 No team sessions saved yet. Save one at the end of your work: /session-save [name]
 ```
 
-**`list` mode:** render this table and stop here.
+Whenever you render this table to the developer (in `list` mode **and** in the
+no-argument discovery flow), explicitly disclose that delete is available — e.g. a
+trailing line: "To retire a stale session, run `/session-resume delete <id>`." A
+developer must never have to already know the command to discover it.
+
+**`list` mode:** render this table (with the delete disclosure) and stop here.
 
 **`delete <id>` mode:** confirm with the developer, then run
 `node "<TEAM_REPO>/knowledge.js" session-delete <id> --msg="session: retire <id>"`,
@@ -61,7 +66,8 @@ report the `SESSION: DELETED|NOT_FOUND|CONFLICT` result, and stop.
 - `<slug-or-id>` → the row whose id equals it or contains the slug. If several match
   (same slug, different authors/dates), show those candidates (date + author) and ask which.
 - If none match: "No session found matching '<x>'. Available: [list ids]."
-- No argument → ask: "Which session should I load? (id or slug)"
+- No argument → ask: "Which session should I load? (id or slug — or `delete <id>` to
+  retire a stale one)"
 
 ---