toga-ai 1.0.167 → 1.0.168

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,8 +15,8 @@ _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)

package/package.json

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