toga-ai 1.0.220 → 1.0.221

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

@@ -5,6 +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 |
 | [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 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 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 |
@@ -15,7 +16,9 @@
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.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 |
 | [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 |
+| [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |
 | [Team Sprint Management & Reporting](features/team-sprint-management.md) | `_Worker_Team_Sprint` (file `Worker/Team/Sprint.php`) is the engine behind TOGA's internal **development-sprint process and reporting**. | worker2/Worker/Team/Sprint.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
 | [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php |
 | [WJE Freshservice Sync (worker2)](features/wje-freshservice-sync.md) | WJE ("WJE IT", helpdesk `wje.freshservice.com`) is a **Freshservice**-based help-desk client whose tickets, contacts, assets, groups, categories, and canned res | worker2/Worker/Wje.php, _underscore/Component/Api/Wje/Wje.php, _underscore/Model/Wje/Ticket.php, _underscore/Model/Wje/TicketNote.php, _underscore/Model/Wje/Contact.php, _underscore/Model/Wje/Unit.php, _underscore/Model/Wje/TicketTeam.php, _underscore/Model/Wje/TicketCategory.php, _underscore/Model/Wje/AssetType.php, _underscore/Model/Wje/PredefinedReply.php, library/app/api/wje.php, worker/crons/toga2/wje/import_supporting_records.php, worker/crons/toga2/wje/sync_togasupply_wje.php, worker/crons/notifications/reports/wje/wje_common.php, library/app/systemmonitor/wje.php, dbchanges2/Client_Wje/2024-10-04 - WjeOnboarding.sql |
+| [Ticket → ClickUp Pseudocode Planning (Talos-grounded)](workflows/ticket-to-pseudocode-planning.md) | A repeatable procedure for turning a ClickUp ticket into a reviewed, formatted implementation plan posted back to the ticket's `📝 Pseudocode` custom field. | test/@dave/clickup_md2delta.js |

package/knowledge/2.0/apps/worker2/features/clickup-richtext-api.md

@@ -0,0 +1,133 @@
+---
+title: ClickUp Rich-Text Custom Fields via Quill Delta (API)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: [dfranks]
+files:
+  - test/@dave/clickup_md2delta.js
+  - .claude/skills/plan-ticket/scripts/clickup.js
+related:
+  - ./netsuite-opportunity-sync.md
+  - ./clickup-project-routing.md
+  - ../workflows/ticket-to-pseudocode-planning.md
+  - ./talos-meeting-notes-integration.md
+---
+
+## Summary
+
+ClickUp custom text fields (type `text` and long-text) support rich formatting only through a
+**Quill Delta** written to the undocumented `value_richtext` key on the Set-Custom-Field-Value
+endpoint. Markdown or HTML written to the documented `value` key renders as literal characters.
+A companion `value` (plain-text fallback) must accompany every richtext write.
+
+## How it works
+
+### Endpoint
+
+`POST https://api.clickup.com/api/v2/task/<taskId>/field/<fieldId>?custom_task_ids=true&team_id=<CLICKUP_TEAM_ID>`
+
+Header: `Authorization: <CLICKUP_API_KEY>` — no `Bearer` prefix.
+
+### Request body
+
+```json
+{
+  "value": "<plain-text fallback>",
+  "value_richtext": "{\"ops\":[...]}"
+}
+```
+
+`value_richtext` must be the Delta JSON **serialized to a string** — not a nested JSON object.
+The outer JSON body is a normal JSON object; only `value_richtext`'s value is a JSON-encoded string.
+
+### Quill Delta format rules
+
+A Delta is `{"ops":[...]}`. Each op is `{"insert": "...", "attributes": {...}}`.
+
+**Block-level formats** attach to the `\n` op that **terminates the block**; they apply back
+to the previous newline. Block attribute keys:
+
+| Format | Key | Values |
+|--------|-----|--------|
+| Heading | `header` | `1`, `2`, `3` |
+| Bullet list | `list` | `"bullet"` |
+| Ordered list | `list` | `"ordered"` |
+| List indent | `indent` | `1`, `2`, … |
+| Code block | `code-block` | `true` |
+| Blockquote | `blockquote` | `true` |
+
+**Inline formats** wrap the text `insert` directly:
+
+| Format | Key | Value |
+|--------|-----|-------|
+| Bold | `bold` | `true` |
+| Italic | `italic` | `true` |
+| Inline code | `code` | `true` |
+| Link | `link` | `"https://..."` |
+
+**No native table op.** Convert markdown tables to bullet lists. Convert horizontal rules
+(`---`) to a blank line — there is no `hr` op in ClickUp's Delta renderer.
+
+Every Delta must end with a bare `{"insert": "\n"}` op.
+
+### Minimal example — a heading followed by a bullet list
+
+```json
+{
+  "ops": [
+    { "insert": "Overview" },
+    { "insert": "\n", "attributes": { "header": 1 } },
+    { "insert": "First item" },
+    { "insert": "\n", "attributes": { "list": "bullet" } },
+    { "insert": "Second item" },
+    { "insert": "\n", "attributes": { "list": "bullet" } },
+    { "insert": "\n" }
+  ]
+}
+```
+
+## Reusable converter
+
+`test/@dave/clickup_md2delta.js` — converts a Markdown file to a Quill Delta and posts both
+`value` and `value_richtext` to a ClickUp custom field.
+
+```sh
+node clickup_md2delta.js <md-path> <TASK_ID> <FIELD_UUID> [--dry]
+```
+
+`--dry` prints the computed Delta without posting. Reads `CLICKUP_API_KEY` and
+`CLICKUP_TEAM_ID` from the environment.
+
+The converter was used to push a full implementation plan into the `📝 Pseudocode` custom
+field (`ad0e4fc8-ff03-4e5f-a187-7d2cd6d0bc65`) on ticket TRUE-79868. The same mechanism is
+reused by the `clickup.js` helper in the local `plan-ticket` skill — see the
+[ticket-to-pseudocode planning workflow](../workflows/ticket-to-pseudocode-planning.md).
+
+## API documentation status
+
+ClickUp's official v2 API docs document only a plain-string `value` for text fields and list
+markdown support as an unfulfilled feature request. The `value_richtext` write path is
+**undocumented but empirically verified** (2026-06-26). It works for both `text` and
+long-text field types.
+
+## Tooling gotcha — PowerShell ConvertTo-Json
+
+PowerShell 5.1 `ConvertTo-Json` pathologically inflates nested strings. A 21 KB
+`value_richtext` string was inflated ~190x (to ~3.8 MB) due to recursive escape-doubling
+of the inner JSON. Avoid `ConvertTo-Json` for ClickUp richtext payloads. Use one of:
+
+- **Node `fetch`** — serialize the body with `JSON.stringify()` directly.
+- **PowerShell + file** — write the JSON body to a UTF-8 file, then pass it to
+  `Invoke-RestMethod -InFile <path> -ContentType "application/json"`.
+- **`System.Web.Script.Serialization.JavaScriptSerializer`** — correctly serializes a
+  pre-built string without re-escaping it.
+
+## Change history
+
+- 2026-06-26 — Cross-linked to the Talos meeting-notes integration and the ticket-to-pseudocode planning workflow; noted the `plan-ticket` skill reuses this richtext write path (dfranks)
+- 2026-06-26 — Initial doc: Quill Delta richtext write path verified; converter tool documented; PowerShell inflation gotcha added (dfranks)

package/knowledge/2.0/apps/worker2/features/talos-meeting-notes-integration.md

@@ -0,0 +1,97 @@
+---
+title: Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: [dfranks]
+files:
+  - .claude/skills/plan-ticket/scripts/talos.js
+related:
+  - ../../talos/architecture.md
+  - ./clickup-richtext-api.md
+  - ../workflows/ticket-to-pseudocode-planning.md
+---
+
+## Summary
+
+How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus
+programmatically. Talos itself (the LangGraph Agent Protocol server) is documented under
+[`2.0/apps/talos/`](../../talos/architecture.md); this doc is the **consumer side** — the
+endpoints, assistant, and auth-refresh flow a worker2-side dev script needs to ground its
+output in meeting notes.
+
+**Key distinction:** the `[talos]` key in worker2 config only reaches the **stateless**
+`/api/ai/generate` and `/api/ai/chat` endpoints, which have **no meeting-notes access**.
+Meeting-notes access comes only from **assistants wired to knowledge bases**, reached through
+the Agent Protocol `/threads` + `/threads/{id}/runs/wait` surface with a **user Bearer JWT**.
+
+## How it works
+
+### Server
+
+- Agent Protocol (LangGraph) server: `https://api.togaiq.com`
+- Web app (login / token source): `https://talos.togaiq.com`
+
+### Assistants
+
+Meeting-notes / knowledge-base queries go to a knowledge-wired **assistant**, not the
+stateless generate endpoint.
+
+| Assistant | ID | Use |
+|-----------|-----|-----|
+| **DevCore** | `a5b1833d-b47c-5cb3-8cda-963f1cc74a33` | dev + meeting notes (plan-and-execute agent) |
+| Talos One | — | general |
+| Talos Sales | — | sales |
+| Talos HR | — | HR |
+
+### Querying DevCore
+
+1. `POST /threads` → returns a thread id.
+2. `POST /threads/{id}/runs/wait` with the assistant id and the user message.
+3. DevCore is a **plan-and-execute** agent that **interrupts for plan approval**
+   (agent-inbox schema): the response carries `__interrupt__` with `action: plan_approval`.
+4. **Resume** the run with `command: { resume: [ { "type": "accept", "args": null } ] }`.
+5. The **final answer** is the last item in `messages[]` whose `type` is `"ai"`.
+
+### Authentication & token auto-refresh (verified)
+
+JWTs are issued by `api-writer.togahub.com` with audience `talos.togaiq.com`. This is the
+standard **TOGA 2.0 `/v2/auth/*` flow** (mirrors `api2/Component/Api/V2/V2.php`).
+
+- **Access token** — 1 hour TTL.
+- **Refresh token** — 30 day TTL and **rolls forward** on each refresh (a new refresh token
+  may be returned and must replace the stored one).
+- **Refresh call:**
+  `POST https://api-writer.togahub.com/v2/auth/refresh?transactionId=<unique-uuid>`
+  Header: `Authorization: Bearer <refresh token>`
+  Response: `{ isSuccess, data: { tokens: { access [, refresh] } } }`
+
+**Gotchas (both verified empirically 2026-06-26):**
+
+- The **`/v2` path prefix is REQUIRED** — omitting it returns error **EV-2 "invalid version"**.
+- `transactionId` must be **globally unique per call** — reusing one returns error **EV-5**.
+
+The browser obtains the initial token pair via the `talos.togaiq.com` login. A developer can
+copy `accessToken` + `refreshToken` out of the browser session to seed a local tool, after
+which the tool refreshes on its own.
+
+## Credential storage (location only)
+
+The consumer tool stores its token pair at **`~/.talos/credentials.json`** (user home,
+**outside any repo**). Never commit, echo, or paste the token values anywhere — they are
+secrets. Document only this location.
+
+## Consumer helper
+
+`.claude/skills/plan-ticket/scripts/talos.js` — performs the auth refresh and runs a DevCore
+query (create thread → run → accept plan interrupt → extract final `ai` message). It is part
+of the **local** `plan-ticket` skill, not the team repo; its source is intentionally not
+mirrored into the knowledge base.
+
+## Change history
+
+- 2026-06-26 — Initial doc: consumer-side Talos meeting-notes access via DevCore assistant + the `/v2/auth/refresh` token-rotation flow; stateless `[talos]` config vs. assistant distinction; EV-2/EV-5 gotchas; credential location `~/.talos/credentials.json` (dfranks)

package/knowledge/2.0/apps/worker2/workflows/ticket-to-pseudocode-planning.md

@@ -0,0 +1,60 @@
+---
+title: Ticket → ClickUp Pseudocode Planning (Talos-grounded)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-06-26
+owners: [dfranks]
+files:
+  - test/@dave/clickup_md2delta.js
+related:
+  - ../features/clickup-richtext-api.md
+  - ../features/talos-meeting-notes-integration.md
+---
+
+## Summary
+
+A repeatable procedure for turning a ClickUp ticket into a reviewed, formatted implementation
+plan posted back to the ticket's `📝 Pseudocode` custom field. It spans three systems —
+ClickUp (read ticket / write field), the codebase (investigation), and Talos DevCore
+(meeting-notes grounding) — so it is a workflow, not a single feature.
+
+It is implemented as a **local Claude skill** (`.claude/skills/plan-ticket/`) that is **not**
+in the team repo. This doc records the *shape of the procedure* and the durable integration
+mechanics; it does not duplicate the skill source. The two underlying integrations have their
+own feature docs:
+
+- [ClickUp rich-text custom fields via Quill Delta](../features/clickup-richtext-api.md) — how the plan reaches the `📝 Pseudocode` field.
+- [Talos meeting-notes integration](../features/talos-meeting-notes-integration.md) — how the plan is grounded in meeting notes.
+
+## Steps
+
+1. **Fetch the ticket** by id from ClickUp (`custom_task_ids=true`, `team_id` from env).
+2. **Investigate the codebase FIRST** — establish what already exists before asking Talos, so
+   the Talos query is code-informed rather than speculative.
+3. **Query Talos DevCore** (assistant `a5b1833d-b47c-5cb3-8cda-963f1cc74a33`) for
+   meeting-notes context, passing the codebase findings as grounding. Accept the
+   plan-approval interrupt to get the final answer.
+4. **Synthesize a ≤150-line phased plan**, saved to `test/@dave/approach/<TICKET>.md`.
+5. **Preview & approval gate** — show the plan; iterate until the developer approves.
+6. **Push to the ticket's `📝 Pseudocode` field** as a Quill Delta via the richtext write
+   path. The push is **overwrite-guarded**: it refuses to clobber an already-populated field
+   unless run with `--force`.
+
+## Plan document format
+
+`test/@dave/approach/<TICKET>.md` (see also the team convention to store approach plans
+under `test/@dave/approach/`):
+
+- Title heading.
+- Bold header line: **Repos / Framework / Client / Sibling**.
+- Sections, in order: **Summary** · **Meeting-notes context** · **What already exists** ·
+  **Architecture decision** · **Phases** (each with file paths + pseudocode) · **Testing** ·
+  **Risks** · **Owners / open questions** · **Key files**.
+
+## Change history
+
+- 2026-06-26 — Initial doc: ticket→pseudocode planning procedure (ClickUp read → codebase investigation → Talos DevCore grounding → phased plan → approval gate → guarded richtext push); records the shape, not the local skill source (dfranks)

package/knowledge/INDEX.md

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