toga-ai 1.0.167 → 1.0.169

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
+| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -0,0 +1,107 @@
+---
+title: ACL Permission Chain (Record & Field Authorization)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["jcardinal"]
+files:
+  - api2/Component/Api/V2/V2.php
+  - _underscore/Model/Core/Page.php
+  - dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql
+  - dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql
+---
+
+## Summary
+
+Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete
+a record is decided by rows across **four linked tables**, not by code. Granting access by
+inserting only an `AclRecordPermissions` row is the single most common mistake — the permission
+silently does nothing without the rest of the chain. A complete grant requires **all four** tables,
+plus `AclFieldPermissions` for the fields to be readable/writable.
+
+## The complete chain (all four are required)
+
+```
+AclRecordPermissions   →  AclLogicGroups   →  AclLogicGroupExpressions  →  AclRecordExpressions
+  (the role × record       (operator AND/OR,     (binds a group to an          (the SQL test,
+   CRUD grant)              parent group tree)     expression)                   e.g. '1' = all)
+```
+
+1. **`AclRecordPermissions`** — the grant: `recordId`, `roleId`, `allowCreate/Read/Update/Delete`
+   (optional `appId`, `indirectRecordId`). Unique on `(appId, recordId, roleId, indirectRecordId)`.
+2. **`AclLogicGroups`** — at least one root group per permission: `aclRecordPermissionId` (FK),
+   `operator` **`enum('AND','OR') NOT NULL`** (this column is mandatory and easy to forget),
+   optional `parentAclLogicGroupId` for nested groups.
+3. **`AclLogicGroupExpressions`** — binds a logic group to a record expression: `aclLogicGroupId`
+   (FK), `aclRecordExpressionId` (FK). Unique on `(aclLogicGroupId, aclRecordExpressionId)`.
+4. **`AclRecordExpressions`** — the actual SQL test: `recordId`, `slug`, `description`,
+   `sqlExpression` (TEXT). Unique on `(recordId, slug)`. The conventional "always allow" row is
+   `slug = 'all'`, `sqlExpression = '1'`.
+
+**Field visibility — `AclFieldPermissions`.** Record-level access alone does **not** expose
+fields. Each field needs a row: `recordFieldId`, `roleId`, `isWritable` (0 = read-only, 1 =
+writable). Without it the field is omitted from responses (and rejected on write).
+
+## Where ACL rows live: Core vs. Client database
+
+`Core.Records.aclDatabase` decides which database holds the ACL rows for that record:
+
+- **`aclDatabase = 'CORE'`** → ACL rows live in the **Core** database.
+- **`aclDatabase = 'CLIENT'`** → ACL rows live in **each client's own database**. A migration
+  granting access therefore goes in `dbchanges2/Client/` (or a specific `Client_<Name>/`) so it
+  runs against every client DB.
+
+**Role ids differ per client DB**, so never hardcode a `roleId` in a `CLIENT` ACL migration —
+resolve it with a subselect, e.g. the Base role:
+
+```sql
+roleId = (SELECT id FROM Roles WHERE `name` = 'Base')
+```
+
+## Canonical example (grant the Base role full CRUD on a record)
+
+```sql
+INSERT INTO AclRecordPermissions SET
+	uuid = '…', recordId = 331, roleId = (SELECT id FROM Roles WHERE `name` = 'Base'),
+	allowCreate = 1, allowRead = 1, allowUpdate = 1, allowDelete = 1;
+
+INSERT INTO AclRecordExpressions SET
+	uuid = '…', recordId = 331, slug = 'all', description = 'All', sqlExpression = '1';
+
+INSERT INTO AclLogicGroups SET
+	uuid = '…', aclRecordPermissionId = (SELECT MAX(id) FROM AclRecordPermissions), operator = 'AND';
+
+INSERT INTO AclLogicGroupExpressions SET
+	uuid = '…', aclLogicGroupId = (SELECT MAX(id) FROM AclLogicGroups),
+	aclRecordExpressionId = (SELECT id FROM AclRecordExpressions WHERE recordId = 331 AND slug = 'all');
+
+-- and one AclFieldPermissions row per exposed field (recordFieldId, roleId, isWritable)
+```
+
+## How it is enforced
+
+`_Component_Api_V2::buildLookups()` bulk-loads these tables (from the Core and/or Client ACL
+database per `Records.aclDatabase`) into in-memory lookups once per request; `processRoutePairs()`
+then checks the caller's roles against `AclRecordPermissions` (→ `EZ-1` if no grant) and computes
+readable/writable fields from `AclFieldPermissions`. `_Model_Core_Page::meta()` reads the same
+tables to return per-page ACL to the frontend.
+
+## Checklist (so the chain is never half-built)
+
+- [ ] `AclRecordPermissions` row for the role × record with the right CRUD flags.
+- [ ] `AclRecordExpressions` row (`slug='all'`, `sqlExpression='1'` for unconditional access).
+- [ ] `AclLogicGroups` row with `operator` set (AND/OR) referencing the permission.
+- [ ] `AclLogicGroupExpressions` row binding the group to the expression.
+- [ ] `AclFieldPermissions` rows for every field that must be readable/writable.
+- [ ] For `aclDatabase = 'CLIENT'` records: rows go in client DB(s); resolve `roleId` by subselect.
+
+## Change history
+
+- **2026-06-23** — Documented after repeatedly missing the logic-group/expression rows when
+  granting access to new records. Created alongside the `item-translations` record (331) ACL,
+  whose grant in `dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql` is a worked example of
+  the full chain for a `CLIENT`-aclDatabase record targeting the Base role.

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

