toga-ai 1.0.882 → 1.0.883

package/knowledge/1.0/apps/tools/INDEX.md

@@ -9,6 +9,7 @@
 | [Compass User & Persona Admin (tools /compass/users, /compass/personas)](features/compass-user-persona-admin.md) | Two pages in the Tools `developers` nav folder that let staff do, in a browser, the Compass requests that used to mean "email a developer, who writes a `dbchang |
 | [Design Demo Admin](features/design-demo-admin.md) | SSO-gated Tools admin at `/design` that publishes self-contained "Claude Design" HTML exports as versioned demos into the `forward` repo over the GitHub REST AP |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | Tools "Developers" folder — the Generate UUID and Generate Password tools (reference example of the one-tool-per-`mvc/<route>/get.php` pattern); open for the ge |
+| [/emails Email Queue Review (Tools → 2.0 Logs_<Client>.Email)](features/email-queue-review.md) | Staff page to browse any 2.0 client's `Logs_<Client>.Email` queue and release/reject `HELD` review-hold emails. |
 | [/errors Curation Console (Tools → shared Core Logs DB)](features/errors-curation-console.md) | Internal-only 1.0 Tools triage/curation screen (`/errors`) for the 2.0 Issue/Event error pipeline, reading the shared Core Logs DB via `db_toga2logs`; curates, |
 | [GitHub Audit (monthly code-churn report)](features/github-audit.md) | Internal monthly code-churn report at `/developers/github-audit` (lines added/removed across every `agilantsolutions` repo for one month); open for the two-phas |
 | [Legacy Email Notifier (tools /email-migration/notify)](features/legacy-email-notifier.md) | SSO-gated admin tool at `/email-migration/notify` that emails employees a digest of mail still hitting their legacy domains (asks senders to switch to `@togatec |

package/knowledge/1.0/apps/tools/architecture.md

@@ -79,9 +79,17 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
 
 ## Gotchas
 
+- **Bare `<header>` violated again (2026-09-23, /emails)** — use a `<div>` with a page class; see Critical rules.
+- **The app-wide input rule outranks class selectors.** `style.css` ~line 769 styles inputs with five chained `:not()`; that specificity beats a page's class selector. A page restyling its inputs must repeat the same `:not()` chain under its page scope.
+- **`.app-content` caps width at 960px** unless the page root has `.tool--wide`.
+- **`.btn-secondary` and `.btn-secondary-outline` are RED (danger).** There is no neutral button class; do not use them for non-destructive actions.
+- **CSRF is not a token.** `App_Page::validateCrossSiteRequestForgery` checks Origin/Referer only; POST handlers rely on it.
 - **⚠ `tools` runs PHP 8, not 7.2 — check the vhost, not the framework label.** Despite being a 1.0 `App_` app, its vhost lives in the PHP 8 Apache (`DocumentRoot "C:/WWW/tools"`), and `App_Compass::tenantKey(mixed $key)` uses the `mixed` type hint (PHP 8.0+). The trap: `mixed` **passes** `php -l` on 7.2 (parsed as a class name) and only fatals at runtime — "Argument 1 passed to f() must be an instance of mixed, string given". So linting `tools` on 7.2 fails in the dangerous direction: it accepts code that would die.
 - **Plaintext secrets were publicly web-readable (fixed 2026-07-24; rotation still owed).** `config.*.ini` (incl. `config.prod.ini`) holds plaintext production secrets (RDS master password, SMTP, Payeezy, NetSuite). The front controller routed through `index.php` on a `RewriteCond !-f` rule **only**, which is not access control — a direct `GET /config.production.ini` served the file **verbatim**. Fixed 2026-07-24 by adding `<FilesMatch>` `Require all denied` blocks (sensitive extensions incl. `.ini`, and any `config.*`) — see the [1.0 back-end security standard](../../standards/backend-php.md). **Action still owed:** rotate every secret in `config.production.ini` — the file was reachable, so treat all of it as compromised. (Location only — no values recorded here.)
 - **Hardcoded GitHub Personal Access Token committed in plaintext (rotation owed).** `.ebextensions/020_setup_git_libraries.config` contains a GitHub PAT in plaintext, committed to the repo and therefore exposed in git history. **Action owed:** rotate the token and move it to an EB environment property (read via `getenv()`/`$_SERVER`/`$_ENV` per the deploy workflow's clear_env gotcha); a rotation does not un-expose git history. (Location only — no value recorded here.)
 - **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.
 - **~~Unproxied third-party polling from the browser~~ (resolved 2026-08-18).** The monitor column used to pull ~250 KB from OneUptime cross-origin every poll (per open tab) and hardcode the status-page ID in the HTML. It is now served by a same-origin server-side proxy `/v2/monitors/status/` (`App_Clickup_Monitors`) that fetches, reduces to ~1 KB and caches ~5s (APCu), with the status-page ID in config — one upstream fetch shared across all tabs, no cross-origin dependency. See `features/oneuptime-monitor-status-panel.md`. **Framework gotcha found building it (prod incident CV-2):** never call `curl_close()` in App_ code — it is deprecated in PHP 8.5 and the strict error handler promotes that `E_DEPRECATED` to a fatal (500). It is a no-op since PHP 8.0; drop it (or `unset($ch)`).
 - **Framework-level Sentry error reporting is an open gap.** Prod printed "Sentry is not installed" because `sentry/sentry` was missing from `composer.json` (added `^4.10`; sibling apps use `^4.10`/`^4.19`). But even with Sentry in `vendor/`, the 1.0 framework does **not** auto-require `vendor/autoload.php` (the `App_Talos_S3` pattern `require_once`s it explicitly), so framework-level Sentry reporting for Tools still does not load. Any code path that needs a composer package must `require_once` the autoloader itself.
+
+## Change history
+- 2026-09-23 — Added gotchas from the /emails build: input :not chain, 960px cap/.tool--wide, red btn-secondary, Origin/Referer CSRF. (jcardinal)

package/knowledge/1.0/apps/tools/features/email-queue-review.md

@@ -0,0 +1,54 @@
+---
+title: /emails Email Queue Review (Tools → 2.0 Logs_<Client>.Email)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-09-23
+owners: ["jcardinal"]
+files:
+  - tools/_/app/emails.php
+  - tools/mvc/emails/get.php
+  - tools/mvc/emails/post.php
+  - tools/_/app/nav.php
+  - tools/assets/css/style.css
+related:
+  - ../architecture.md
+  - ../../../../2.0/apps/_underscore/features/email-send-pipeline.md
+  - ../../../../2.0/apps/_underscore/features/email-template-sending.md
+---
+
+## Summary
+
+Staff page to browse any 2.0 client's `Logs_<Client>.Email` queue and release/reject `HELD`
+review-hold emails. Nav: Developers group, Development Team persona only.
+
+## Key files / entry points
+
+- `tools/_/app/emails.php` — `App_Emails`: client list, queue queries, actions.
+- `tools/mvc/emails/get.php` / `post.php` — page + actions.
+- `tools/assets/css/style.css` — `.tool--emails` block.
+
+## How it works
+
+1. Client list from Core (`db_toga2core`). Queue queries go over `db_toga2logs` against one
+   `Logs_<Client>` db named from `Core.Clients.logDatabaseId`, checked against
+   `^Logs_[A-Za-z0-9]+$`. Never joins Core with Logs.
+2. Status tabs with counts, search, pagination, split-pane list/detail.
+3. Actions:
+   - **Approve** — guarded `UPDATE ... WHERE status='HELD'`, requires `affectedRows === 1`; sets
+     `PENDING`, `dtReviewed`, `reviewedBy` = staff email.
+   - **Reject** — `HELD` → `CANCELLED`, same guard.
+   - **Send copy** — new `PENDING` row + attachments via `INSERT ... SELECT`, PHP v4 uuid per row.
+4. Deep link `/emails?client=&emailId=` is the target of `[_underscore] email_review_url`.
+
+## Gotchas / known issues
+
+- Preview is an `<iframe sandbox="" srcdoc>` — the **only** XSS barrier for stored email HTML.
+  Never add `allow-scripts`.
+- CSRF is `App_Page` Origin/Referer check, not a token (see architecture).
+
+## Change history
+- 2026-09-23 — Created: browse queue, Approve/Reject held emails, Send copy. (jcardinal)

package/knowledge/2.0/apps/_underscore/features/email-send-pipeline.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
-owners: ["bala", "tcox", "dfranks", "apeterson"]
+updated: 2026-09-23
+owners: ["bala", "tcox", "dfranks", "apeterson", "jcardinal"]
 files:
   - _underscore/Email.php
   - _underscore/String.php
@@ -39,6 +39,9 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
   unless both `setClientIdentifier(...)` and a From address (`fromEmailAddress`) are set. The
   `Logs_[Client]` databases live on a separate cluster (`production-logs-*`), so `send()` points
   `DB_CLIENT_LOGS` at the correct `Logs_[Client]` schema before inserting.
+- Setters (2026-09-23): `setIsHeld(true)` writes the row as `HELD` instead of `PENDING`;
+  `setEmailTemplateId()` / `setReviewOfEmailId()` fill the matching columns. `send()` returns the
+  **int `Logs_<Client>.Email` id**.
 - `worker2/Worker/Infrastructure/Email/Send.php` — `Run()` fetches up to 100 `PENDING` rows for
   the client, and `sendEmail()` transmits each via SES SMTP. Constants: `STATUS_PENDING`,
   `STATUS_SENT`, `STATUS_FAILED`, `MAX_RETRIES`.
@@ -54,6 +57,17 @@ SMTP** using PHPMailer, then flips each row to `SENT` or `FAILED`. So a 2.0 emai
 4. On success the row flips to `SENT`; on failure `retryCount` is incremented and the row is
    retried on subsequent runs until `MAX_RETRIES` (3), after which it is marked `FAILED`.
 
+### Statuses + review columns (2026-09-23)
+
+`status` enum = `PENDING` / `SENT` / `FAILED` / `HELD` / `CANCELLED`. The Send cron reads only
+`PENDING`, so `HELD` and `CANCELLED` rows are never sent (worker2 unchanged). Columns:
+`emailTemplateId` (after `dtCreated`), `reviewOfEmailId` (self FK, `ON DELETE SET NULL` — links a
+review copy to the held original), `dtReviewed` (after `dtSent`), `reviewedBy` (after
+`failureReason`). Migration: `dbchanges2/Logs_Client/2026-09-23a - EmailReview.sql` — must run
+**before** the `_underscore` deploy or every `send()` fails. Who writes `HELD`: see
+[email-template-sending.md](email-template-sending.md) *Review hold*; who releases it: Tools
+[/emails](../../../../1.0/apps/tools/features/email-queue-review.md).
+
 ### `send()` resolves the log database itself — from the clientIdentifier
 
 `send()` does not take a database name. It resolves `Logs_<Client>` by joining
@@ -76,10 +90,8 @@ derive one from the other).
 
 ## Gotchas / known issues
 
-- **It is a POLL, not an enqueue — and the docblock lies.** The comment at `_underscore/Email.php`
-  ~line 320 says `send()` "enqueues a Worker 2 job". **There is no enqueue anywhere in the file.**
-  `send()` only INSERTs a `PENDING` row (`Logs_<Client>.Email`, `status` enum
-  `PENDING`/`SENT`/`FAILED`), and `worker2/Worker/Infrastructure/Email/Send.php` loops the clients
+- **It is a POLL, not an enqueue.** (The old docblock claiming `send()` "enqueues a Worker 2 job"
+  was corrected 2026-09-23.) `send()` only INSERTs a `PENDING` (or `HELD`) row, and `worker2/Worker/Infrastructure/Email/Send.php` loops the clients
   and `SELECT`s `PENDING` rows. Two consequences: nothing is queued anywhere but the database, and
   **a `PENDING` row written from a local machine is never delivered**, because the worker polls the
   sandbox/prod clusters, not your laptop. Local "the email never arrived" is expected — verify by
@@ -190,6 +202,9 @@ derive one from the other).
     for a hotfix.
 
 ## Change history
+- 2026-09-23 — Review hold: `HELD`/`CANCELLED` statuses, `emailTemplateId`/`reviewOfEmailId`/
+  `dtReviewed`/`reviewedBy` columns, `setIsHeld`/`setEmailTemplateId`/`setReviewOfEmailId`;
+  `send()` now returns the log id; stale "enqueues" docblock fixed. (jcardinal)
 - 2026-09-17 — Three gotchas from building the NYCHH transfer-order emails, no code change: the
   `Logs_<Client>.Email` `body` column holds the **finished HTML**, so a new email is verified by
   reading the row rather than an inbox; **`send_debug_emails_to` redirects at QUEUE time only** (the

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-23
 owners: ["jcardinal", "bala", "mhammontree", "apeterson"]
 files:
   - _underscore/Model/Client/EmailTemplate.php
@@ -65,6 +65,29 @@ sends via `_Email`. The only client-specific input the send actually needs is th
 4. Replace `{key}` placeholders in subject and body from the `$args` variadic map
    (`replaceTemplateVariables`), then `send()`.
 
+### Review hold (`EmailTemplates.isReviewRequired`, 2026-09-23)
+
+The **template** decides (not `_Email`; direct `_Email` callers are never held). When
+`isReviewRequired = 1`, `dispatch()` calls `_Email::send()` twice:
+1. The real email, real recipients, `setIsHeld(true)` → row status `HELD` (Send cron skips it).
+2. A `PENDING` copy, subject prefixed `[REVIEW] `, sent **only** to the template's `toCcBcc =
+   REVIEW` addresses. Body gets a yellow banner inserted after `<body>` listing the real
+   To/CC/BCC + held id, plus an approve link if `[_underscore] email_review_url` is set (Tools
+   `/emails?client=&emailId=`). Linked via `reviewOfEmailId`.
+
+Release/reject happens in Tools [/emails](../../../../1.0/apps/tools/features/email-queue-review.md).
+Rules:
+- **Fail loud:** review on + no `REVIEW` rows → throws `Email template <uuid> requires review but
+  has no REVIEW addresses configured`; nothing is queued. Unknown `toCcBcc` → throws.
+- `REVIEW` addresses are never merged into real To/CC/BCC.
+- Out of scope by decision: no expiry of held rows, no body/PII hiding, no time-sensitive guard.
+- Rejected design: an approve button inside the email (mail scanners pre-fetch links). Runner-up:
+  single held row, preview only in Tools.
+
+Migrations: `Core/2026-09-23e - EmailTemplateReviewRecordField.sql` (RecordFields 2632 on
+Records 202), `Client/2026-09-23a - EmailTemplateReview.sql`, `Logs_Client/2026-09-23a -
+EmailReview.sql`. Deploy: SQL (Logs_Client first) → `_underscore` → tools.
+
 Both `sendEmail()` and `send()` are thin wrappers that forward to `dispatch()`, so the API
 and non-API paths run identical code — no behavioral drift between them.
 
@@ -76,10 +99,10 @@ gets a real error instead of a `true`/`false` it would otherwise ignore.
 
 ## Data model
 
-- `EmailTemplates` (client DB): `uuid`, `isActive`, `sendFromEmailAddress`, `sendFromName`,
+- `EmailTemplates` (client DB): `uuid`, `isActive`, `isReviewRequired`, `sendFromEmailAddress`, `sendFromName`,
   `priority`, `subject`, `body`.
 - `EmailTemplateOutgoingEmailAddress` (client DB): `emailTemplateId`, `emailAddress`,
-  `toCcBcc` (`TO`/`CC`/`BCC`).
+  `toCcBcc` (`TO`/`CC`/`BCC`/`REVIEW`).
 
 ## Client variations
 
@@ -207,6 +230,8 @@ worker method) in-process instead.
 
 ## Change history
 
+- 2026-09-23 — Added the review hold (`isReviewRequired` + `REVIEW` addresses → `HELD` real email +
+  `[REVIEW]` copy); fail-loud on missing REVIEW rows / unknown `toCcBcc`. (jcardinal)
 - 2026-09-17 — Added two caller-side gotchas found building the NYCHH transfer-order emails:
   `replaceTemplateVariables()` does **no escaping** (plain `str_replace`, and the Send worker forces
   HTML mode), so a stored value containing `<` arrives as live markup and every scalar must be

package/knowledge/INDEX.md

@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **test** (Test) — 16 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 3 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **store** (Store) — 3 doc(s) → [1.0/apps/store/INDEX.md](1.0/apps/store/INDEX.md)
-- **tools** (Tools) — 21 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 22 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

package/knowledge/clients/nychh/features/transfer-order-notification-emails.md

@@ -7,7 +7,7 @@ client: nychh
 type: client-feature
 status: active
 updated: 2026-09-23
-owners: ["bala", "rgirish"]
+owners: ["bala", "rgirish", "jcardinal"]
 files:
   - worker2/Worker/Client/Nychh/TransferOrderEmails.php
   - _underscore/Model/Nychh/TransferOrder.php
@@ -231,6 +231,12 @@ Cost of the split, stated so nobody is surprised later:
 
 ## Gotchas / known issues
 
+- **Submitted uses the review hold** (template "Transfer Order - Submitted", `Client_Nychh`
+  `EmailTemplates` id 3, `isReviewRequired = 1`) — first prod user; see
+  [email-template-sending.md](../../../2.0/apps/_underscore/features/email-template-sending.md).
+  Turning it on **without** a `REVIEW` address row fails `Client/Nychh/TransferOrderEmails/SendSubmitted`
+  (prod Logs.Issue Y6) — expected fail-loud. Fix: add the `REVIEW` row, retry the job.
+
 - **⚠ There is NO `try`/`catch` anywhere in this feature, by design.**
   `sendTransferOrderEmail()` returns `void` and **throws `_Exception`** when
   `_Model_Client_EmailTemplate::send()` returns `false` (which happens only when the template row is
@@ -260,6 +266,7 @@ loaded out of the dbchanges2 file so an unresolved `{placeholder}` fails a test.
 unescaped values and both detail-box defects were all found there, not in production.
 
 ## Change history
+- 2026-09-23 — Submitted template put on review hold; missing REVIEW row → job failure note. (jcardinal)
 
 - 2026-09-23 — **The greeting now addresses whoever raised the order, not the site contact.**
   `readTransferOrderForEmail()` selects `CreatedByUsers.firstName AS submittedByFirstName`, and

package/package.json

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