toga-ai 1.0.558 → 1.0.560

package/.claude/settings.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/kickoff-gate.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/kickoff-gate.js\"",
             "timeout": 3000
           }
         ]
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/kickoff-gate.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/kickoff-gate.js\"",
             "timeout": 3000
           }
         ]
@@ -27,7 +27,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/block-destructive.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/block-destructive.js\"",
             "timeout": 3000
           }
         ]
@@ -37,7 +37,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/guard-index.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/guard-index.js\"",
             "timeout": 3000
           }
         ]
@@ -47,7 +47,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/dbchanges2-cluster-isolation.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/dbchanges2-cluster-isolation.js\"",
             "timeout": 3000
           }
         ]
@@ -57,7 +57,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/dbchanges2-record-ids.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/dbchanges2-record-ids.js\"",
             "timeout": 3000
           }
         ]
@@ -69,7 +69,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/post-edit-validate.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/post-edit-validate.js\"",
             "timeout": 15000
           }
         ]
@@ -79,7 +79,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/remind-php-review.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/remind-php-review.js\"",
             "timeout": 3000
           }
         ]
@@ -89,7 +89,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/remind-sql-review.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/remind-sql-review.js\"",
             "timeout": 3000
           }
         ]
@@ -99,7 +99,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/scope-counter.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/scope-counter.js\"",
             "timeout": 3000
           }
         ]
@@ -110,7 +110,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/session-start.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/session-start.js\"",
             "timeout": 5000
           }
         ]
@@ -121,7 +121,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/session-end.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/session-end.js\"",
             "timeout": 5000
           }
         ]
@@ -130,7 +130,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/evaluate-session.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/evaluate-session.js\"",
             "timeout": 5000
           }
         ]
@@ -139,7 +139,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \".claude/hooks/toga/remind-php-lint.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/remind-php-lint.js\"",
             "timeout": 3000
           }
         ]

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

