toga-ai 1.0.192 → 1.0.193

package/knowledge/2.0/apps/_underscore/features/email-template-sending.md

@@ -6,13 +6,14 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-18
-owners: ["jcardinal", "bala"]
+updated: 2026-06-24
+owners: ["jcardinal", "bala", "mhammontree"]
 files:
   - _underscore/Model/Client/EmailTemplate.php
   - _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php
   - _underscore/Email.php
-related: []
+related:
+  - ../../worker2/features/notification-email.md
 ---
 
 ## Summary
@@ -33,6 +34,17 @@ sends via `_Email`. The only client-specific input the send actually needs is th
     non-API entry point. Caller passes the client identifier directly; no `$api` object.
   - **`dispatch(string $clientIdentifier, ...): bool`** (private) — the shared body both
     entry points call. Holds all the real logic.
+  - **`renderWrappedBody(string $subject, string $body): ?string`** — the **branded-wrapper**
+    path (distinct from the send-by-uuid path above). Loads the reserved wrapper row
+    (`uuid = WRAPPER_UUID`) and injects the subject/body into its `{subject}`/`{body}`
+    placeholders via `strtr` (simultaneous, so a `{body}` literal in the subject can't be
+    re-expanded). Returns `null` if there is no active wrapper row. Does **not** send — the caller
+    feeds the result to `_Email`.
+- **`const WRAPPER_UUID = '11111111-1111-4111-8111-111111111111'`** — the reserved uuid of the
+  per-client branded "wrapper" template row. The model lookup and the dbchanges2 seed migration
+  must use this same literal. The row is seeded by dbchanges2 (`Client/` blank-client baseline so
+  every new client inherits it, plus per-client backfills). Its body is the branded HTML shell
+  holding `{subject}`/`{body}` placeholders.
 - `_Model_Client_EmailTemplateOutgoingEmailAddress` — per-template stored TO/CC/BCC
   addresses (`toCcBcc` enum), merged into the caller-supplied recipients.
 - `_underscore/Email.php` — `_Email` requires a non-empty `clientIdentifier` (throws
@@ -91,6 +103,11 @@ can keep using `sendEmail($api, ...)`.
 
 ## Change history
 
+- 2026-06-24 — Added the **branded-wrapper** path: `WRAPPER_UUID` + `renderWrappedBody()` load a
+  reserved per-client `EmailTemplates` row and inject `{subject}`/`{body}`. Consumed by the new
+  worker2 `_Worker_Notification_Email::Send` for internal/notification mail; the wrapper row is
+  seeded across clients by dbchanges2. See
+  [`worker2/notification-email.md`](../../worker2/features/notification-email.md). (mhammontree)
 - 2026-06-18 — Hardened against silent failure: `dispatch()` throws on an inactive template
   (was `return false`) and `_Email::send()` throws + logs `isSuccess`/`error` when
   `PHPMailer::Send()` fails (was swallowed with no return/throw/log). Affects all clients;

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

@@ -11,6 +11,7 @@
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [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 |
 | [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 |

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-06-18
-owners: [jcardinal, dfranks]
+owners: [jcardinal, dfranks, mhammontree]
 files:
   - worker2/Worker/
   - worker2/Controller/Index.php
@@ -34,7 +34,10 @@ Lambda code changes are needed** — you just create the PHP file.
    - Method: `MethodName`
    - Example: `Client/Acme/ImportData` → `Worker/Client/Acme.php`, `_Worker_Client_Acme::ImportData`.
 2. **Parameters** — name + PHP type (`string`/`int`/`bool`/`array`/`float`); optional ones
-   get PHP defaults. The framework spreads the `parameters` JSON as positional arguments.
+   get PHP defaults. The framework spreads the **string-keyed** `parameters` array into the method
+   (`$class::$method(...$parameters)`), which PHP binds as **named arguments** — so each method
+   parameter name *is* the queue's parameter contract. Do **not** collapse a multi-param action
+   into a single `array` argument: named-argument dispatch then has no key to bind to and breaks.
 3. **Return** — return `string`; `json_encode()` structured data.
 4. **`initialize()`** — optional `public static function initialize()` the framework calls
    automatically before any method in the class (register DB connections / shared setup).
@@ -160,6 +163,9 @@ be reattempted.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-06-24 — Clarified that the dispatcher spreads the string-keyed `parameters` as PHP **named
+  arguments** (`$class::$method(...$parameters)`), so parameter names are the queue contract — do
+  not collapse a multi-param action into a single `array` arg. (mhammontree)
 - 2026-06-18 — Documented worker-action **exception/retry semantics**: dispatcher catches `Throwable` →
   `isSuccess=0`+`failureReason`, **always HTTP 200, no DLQ, no auto-retry**; throwing surfaces a failure
   but does not re-run — retry via `_Worker::runTask` re-enqueue (attempt-counter), in-process loop, or

package/knowledge/2.0/apps/worker2/features/notification-email.md

@@ -0,0 +1,144 @@
+---
+title: DB-Driven Notification (Internal) Email
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-24
+owners: ["mhammontree"]
+files:
+  - 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
+related:
+  - ../../_underscore/features/email-template-sending.md
+  - ./creating-worker-actions.md
+---
+
+## Summary
+
+Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated,
+not client-facing transactional mail) are sent through one worker action,
+`_Worker_Notification_Email::Send(...)`, which wraps a plain subject/body in the client's
+**DB-stored branded shell** before sending via `_Email`. The branded shell used to be a
+hardcoded PHP class (`_Email_Template`, now **deleted**); it now lives in the client DB as a
+reserved `EmailTemplates` row so the branding can change without a code deploy. This is a
+**shared/core 2.0 mechanism** — every client inherits the wrapper row from the dbchanges2
+`Client/` baseline; it is not specific to any one tenant (`True` is only the pilot tenant the
+migration backfilled first).
+
+## Key files / entry points
+
+- `worker2/Worker/Notification/Email.php` — `abstract _Worker_Notification_Email`. One method:
+  `Send(string $clientIdentifier, string $subject, string $body, string|array $to=[],
+  string|array $cc=[], string|array $bcc=[], string $fromEmail='donotreply@togatech.com',
+  string $fromName='TOGA Technology')`. The entry point. Self-registers the client DB (no
+  `initialize()` — see below), wraps the body, and sends.
+- `_underscore/Model/Client/EmailTemplate.php` — supplies `WRAPPER_UUID` and
+  `renderWrappedBody($subject, $body)`. Documented in
+  [`email-template-sending.md`](../../_underscore/features/email-template-sending.md).
+- `dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql` — blank-client baseline; seeds the
+  wrapper row so **every new client** inherits it.
+- `dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql` — backfills the pilot tenant.
+
+## How it works
+
+1. **Validate the identifier.** `$clientIdentifier` is interpolated into a schema name
+   (`Client_<id>`), so `Send()` first rejects anything that isn't `^[A-Za-z0-9]+$` (matches
+   `Core.Clients.clientIdentifier`, e.g. `True`, `CompassCanada`). This is the injection guard —
+   keep it.
+2. **Register the client DB under the `DB_CLIENT` alias** via
+   `_Database::register('Client_'.$id, _Config::databaseClient(...), …, _underscore::DB_CLIENT)`.
+   This points the process-global `Client` alias at the concrete `Client_<id>` schema so the
+   `DATABASE = DB_CLIENT` model resolves to the right tenant. Only the `Client` alias is
+   registered — **not** `DB_CLIENT_LOGS` (see gotchas).
+3. **Wrap the body.** `_Model_Client_EmailTemplate::renderWrappedBody($subject, $body)` loads the
+   active wrapper row (uuid = `WRAPPER_UUID`) and `strtr()`-substitutes `{subject}`/`{body}`.
+   Returns `null` if there is no active wrapper row.
+4. **Graceful degrade.** If `renderWrappedBody` returns `null`, `Send()` `error_log()`s the
+   missing wrapper (with the uuid + client) and sends the **raw, unwrapped** body. These are
+   internal alerts — delivering unbranded mail beats dropping the alert. (Revisit if this path is
+   ever reused for client-facing email, where branding should be guaranteed.)
+5. **Send** via a plain `_Email`: `setClientIdentifier`, `addTo/Cc/Bcc`, `setFrom`,
+   `setSubject`, `setBody($wrapped ?? $raw)`, `send()`.
+
+### Enqueuing it
+
+`_Worker::runTask('Notification/Email/Send', ['clientIdentifier'=>…, 'subject'=>…, 'body'=>…, …])`
+inserts a WorkerJob. The dispatcher (`worker2/Controller/Index.php`) resolves
+`'Notification/Email/Send'` → `_Worker_Notification_Email::Send`, then spreads the **string-keyed**
+parameters array as PHP **named arguments**. So the method's named parameters *are* the queue's
+parameter contract — see [`creating-worker-actions.md`](./creating-worker-actions.md).
+
+**Proven caller:** `_Worker_Team_GitHub::Merge()` (`worker2/Worker/Team/Github.php`) enqueues
+`Notification/Email/Send` on a git merge conflict, so merge-conflict alerts now go out branded.
+
+## The wrapper row (data model)
+
+A single reserved `EmailTemplates` row per client DB:
+
+- **uuid** = `_Model_Client_EmailTemplate::WRAPPER_UUID` (`11111111-1111-4111-8111-111111111111`).
+  This literal is the contract between the model lookup and the seed SQL — both must use it.
+- **body** holds the full branded HTML with `{subject}` and `{body}` placeholders.
+- Seeded once in `dbchanges2/Client/…` (baseline, so new clients inherit it) and backfilled per
+  existing client (`dbchanges2/Client_True/…` did the pilot). In the seed SQL the CSS font names
+  are left **unquoted** so the `INSERT` has no single quotes to escape.
+
+## Branded header — Outlook bulletproofing (load-bearing recipe)
+
+The wrapper's header must render the TOGA line-art logo
+(`TOGA-TECHNOLOGY-Header-Logo-Vector.png`, sized **exactly 600×69** = the header box) in
+**both** classic Outlook and new Outlook/Gmail/Apple, **without** the logo rendering twice. The
+working recipe — verified in classic + new Outlook:
+
+- **Classic Outlook:** VML — `<v:rect>` with `<v:fill type="frame" src=…>` and a `<v:textbox>`
+  holding the title.
+- **New Outlook / Gmail / Apple Mail:** the HTML `background=` **attribute** on the cell.
+- **No CSS `background-image`** on the header — only `background-color`. New Outlook would
+  otherwise render the CSS image *and* the `background=` attribute = the double-render.
+- **Horizontal inset belongs on the title `<div>`** (`padding: 22px 90px`), **not** on the `<td>`.
+  Putting padding on the `<td>` squeezes the VML/background image inward in classic Outlook so it
+  no longer fills the full header width.
+- The **footer** logo is a normal `<img>` (no VML needed).
+
+## Gotchas / known issues
+
+- **No `initialize()` on this action.** `_Worker_Notification_Email` does not define
+  `initialize()`, so the dispatcher never calls one — `Send()` registers its own client DB inline.
+  (The dispatcher only calls `initialize()` when the class defines it.)
+- **A `DATABASE = DB_CLIENT` model resolves only after the `Client` alias is registered** to the
+  concrete `Client_<x>` schema. `renderWrappedBody()` will load the wrong (or no) tenant if you
+  call it before `_Database::register(..., _underscore::DB_CLIENT)`. Authoritative pattern:
+  `_Worker_Ai_Bdr_Netsuite::initialize()`.
+- **Do not register `DB_CLIENT_LOGS` for this path.** `_Email` logs to CloudWatch, not a Logs DB,
+  so the notification path never needs it — and `[databaseLogs]` only exists in `production.ini`,
+  so registering it in dev/beta throws.
+- **Debug mode redirects, doesn't suppress.** When `_Email::isDebugMode()` is on, `_Email::send()`
+  redirects the recipient to `[_underscore] send_debug_emails_to` and prepends a
+  "DEVELOPMENT MODE - Intended Recipients" banner — the email still sends.
+- **Missing wrapper row → unbranded send, logged.** If a client has no active wrapper row the alert
+  still goes out (raw body) and an `error_log` line records the missing uuid. Branding is *not*
+  guaranteed on this path by design (internal mail). Don't rely on it for client-facing email.
+- **`{subject}`/`{body}` substitution is `strtr`, not sequential `str_replace`.** All placeholders
+  are replaced simultaneously, so a `{body}` literal inside the subject can't be re-expanded.
+
+## Change history
+- 2026-06-24 — Built the DB-driven notification-email mechanism (TRUE-79240): new
+  `_Worker_Notification_Email::Send` entry point; branded shell moved out of code (deleted
+  `_underscore/Email/Template.php`, which also carried the 1.0 double-render bug) into a reserved
+  per-client `EmailTemplates` wrapper row seeded by dbchanges2 (`Client/` baseline +
+  `Client_True/` backfill). Missing wrapper degrades to an unbranded send (logged). Documented the
+  Outlook-bulletproof header recipe (VML + `background=` attribute, no CSS background-image, inset
+  on the title `<div>`). Merge-conflict alerts (`_Worker_Team_GitHub::Merge`) now use this path.
+  (mhammontree)
+
+## Related docs
+- [`2.0/apps/_underscore/features/email-template-sending.md`](../../_underscore/features/email-template-sending.md)
+  — the `_Model_Client_EmailTemplate` model, including `WRAPPER_UUID` + `renderWrappedBody()`.
+- [`creating-worker-actions.md`](./creating-worker-actions.md) — worker action dispatch +
+  named-argument parameter contract.
+- `1.0/apps/library/features/email-templates.md` — the **1.0** `App_Email_Template` (a different
+  framework/mechanism; cross-link only, do not conflate).

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)_ — 12 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 13 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 14 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 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.192",
+  "version": "1.0.193",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",