@@ -4,6 +4,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 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 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 |
 | [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 |

package/knowledge/2.0/apps/worker2/features/clickup-work-type-automation.md

@@ -0,0 +1,80 @@
+---
+title: ClickUp Work Type Automation (Committed / Conditional / Stretch)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: ["jcardinal"]
+files:
+  - worker2/Worker/Clickup.php
+  - worker2/Tests/Worker/ClickupWorkTypeTest.php
+related:
+  - ./clickup-project-routing.md
+---
+
+## Summary
+The ClickUp webhook handler (`_Worker_Clickup`) automatically maintains each task's **Work
+Type** custom field — `Committed`, `Conditional`, or `Stretch` — based on the task's
+dependencies, its status, and its due date. The core rule: a task that should be Committed is
+demoted to **Conditional** while it still has an unfinished dependency, and promoted back to
+**Committed** once all its dependencies are complete. The logic lives in
+`updateTaskAndDependencies()`.
+
+## Key files / entry points
+- `Worker/Clickup.php` → `Webhook($payload, $headers)` — webhook entry; routes by
+  `$payload->event`.
+- `updateTaskAndDependencies($taskId, $dependsOnTaskId = null)` — the work-type engine.
+- `getWorkType($taskDetails)` — reads the current Work Type custom field value.
+- `isStatusComplete(string $statusType): bool` — true when a ClickUp status type is terminal.
+- `getTaskDetails($taskId)` — cached `GET /task/{id}` (static per-invocation cache).
+
+## How it works
+1. A ClickUp webhook hits the worker; `Webhook()` switches on `$payload->event`.
+2. `updateTaskAndDependencies()` is invoked from the `taskCreated`, `taskUpdated`, and
+   `taskStatusUpdated` events. For `taskStatusUpdated` the call is **gated to terminal
+   statuses** (`isStatusComplete()`) so the dependent re-evaluation cascade only runs when a
+   task actually completes — not on every status change.
+3. For the task, it builds `$waitingOn` — the list of dependencies (`$dependency->task_id ==
+   $taskId`) whose status is **not** complete. A dependency counts as complete when its status
+   `type` is one of `COMPLETE_STATUS_TYPES` (`done` **or** `closed`).
+4. It also computes `$isStalledTask` (status in `on hold` / `awaiting client` / `roadblocked`).
+5. Decision:
+   - `Committed` + (`$waitingOn` non-empty OR stalled) → set **Conditional** (+ comment).
+   - `Conditional` + `$waitingOn` empty + not stalled → set **Committed** (+ comment).
+   - `Stretch` with a due date inside the current sprint → set Committed/Conditional as above.
+6. When a task is depended on by another (`$dependency->depends_on == $taskId`), it recurses
+   into the blocking direction so completing a task re-evaluates the tasks it was blocking. The
+   `$dependsOnTaskId` argument breaks two-node cycles.
+
+## Data model
+Reads/writes the `Team` database (`Tasks`, `Developers`, `Tasks_Developers`, `Sprints`) and the
+ClickUp REST API. The Work Type itself lives in ClickUp as a custom field
+(`CLICK_UP_CUSTOM_FIELD_ID__WORKTYPE`), not in the DB.
+
+## Client variations
+None — internal team/sprint tooling, uniform across clients.
+
+## Gotchas / known issues
+- **Two terminal status types.** ClickUp has both `done` and `closed` terminal status types. A
+  completed dependency may be `closed`, not `done`. The completion check must treat **both** as
+  finished — see `COMPLETE_STATUS_TYPES`. Checking only `== 'done'` leaves dependents stuck on
+  Conditional after their blocker is closed.
+- **Status changes must trigger re-evaluation.** A dependency completing fires
+  `taskStatusUpdated` on the *dependency*, not the blocked task. The `taskStatusUpdated` case
+  must call `updateTaskAndDependencies()` (it recurses into dependents) or the auto-promotion
+  back to Committed never fires on its own.
+- **No PHPUnit harness** in worker2. The regression test
+  `Tests/Worker/ClickupWorkTypeTest.php` is a plain-PHP script (reflection on
+  `isStatusComplete`) run with `php Tests/Worker/ClickupWorkTypeTest.php`.
+
+## Change history
+- 2026-06-23 — Fixed dependents staying Conditional after a blocker completed: completion check
+  now treats `closed` as terminal alongside `done`, and `taskStatusUpdated` re-evaluates
+  dependents (gated to terminal statuses). Added `COMPLETE_STATUS_TYPES`, `isStatusComplete()`,
+  and a plain-PHP regression test. (jcardinal)
+
+## Related docs
+- [ClickUp Project & Opportunity Multi-List Routing](./clickup-project-routing.md)

package/knowledge/INDEX.md

@@ -15,13 +15,13 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 10 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 9 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 11 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 10 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 4 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 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)
 - **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