@@ -32,7 +32,7 @@
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [NYCHH Asset-Tag Backfill (worker2)](features/nychh-asset-tag-backfill.md) | Keeps NYC Health & Hospitals (`Client_Nychh`) unit asset tags and MAC addresses synced from NetSuite. | worker2/Worker/Client/Nychh.php, worker2/Worker/Client/Nychh/AssetTagBackfill.php, worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php, worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php |
-| [OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)](features/oneuptime-incident-clickup-sync.md) | An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for **currently-open** incidents and ensures a ClickUp task exists for eac | worker2/Component/Api/Oneuptime/Oneuptime.php, worker2/Worker/Monitor/Oneuptime.php, worker2/Config/production.ini, dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql, dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql |
+| [OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)](features/oneuptime-incident-clickup-sync.md) | An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for **currently-open** incidents and ensures a ClickUp task exists for eac | worker2/Component/Api/Oneuptime/Oneuptime.php, worker2/Worker/Monitor/Oneuptime.php, worker2/Config/production.ini, dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql, dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql, dbchanges2/Team/2026-08-12a - OneUptime Incident Tasks Closed Marker.sql |
 | [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.php, worker2/Worker/Monitor/Operations.php |
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |

package/knowledge/2.0/apps/worker2/features/oneuptime-incident-clickup-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-12
 owners: ["jcardinal"]
 files:
   - worker2/Component/Api/Oneuptime/Oneuptime.php
@@ -14,6 +14,7 @@ files:
   - worker2/Config/production.ini
   - dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql
   - dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql
+  - dbchanges2/Team/2026-08-12a - OneUptime Incident Tasks Closed Marker.sql
 related:
   - ./oneuptime-worker2-monitoring.md
   - ./error-escalation-cron.md
@@ -41,7 +42,7 @@ reporter, smart monitor"; this feature adds the reader half.
   open incidents (filters out resolved **in PHP**).
 - `worker2/Worker/Monitor/Oneuptime.php` — `_Worker_Monitor_Oneuptime::SyncIncidents(): string`,
   the cron action. Returns a structured summary string on every path
-  (`incidentsPolled` / `created` / `skipped` / `failed`).
+  (`incidentsPolled` / `created` / `skipped` / `failed`, plus `closed` / `closeFailed`).
 
 ## How it works
 
@@ -68,6 +69,36 @@ worker2 way to prevent duplicate ClickUp tasks under overlapping cron runs — p
 from `_Worker_Infrastructure_Errors::createClickupTask`. `INSERT … WHERE NOT EXISTS` is
 **insufficient** under REPEATABLE READ; the UNIQUE key is the concurrency arbiter.
 
+### Close pass (auto-close on incident resolution)
+
+The sync was originally **create-only**; a ClickUp task opened for an incident was never
+closed once the incident resolved, so a recurrence (a *new* OneUptime incident with the same
+monitor title) opened a second task that **looked like a duplicate** but was not (see the
+gotcha below). `SyncIncidents()` now runs a **close pass first** each cycle, independent of how
+many incidents are currently open, via `closeResolvedIncidents()`:
+
+- SELECT ledger rows `WHERE clickupIdentifier IS NOT NULL AND dtClosed IS NULL`.
+- For each, call `_Component_Api_Oneuptime::getIncidentResolvedState(string $incidentId): ?bool`
+  — `true` = resolved, `false` = confirmed still open, `null` = unknown. **Only a definite
+  `true` closes a task**; `null` means "leave alone" so an ambiguous read never closes a live
+  incident's ticket. This lookup uses a new per-incident route (`ROUTE__INCIDENT_ITEM`,
+  `/api/incident/{id}/get-item`, still a PLACEHOLDER) because resolved incidents no longer
+  appear in `getActiveIncidents()` and must be re-checked individually. A 2xx response missing
+  `currentIncidentState.isResolvedState` logs a warning (incident id only, no body/PII) so a
+  wrong placeholder shape is detectable rather than silently returning `null` forever.
+- To close, PUT `/task/{id}` with the list's **closed-type status NAME** (ClickUp has no
+  generic close verb — see gotcha), resolved per-list via `GET /list/{id}` `statuses[]` where
+  `type == 'closed'`, cached per run in `$closedStatusByList`. Then stamp `dtClosed = NOW()`.
+- `dtClosed` is stamped **only after a successful close**, so a failure retries next run.
+  Per-incident failures are caught (`Throwable`) + `error_log` + counted, not fatal; whole-run
+  failures (e.g. no sprint list) still re-throw for queue retry.
+- All new ClickUp calls in the close path are throttled with
+  `usleep(_Worker_Clickup_Project::RATE_LIMIT_DELAY_US)` (120ms = 500/min), matching
+  `_Worker_Infrastructure_Errors`.
+
+Helpers added: `closeResolvedIncidents()`, `closeClickupTask()`, `resolveClosedStatusForList()`,
+`markClosed()`, and the `$closedStatusByList` per-run cache.
+
 ### Target list = current sprint list
 
 The ClickUp task lands in the **current sprint** list, resolved by `GET /folder/{id}` and
