toga-ai 1.0.333 → 1.0.334

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

@@ -9,6 +9,7 @@
 | [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 |
+| [ClickUp Subtask Activity → Parent Opportunity/Epic Comments](features/clickup-subtask-activity.md) | Surfaces **subtask** progress, completion, and discussion on the top-level **Opportunity** or **Epic** it rolls up to, so a deal/project owner sees activity whe | worker2/Worker/Clickup/Subtask.php, worker2/Worker/Clickup.php, dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql |
 | [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 |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |

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

@@ -15,6 +15,7 @@ related:
   - ../architecture.md
   - ./creating-worker-actions.md
   - ./clickup-connectivity-watchdog.md
+  - ./clickup-subtask-activity.md
 ---
 
 ## Summary
@@ -78,8 +79,11 @@ ids are discovered. Configure via the `DiscoverTaskTypes()` / `DiscoverIds()` ac
 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). 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.
+   **structurally** (space + top-level). The `enforceHubPlacement` guard was written to key on
+   `custom_item_id`, but the Task-Types ClickApp is **not reliably enabled** on the hub spaces
+   and `TASK_TYPE_EPIC_ID` / `TASK_TYPE_OPPORTUNITY_ID` remain `null` — so that guard is
+   effectively **inert** in practice; structural (space + top-level) identification is what
+   actually runs (see Gotchas, and `./clickup-subtask-activity.md`).
 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
@@ -160,6 +164,7 @@ Read-only / setup actions, invoked via `curl -X POST https://worker.togahub.com/
 `RESULT: PASS`), `RegisterOpportunityWebhook` and `RegisterHubGuardWebhooks` (one-time setup).
 
 ## Change history
+- 2026-07-14 — Correction: `TASK_TYPE_EPIC_ID` / `TASK_TYPE_OPPORTUNITY_ID` are still `null` and the Task-Types ClickApp is not reliably enabled on the hub spaces, so `enforceHubPlacement`'s custom-Task-Type keying is inert; structural (space + top-level) identification is what actually runs. Cross-linked the new subtask-activity feature (same hub spaces/pipeline). (ajean)
 - 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)
 

package/knowledge/2.0/apps/worker2/features/clickup-subtask-activity.md

@@ -0,0 +1,117 @@
+---
+title: ClickUp Subtask Activity → Parent Opportunity/Epic Comments
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: draft
+updated: 2026-07-14
+owners: [ajean]
+files:
+  - worker2/Worker/Clickup/Subtask.php
+  - worker2/Worker/Clickup.php
+  - dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql
+related:
+  - ./clickup-project-routing.md
+  - ../architecture.md
+---
+
+## Summary
+
+Surfaces **subtask** progress, completion, and discussion on the top-level **Opportunity**
+or **Epic** it rolls up to, so a deal/project owner sees activity where they actually look.
+On a `clickup` webhook for a subtask (a task with a non-empty `parent`) of event
+`taskStatusUpdated` or `taskCommentPosted`, the worker walks the parent chain to the
+top-level ancestor and, if that ancestor is an Opportunity (Opportunity/RFP Hub space
+`90113928591`) or an Epic (Project Hub space `90113939341`), posts **one** comment on the
+ancestor. Implemented in `_Worker_Clickup_Subtask` (extends `_Worker_Clickup`), fanned out
+from a pre-switch block in `_Worker_Clickup::Webhook()`.
+
+> **Status: not yet deployed / not live-verified.** PRs open: worker2 #110, dbchanges2 #427.
+> The dbchanges2 migration must run **before or with** the worker deploy (the worker reserves
+> a ledger row before every post).
+
+## Key files / entry points
+
+- `worker2/Worker/Clickup/Subtask.php` — `_Worker_Clickup_Subtask` (NEW), all subtask
+  fan-out / ancestor-walk / dedup / post logic.
+- `worker2/Worker/Clickup.php` — a **pre-switch fan-out block** in `_Worker_Clickup::Webhook()`
+  detects a subtask event and dispatches `_Worker::runTask('Clickup/Subtask/Process',
+  ['taskId', 'event', 'data' => history_items])`. The block is wrapped in a best-effort
+  `try/catch (Throwable)` and **deliberately does not `return`** — it falls through to the
+  existing `taskStatusUpdated` / `taskCommentPosted` switch, so sprint / work-type handling is
+  unaffected.
+- `dbchanges2/Team/2026-07-14a - Add ClickupSubtaskActivity ledger.sql` (NEW) — creates the
+  `ClickUpSubtaskActivity` dedup ledger table in the **Team** DB.
+
+## How it works
+
+1. Webhook arrives → `_Worker_Clickup::Webhook()`. The pre-switch block short-circuits **early
+   on the subtask's own space** before any parent walk (a subtask lives in the same space as its
+   ancestor, so a non-hub space is discarded before spending API calls).
+2. `Clickup/Subtask/Process` walks up the `parent` chain to the top-level (no-parent) ancestor
+   and confirms it is an Opportunity or Epic **structurally** — by home space id + top-level —
+   mirroring `handleEpicUpdate` / `handleOpportunityUpdate`. **Not** by custom Task Type: the
+   Task-Types ClickApp is not reliably enabled on the hub spaces (see Gotchas).
+3. Triggers:
+   - **Status** — post when the subtask status moves into `in progress`, `roadblocked`, or
+     `on hold` (matched by **lowercase status name**, consistent with existing status
+     comparisons in `Worker/Clickup.php`), OR into any completed status (matched by **status
+     TYPE** in `done`/`closed` via the inherited `COMPLETE_STATUS_TYPES`).
+   - **Comment** — any user comment posted on the subtask is mirrored to the ancestor as
+     `"💬 <author> commented on subtask …"`.
+4. Every post carries a trailing `(automated)` marker. Comments that already carry that marker
+   are **never** mirrored (loop guard).
+5. Posts use `_Component_Api_Clickup::send('POST', '/task/{id}/comment',
+   ['comment_text' => …, 'notify_all' => false])`; task lookups reuse
+   `_Worker_Clickup::getTaskDetails()` (in-process static cache);
+   `_Worker_Clickup_Project::RATE_LIMIT_DELAY_US` paces the parent walk.
+
+### Dedup ledger (the authoritative guard)
+
+Before posting, the worker **reserves a ledger row** (`INSERT` into `ClickUpSubtaskActivity`)
+so the `UNIQUE(subtaskId, activityKey)` constraint — not a check-then-act window — is the
+authoritative dedup guard against re-delivered webhooks. If the comment POST fails, the row is
+**released** (`DELETE`) so a retry can re-attempt. The `activityKey` is:
+- `status:<name>` for a watched named status,
+- `status:completed` for a completion,
+- `comment:<clickupCommentId>` for a mirrored comment — falling back to the history-item id,
+  then a per-event date, then `md5(text)`, so identical comment texts stay distinct.
+
+Ledger access follows the `ClickUpHealthState` pattern from `_Worker_Clickup_Health`: raw
+`_Query` on `_underscore::DB_TEAM` with `_Database::escape()`.
+
+## Data model
+
+`ClickUpSubtaskActivity` in the **Team** DB (dbchanges2 migration `2026-07-14a`):
+`id`, `uuid`, `subtaskId VARCHAR(32)`, `activityKey VARCHAR(255)`, `dtPosted`, with
+`UNIQUE(subtaskId, activityKey)`. All other state lives in ClickUp.
+
+## Client variations
+
+None — internal automation for Agilant's ClickUp workspace, uniform across clients.
+
+## Gotchas / known issues
+
+- **Ancestor identification is STRUCTURAL, not by Task Type.** The Task-Types ClickApp is not
+  reliably enabled on the hub spaces, and `_Worker_Clickup_Project`'s `TASK_TYPE_EPIC_ID` /
+  `TASK_TYPE_OPPORTUNITY_ID` remain `null` (inert). Identify Opportunities/Epics by home space
+  id + top-level, exactly like the routing handlers — do not rely on `custom_item_id` here.
+- **Completion matches by status TYPE (`done`/`closed`), not name** — it survives label
+  changes. The other watched statuses match by lowercase **name** (`in progress`,
+  `roadblocked`, `on hold`).
+- **Loop guard is the `(automated)` marker** — every automated post carries it, and any comment
+  carrying it is skipped on mirror. Removing/altering the marker text re-opens the mirror loop.
+- **Fan-out never returns** — it falls through to the existing switch on purpose; keep it that
+  way or existing sprint/work-type handling breaks.
+- **Migration ordering** — deploy the dbchanges2 `2026-07-14a` migration before/with the worker;
+  the worker reserves a ledger row on every post and will error without the table.
+
+## Change history
+- 2026-07-14 — Created (draft, not yet deployed): subtask status/completion/comment mirroring to the parent Opportunity/Epic via `_Worker_Clickup_Subtask`, guarded by the `ClickUpSubtaskActivity` UNIQUE-key dedup ledger. PRs worker2 #110 / dbchanges2 #427. (ajean)
+
+## Related docs
+
+- [ClickUp Project & Opportunity Multi-List Routing](./clickup-project-routing.md) — same hub spaces, same webhook pipeline, same structural identification.
+- [Worker (worker2) Architecture](../architecture.md) — always-HTTP-200, commit-before-SQS worker contract.

package/knowledge/INDEX.md

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