-- **toga2-view** (TOGa View Frontend) — 0 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
+- **toga2-view** (TOGa View Frontend) — 1 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)

package/knowledge/clients/rate/INDEX.md

@@ -4,4 +4,5 @@
 |-----|-----------|---------|-------|
 | [Rate Monthly Reconciliation Report](features/monthly-reconciliation-report.md) | 1.0 | A monthly cron that emails an Excel reconciliation report covering all Rate subscription sales orders and their linked PayPal payments for the prior calendar mo | worker/crons/notifications/reports/rate/send_monthly_rate_purchases_report.php, worker/schedules/cron.worker.notification.json |
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
+| [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/service-card-entitlements.md

@@ -0,0 +1,103 @@
+---
+title: "Service Card Entitlement Display"
+framework: "2.0"
+repo: toga2-view
+project: TOGa View
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-23
+owners: ["bala"]
+files:
+  - src/components/ServiceCard/ServiceCard.tsx
+  - src/components/ServiceCard/index.ts
+  - src/hooks/useBundleServices.ts
+  - src/pages/Home/api/homeApi.ts
+  - src/pages/Home/view/HomePage.tsx
+  - src/pages/Home/viewModels/useHomePageViewModel.ts
+  - src/pages/Services/view/ServicesPage.tsx
+  - src/pages/Services/viewModels/useServicePageViewModel.ts
+related:
+  - clients/rate/profile.md
+---
+
+## Summary
+
+Rate's home and services pages display one service card per purchased entitlement. The card
+shows a hero image, title, Active badge, contract number, plan, price (or address for warranty
+cards), renewal date, and a Manage button. Previously the UI showed one card per bundle type
+regardless of how many entitlements the user had purchased.
+
+## Key files / entry points
+
+- `ServiceCard.tsx` — the card component; accepts `serviceType` to switch the second data row
+  between Price (tech) and Address (warranty)
+- `useBundleServices.ts` — shared hook returning one `BundleService` per active entitlement;
+  used by both `useHomePageViewModel` and `useServicePageViewModel`
+- `homeApi.ts` — `getActiveServices()` fetches entitlements with subscription and address fields
+- `HomePage.tsx` — shows max 3 cards; "View All Services" tertiary text button links to `/services`
+- `ServicesPage.tsx` — shows all entitlements in a 2-column grid, scrollable
+
+## How it works
+
+1. `getActiveServices(borrowerId)` queries `Entitlements` with:
+   - INNER JOIN: `Contacts`, `Customers`, `Subscriptions`
+   - LEFT JOIN (`ojoin`): `ContactAddresses`, `Addresses` — keeps entitlements whose contact
+     has no address instead of dropping the row
+   - Fields: `uuid`, `number`, `saleItem.title/uuid`, `subscription.isActive/amount/frequency/dateEnd`,
+     `contact.primaryContactAddress.address.line1`
+
+2. `useBundleServices` filters `subscription.isActive === true` and builds one `BundleService`
+   per entitlement. It also fetches bundles to resolve `bundleUuid` for navigation.
+
+3. `detectServiceType(title)` classifies each card:
+   - `'warranty'` — title includes "warranty" or "whole home" (and NOT "tech")
+   - `'tech'` — title includes "tech" or "support"
+   - `'other'` — everything else
+
+4. `ServiceCard` renders the data rows based on `serviceType`:
+   - Tech / other → row 2: **Price** (`$XX.XX`)
+   - Warranty → row 2: **Address** (`contact.primaryContactAddress.address.line1`)
+
+5. Home page slices `allServices` to 3 (`HOME_SERVICE_LIMIT`). If more exist, a tertiary
+   "View All Services" text link appears below the cards pointing to `/services`.
+
+6. Services page renders all entitlements with no cap in a `grid-cols-1 md:grid-cols-2` grid.
+
+## Data model
+
+Address path in DB:
+```
+Entitlements.contactId
+  → Contacts.primaryContactAddressId
+  → ContactAddresses.id → ContactAddresses.addressId
+  → Addresses.line1
+```
+
+Contract number comes from `Entitlements.number` (auto-incremented with ET prefix, e.g. `ET100017`).
+
+## Client variations
+
+This feature is Rate-specific. The warranty card showing Address instead of Price is driven
+by Rate's product mix (Whole Home Warranty + Tech Support). Other clients with different
+product types would need `detectServiceType` extended or overridden.
+
+## Gotchas / known issues
+
+- **`ojoin` is required for address** — using INNER JOIN (`join`) drops every entitlement
+  whose contact has no `primaryContactAddressId`, silently hiding those cards.
+- **`T00:00:00` in date formatting** — `formatDate` appends this before parsing to avoid
+  timezone offset shifting the renewal date back by one day.
+- **Per-entitlement, not per-bundle** — `useBundleServices` intentionally does not dedup.
+  A user with 8 entitlements of the same product sees 8 cards. The old dedup-by-bundle
+  behavior (1 card per service type) was the previous design.
+- **Inactive bundles are not shown** — the new design only renders active entitlements.
+  The "Add a subscription" dashed button (handled by `useAddSubscription` hook +
+  `AddSubscriptionSheet`) replaces the old "Get Started" inactive bundle cards.
+- **`useBundleServices` is shared** — both `useHomePageViewModel` and `useServicePageViewModel`
+  call it. Changes to the hook affect both pages.
+
+## Change history
+
+- 2026-06-23 — Initial implementation: per-entitlement card display, new ServiceCard component,
+  address via LEFT JOIN, 3-card home limit with View All Services tertiary button (bala)

package/package.json

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