@@ -80,8 +111,11 @@ id is read from `[clickup] sprint_folder_id` with a constant fallback (`90020432
 
 `OneUptimeIncidentTasks` (CREATE on the **Team** cluster — chosen over Logs;
 `dbchanges2/Team/2026-08-10a`): `id`, `uuid char(36)`, `dtCreated`,
-`oneuptimeIncidentId varchar(64)`, `clickupIdentifier varchar(64) NULL`. The **UNIQUE KEY on
+`oneuptimeIncidentId varchar(64)`, `clickupIdentifier varchar(64) NULL`, `dtClosed DATETIME NULL` (added
+`dbchanges2/Team/2026-08-12a`, `AFTER clickupIdentifier`). The **UNIQUE KEY on
 `oneuptimeIncidentId`** is the dedup contract, same rationale as `IssueClickupTasks`.
+`dtClosed` marks a ledger row whose ClickUp task has been closed following incident
+resolution (NULL = still open / not yet closed).
 
 ## Provisioning / deploy
 
@@ -104,13 +138,30 @@ id is read from `[clickup] sprint_folder_id` with a constant fallback (`90020432
 
 ## Gotchas / known issues
 
-- **Incident-list route/fields are PLACEHOLDER** (`/api/incident/get-list`) pending
-  confirmation against the live OneUptime instance. Do not enable the cron (`isActive = 1`)
-  until the route and returned fields are verified.
+- **Same-title ClickUp tickets from OneUptime are expected on incident recurrence.** Dedup is
+  **per-incident-id, not per-title**: the `oneuptimeIncidentId` UNIQUE key + claim-first insert
+  only prevents duplicates for the *same* incident id. Two tasks with the same monitor title
+  minutes apart are two *different* OneUptime incidents, not a dedup failure. The symptom that
+  looked like duplication was actually the missing auto-close: incident #1 resolved but its
+  task never closed, then a fresh incident opened a second task. Auto-close (above) closes
+  #1 on resolution so a recurrence (#2) is the only open ticket.
+- **ClickUp has no generic "close" verb.** A task is closed by PUTting the exact NAME of the
+  status whose `type == 'closed'`, which is **list-specific** — resolved per-list from
+  `GET /list/{id}` `statuses[]` and cached per run.
+- Throttle every ClickUp call in the close path with `usleep(RATE_LIMIT_DELAY_US)` (120ms) or
+  rate-limit failures degrade into `closeFailed` counts.
+- **Both OneUptime routes remain PLACEHOLDERS** — the incident-list route
+  (`/api/incident/get-list`) *and* the new per-incident route (`/api/incident/{id}/get-item`,
+  `ROUTE__INCIDENT_ITEM`) are unverified against the live OneUptime API. Auto-close **fails
+  safe** (only a definite resolved `true` closes anything; `null` leaves the task alone) but
+  won't fire until the route/field shape is confirmed. Do not enable the cron (`isActive = 1`)
+  until the routes and returned fields are verified.
 - **OneUptime cannot filter open-only server-side here** — resolution filtering happens in
   PHP, so the returned field set must actually carry the resolved/open state.
 - Ship the worker2 code deploy and both dbchanges2 migrations **together**; the cron row is
   inert until the action is deployed and the ledger table exists.
+- **Deploy order for the auto-close change:** run `dbchanges2/Team/2026-08-12a` (the `dtClosed`
+  column) **before** the worker2 code deploys — the new close-pass queries reference `dtClosed`.
 
 ## Change history
 - 2026-08-10 — Built: first OneUptime API *reader* (`_Component_Api_Oneuptime`) + the
@@ -118,5 +169,13 @@ id is read from `[clickup] sprint_folder_id` with a constant fallback (`90020432
   ClickUp task in the current sprint list; new `OneUptimeIncidentTasks` ledger (Team cluster,
   UNIQUE on incident id) and a seeded-inactive `*/15 * * * *` cron row. Incident-list route
   left PLACEHOLDER pending confirmation. (jcardinal)
+- 2026-08-12 — Built: auto-close of ClickUp tasks when the OneUptime incident resolves (the
+  sync was create-only). Added `dtClosed` marker to the ledger
+  (`dbchanges2/Team/2026-08-12a`), `_Component_Api_Oneuptime::getIncidentResolvedState()` +
+  PLACEHOLDER per-incident route, and a close-first pass in `SyncIncidents()` (resolves each
+  list's `type=='closed'` status name, PUTs it, stamps `dtClosed` only on success, throttled
+  120ms; return string now carries `closed`/`closeFailed`). Discovered: apparent duplicate
+  same-title tickets were two distinct incidents — dedup is per-incident-id, not per-title; the
+  real gap was the missing close path. (jcardinal)
 </content>
 </invoke>

package/package.json

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