toga-ai 1.0.426 → 1.0.428

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-23
 owners: ["jcardinal", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -56,6 +56,13 @@ writable). Without it the field is rejected on write **and** is unreadable:
 - **`AclFieldPermissions` is `UNIQUE (recordFieldId, roleId)`** (Client blank DDL) — guard inserts
   with `NOT EXISTS`. For a **read-only, server-written** field (one populated by a `postPost`
   interceptor rather than the API caller), grant `isWritable = 0`.
+- **A read-only field only needs a grant on the role(s) that actually READ it — find that role by
+  mirroring a sibling field of the same kind the readers already consume**, rather than blanket-granting
+  every role. E.g. the standard FK `serviceAddressId` mirrored its sibling FK `saleItemId`, whose sole
+  reader in `Client_Rate` is **role 1** (the toga2-view service cards) — so a single role-1 read grant
+  sufficed, NOT a 1/2/4 fan-out (a cross-role probe had shown roles 1/2/4 all lacked the grant, but only
+  role 1 actually reads the field). Grant `isWritable = 0` for a server-written field; resolve the role
+  by name/subselect (ids differ per client DB). Beta-proven on Rate `Client_Rate` 2026-07-23.
 
 ### Standard field vs. custom (`c_`) field — TWO different permission tables
 
@@ -199,6 +206,11 @@ the field.
 
 ## Change history
 
+- **2026-07-23** — TRUE-79533: noted that a **read-only field only needs a grant on the role(s) that
+  actually read it** — mirror a sibling field of the same kind the readers already consume rather than
+  granting every role. The standard FK `serviceAddressId` mirrored `saleItemId`'s reader, **role 1** in
+  `Client_Rate` (the toga2-view service cards), so a single role-1 read grant sufficed (not a 1/2/4
+  fan-out). (tcox)
 - **2026-07-23** — TRUE-79533: documented the **READ side** of `AclFieldPermissions` — a registered
   field with no grant returns **`EZ-2`** on read (the counterpart of the write code `EV-9`), and
   the **standard vs. custom** split: standard fields use `AclFieldPermissions` (keyed by

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-07-23
-owners: ["dfranks", "jcardinal", "mhammontree", "apeterson"]
+owners: ["dfranks", "jcardinal", "mhammontree", "apeterson", "kyalamarthi"]
 files:
   - _underscore/Database.php
   - _underscore/ApiRequest.php
@@ -75,6 +75,22 @@ per-client), region-aware (1=us-east-1, 2=us-west-2, 3=eu-west-1) with per-regio
 registration is region-aware in `api2/Controller/Index.php`; the alias const is in `api2/_.php`.
 `Records.ttlCache` (TINYINT UNSIGNED, default 15) governs cache TTL.
 
+### The `Team` schema rides the Core cluster (`DB_TEAM`)
+
+The **`Team` schema** (tables `Tasks`, `Sprints`; models `_Model_Team_Task` / `_Model_Team_Sprint`
+with `const DATABASE = _underscore::DB_TEAM`) is **not a first-class api2 database** — it is not a
+value of `Core.Records.aclDatabase` (that enum is only `'CORE'` / `'CLIENT'`). It physically
+resolves to the **core cluster**: `DB_TEAM` **reads** route to `reader1.core.database.togahub.com`
+and **writes** to `writer.core.database.togahub.com`. So a `DB_TEAM` SELECT auto-routes to the core
+reader, and a Record backed by the `Team` schema must be registered with **`aclDatabase = 'CORE'`**
+(see [Record Scripts](../../api2/features/record-scripts.md)).
+
+**Where DB hosts come from — the split:** Core and other **non-client** cluster hosts (Core, the
+`Team`-schema-bearing core cluster, etc.) come from the api2 `Config/*.ini` **`[database]`
+section**, not from `DatabaseHosts`. **Per-client** hosts come from the `Core.DatabaseHosts` table,
+resolved by `_Database::registerClientDatabases()`. (Credential/host *values* are not reproduced
+here — they live in `Config/*.ini`.)
+
 ## Gotchas / known issues
 
 - **The "logs DB write trap" (local dev).** A laptop usually imports only `Client_<Id>`, not
@@ -108,6 +124,13 @@ registration is region-aware in `api2/Controller/Index.php`; the alias const is
 
 ## Change history
 
+- 2026-07-23 — Documented that the **`Team` schema** (`Tasks`/`Sprints`, `_Model_Team_*`,
+  `DB_TEAM`) is not a first-class api2 DB (not in `Records.aclDatabase`, which is CORE/CLIENT
+  only) and physically resolves to the **core cluster** (reads → `reader1.core…`, writes →
+  `writer.core…`), so `DB_TEAM` SELECTs auto-route to the core reader and a `Team`-backed Record
+  registers as `aclDatabase = 'CORE'`. Also recorded the host-resolution split: Core/non-client
+  hosts come from api2 `Config/*.ini` `[database]`; per-client hosts come from `DatabaseHosts`
+  via `registerClientDatabases()`. (kyalamarthi)
 - 2026-07-23 — Documented the shared **Core Logs** (`DB_LOGS`) analogue of the logs trap: its schema
   name is resolved from a `Core.Database` row (`id = CORE_LOGS_DATABASE_ID`) in
   `api2/Controller/Index.php::api()`, so a name-mismatched local Logs DB still reads as missing; and

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

@@ -7,6 +7,7 @@
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, plus item **feature** text — `Features.name`, `ItemCategoryFeatureGroups.name`, `ItemFeatures | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, _underscore/Model/Client/FeatureTranslation.php, _underscore/Model/Client/ItemCategoryFeatureGroupTranslation.php, _underscore/Model/Client/ItemFeatureTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-13a - FeatureTranslations.sql, dbchanges2/Client/2026-07-13b - FeatureTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql, dbchanges2/Core/2026-07-13 - FeatureTranslationsRecord.sql |
 | [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
+| [Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)](features/record-scripts.md) | In api2 you almost never write a controller. | api2/Component/Api/V2/V2.php, _underscore/Model/Team/Sprint.php |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |

package/knowledge/2.0/apps/api2/features/record-scripts.md

@@ -0,0 +1,160 @@
+---
+title: Record Scripts (computed/aggregate /v2 endpoints — the authoring contract)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-23
+owners: ["kyalamarthi"]
+files:
+  - api2/Component/Api/V2/V2.php
+  - _underscore/Model/Team/Sprint.php
+related:
+  - ./scripted-api-post-body-args.md
+  - ./tableview-apiwhereclause-row-filtering.md
+  - ../architecture.md
+  - ../../_underscore/features/per-client-database-connections.md
+  - ../../worker2/features/team-sprint-management.md
+---
+
+## Summary
+
+In api2 you almost never write a controller. The generic **/v2 engine** serves models from
+metadata (Records / RecordFields / ACL rows), so ordinary CRUD is a *data* change, not code.
+For a payload the metadata CRUD path cannot express — a **computed value, an aggregate, or a
+purpose-built dashboard tile** — the mechanism is a **Record Script**: a `public static`
+method on the record's `_Model` whose return value becomes the `/v2` envelope `data`. This is
+the company-standard way to add a read-only, non-CRUD endpoint.
+
+This doc is the **authoring contract** for a Record Script (the general pattern and how to
+register one). For the POST + JSON-request-body variant (large argument values), see
+[POST + JSON-body args for scripted APIs](./scripted-api-post-body-args.md).
+
+Motivating example: `_Model_Team_Sprint::committedTile()` — a read-only dashboard tile over
+the internal TOGa IQ sprint (`Team` schema) data. **Decision recorded:** internal
+sprint/dashboard read endpoints are served from **api2 via a Record Script**, not by building
+a bespoke controller or standing the data up inside the talos / TOGa IQ app.
+
+## The method contract
+
+A Record Script is a static method on the record's model — for the example above, the
+signature is `public static function committedTile(&$api, int|string $sprint): object` on
+`_underscore/Model/Team/Sprint.php`. Its return value becomes the `/v2` envelope `data`.
+
+Rules the engine enforces (see `getRecordScriptPhpMethod()` + the dispatch in
+`processRoutePairs()` inside `api2/Component/Api/V2/V2.php`):
+
+- **First parameter is `&$api`** — the engine always sets `$args['api'] = $this` last, so the
+  method receives the live V2 engine instance (for auth context, `internalApiRequest()`, etc.).
+- **Remaining parameters are named** and are filled from the **query string**. Each query-string
+  key maps to the same-named PHP parameter; unmatched named args land in a `...$args` variadic
+  if the method declares one. (`transactionId` and `api` keys are reserved and never mapped.)
+- **The return value is the envelope `data`.** Return an object/array; do not echo, and do not
+  return the bare success/error envelope — the engine wraps it.
+- Invocation is effectively `$model::$phpMethod(...$args)`.
+
+## Running SQL inside a Record Script
+
+Record Scripts commonly run their own query (via `new \_Query($sql, \_underscore::DB_TEAM)`
+then `->fetchRow()`) rather than going through model CRUD. Two framework realities to respect:
+
+- **`_Query` has no bound-parameter support.** There is no `?`/`:name` binding. Every value
+  you place into the query text must be sanitized by hand **before** it is assembled into the
+  SQL: pass strings through `\_Database::escape()` and cast numerics with `(int)`. Record-script
+  arguments arrive straight from the query string (user input), so this sanitization is
+  mandatory — an unsanitized value in the query text is a SQL-injection hole. Treat
+  `\_Database::escape()` + `(int)` casting as the required substitute for the prepared
+  statements `_Query` does not offer.
+- **Query cache for "live" tiles.** A dashboard tile that must reflect current data should call
+  `\_Database::useQueryCache(false)` before the query and **restore the previous flag**
+  afterward (capture the value it returns and set it back), so it doesn't serve stale cached
+  rows and doesn't leave caching globally disabled for the rest of the request.
+- `DB_TEAM` SELECTs auto-route to the **core cluster reader** — see
+  [per-client database connections](../../_underscore/features/per-client-database-connections.md)
+  for why the `Team` schema resolves to core.
+
+## Registering / enabling an endpoint (metadata across two databases)
+
+Registering a Record Script is a **metadata change split across two databases plus a
+per-client ACL grant** — it is not a code deploy. The route is
+**`GET /v2/<recordRoute>/<scriptRoute>`**.
+
+**Data model:**
+
+- **`Core.Records`** (the route ↔ model row). Its **`aclDatabase` enum is only `'CORE'` or
+  `'CLIENT'`** — there is no `TEAM` value, so a `Team`-schema-backed record registers as
+  **`aclDatabase = 'CORE'`** (the `Team` schema physically lives on the core cluster).
+- **`Core.RecordScripts`** — `uuid`, `recordId` (FK → `Core.Records`), `method` (e.g. `GET`),
+  `route` (the script route), `phpMethod` (the static method name). **`UNIQUE(recordId, method,
+  route)`.**
+- **`Client.AclRecordScripts`** — model `_Model_Client_AclRecordScript`, on `DB_CLIENT`:
+  `recordScriptId` (FK → `Core.RecordScripts`) + `roleId` (FK → `Client.Roles`). This is the
+  ACL grant, and it lives **per client** — so **record-script authorization is per-client**:
+  granting a role in one client does not grant it in another.
+
+At dispatch the engine calls `getRecordScriptPhpMethod(record, httpMethod, route, roleIds)`,
+which joins `Core.RecordScripts` to the caller's `Client.AclRecordScripts` rows for their
+roles; no matching grant → the script does not run for that caller.
+
+**Where the rows go:** seed them in **dbchanges2** as dated migration files — the
+`Core.Records`/`Core.RecordScripts` rows under the `Core` folder, and the `AclRecordScripts`
+grant under the per-client `Client_<Name>` folder. See the
+[api2 architecture — metadata CRUD engine](../architecture.md) for the surrounding Records
+metadata model.
+
+## Data source note (core DB hosts/credentials)
+
+The core cluster hosts and credentials this endpoint reads through are **not** documented here;
+they live in **api2 `Config/*.ini`** (`[database]` section). Do not paste those values into
+knowledge or code.
+
+## Client variations
+
+None — this is engine behavior. Per-client access is entirely controlled by which roles have
+an `AclRecordScripts` grant in each client DB.
+
+## Gotchas / known issues
+
+- **No bound params in `_Query`.** Sanitize with `\_Database::escape()` (strings) and `(int)`
+  casts (numerics) for every value placed into the query text — query-string args are user
+  input.
+- **Restore the query-cache flag.** `useQueryCache(false)` is a global toggle; capture the
+  prior value and restore it, or you disable caching for the rest of the request.
+- **`aclDatabase` has no `TEAM`.** A `Team`-schema record registers as `'CORE'`; picking
+  `'CLIENT'` sends the engine looking in the wrong cluster.
+- **Registration is per-environment and split.** A missing `Core.RecordScripts` row → the route
+  isn't a script (falls through to normal CRUD / 404-shaped behavior); a missing
+  `AclRecordScripts` grant → the caller's roles can't run it. Both rows must exist in every
+  environment the API serves.
+- **The committed-tile definition is intentionally not the sprint-scoring definition.**
+  `committedTile()` uses the **Power BI / current-state** definition of done/committed
+  (`dtDone IS NOT NULL` + `workTypeNow`), which is *deliberately different* from TOGa IQ's
+  canonical sprint scoring (`statusNow IN (STATUS_IN__DONE)` + `workTypeAtLock`). See
+  [Team Sprint Management](../../worker2/features/team-sprint-management.md) before assuming a
+  tile agrees with sprint scores.
+
+## Change history
+
+- 2026-07-23 — Initial documentation of the Record Script authoring contract (static
+  `fn(&$api, ...namedParams)` on the record model; query-string → named args; return → `/v2`
+  envelope `data`), the SQL specifics (`_Query` has no bound params → `_Database::escape()` +
+  int-cast; `useQueryCache(false)` + restore for live tiles), and the registration metadata
+  (`Core.Records` `aclDatabase` CORE/CLIENT only, `Core.RecordScripts` UNIQUE(recordId,method,
+  route), per-client `Client.AclRecordScripts` grant). Motivated by
+  `_Model_Team_Sprint::committedTile()`, a read-only internal sprint dashboard tile — recording
+  the decision that internal sprint/dashboard reads are served from api2 via a Record Script
+  rather than the talos / TOGa IQ app. (kyalamarthi)
+
+## Related docs
+
+- [POST + JSON-body args for scripted APIs](./scripted-api-post-body-args.md) — the POST /
+  JSON-request-body variant for large argument values.
+- [api2 architecture](../architecture.md) — the metadata-driven /v2 CRUD engine that Record
+  Scripts extend.
+- [Per-Client Database Connections](../../_underscore/features/per-client-database-connections.md)
+  — why `DB_TEAM` resolves to the core cluster.
+- [Team Sprint Management & Reporting](../../worker2/features/team-sprint-management.md) — the
+  canonical sprint scoring definition the committed tile deliberately diverges from.
+</content>

package/knowledge/2.0/apps/toga2-view/features/query-string-builder.md

@@ -60,5 +60,3 @@ easy to misread as an API problem.
   values to `String` before `urlEncode` — a numeric value (first hit via `fetchAddressesByIds`)
   threw `input.replace is not a function` and silently aborted the request client-side. Added
   regression tests. (tcox)
-</content>
-</invoke>

package/knowledge/2.0/apps/toga2-view/features/zip-validation-contact-phone.md

@@ -46,4 +46,3 @@ the store when it changed.
   field (a different covered property can have a different contact number). Previously the field
   was disabled once the store held a phone, and the post-purchase save made the first purchase lock
   it for every later visit. `save-if-different` retained. (tcox)
-</content>

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

@@ -28,7 +28,7 @@
 | [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 |
 | [Talos Pricing Automation (worker2 Cron — AWS Actuals, Calibration, Monthly Report)](features/talos-pricing-automation.md) | The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model` and tools `talos-pricing-ui` docs for the other halves). | worker2/Worker/Talos/Pricing.php, worker2/Database/TalosPricingCrons.sql |
 | [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | `_Worker_Team_Transcripts` runs a fully automated, cron-driven pipeline that ingests raw Teams transcripts into the **Talos / TOGa IQ** AWS Bedrock knowledge ba | worker2/Worker/Team/Transcripts.php, worker2/bin/sync-knowledge-bases.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Team/2026-06-30a, dbchanges2/Team/2026-06-30b, dbchanges2/Team/2026-06-30c, dbchanges2/Team/2026-06-30d, dbchanges2/Team/2026-06-30e, dbchanges2/Core/2026-06-30a, dbchanges2/Core/2026-07-02a, dbchanges2/Team/2026-07-02a, dbchanges2/Team/2026-07-08a, dbchanges2/Team/2026-07-09a, dbchanges2/Team/2026-07-10a |
-| [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, dbchanges2/Core/CronJobs (SprintLockScheduled seed) |
+| [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, _underscore/Model/Team/Sprint.php, dbchanges2/Core/CronJobs (SprintLockScheduled seed) |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | > **SUPERSEDED (2026-07-09) — the S3-staging model below is history.** `Export` is now a thin > **GRAPH-DIRECT** cron poller: it no longer archives raw VTT to ` | 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 |

package/knowledge/2.0/apps/worker2/features/team-sprint-management.md

@@ -6,10 +6,11 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
-owners: ["jcardinal"]
+updated: 2026-07-23
+owners: ["jcardinal", "kyalamarthi"]
 files:
   - worker2/Worker/Team/Sprint.php
+  - _underscore/Model/Team/Sprint.php
   - dbchanges2/Core/CronJobs (SprintLockScheduled seed)
 related:
   - ../architecture.md
@@ -228,8 +229,34 @@ backfills `workTypeAtLock` the first time a task is seen).
   Do **not** overload one map for both jobs. This pattern is replicated identically in
   `SprintLock()`, `CaptureSprintEnd()`, and `CaptureSprintDaily()` — fix all three together.
 
+## Two coexisting "committed / done" definitions (reconcile before comparing)
+
+There are **two intentionally-different definitions** of committed/done for a sprint task, and
+they do not agree:
+
+1. **Canonical sprint-scoring definition** — used by the scoring model above (and by the
+   reusable scoring helpers `_pointsByWorkType` / `_tasksByWorkType` on **`_Model_Team_Sprint`**
+   in `_underscore`, `Model/Team/Sprint.php`): a task is *done* when
+   `statusNow IN (STATUS_IN__DONE)` and its category is taken from **`workTypeAtLock`** (the
+   frozen at-lock baseline). This is what reliability/integrity scoring measures against.
+2. **Power BI / current-state definition** — used by dashboard tiles that must match the Power BI
+   numbers: *done* is **`dtDone IS NOT NULL`** and category is **`workTypeNow`** (current state,
+   not the at-lock snapshot). The api2 Record Script
+   [`_Model_Team_Sprint::committedTile()`](../../api2/features/record-scripts.md) deliberately
+   uses this definition.
+
+Neither is "wrong" — they answer different questions (scored performance vs. live current state).
+If a tile or report must **agree with TOGa IQ's canonical scoring**, reconcile it to definition
+(1); otherwise expect current-state tiles to diverge from sprint scores.
+
 ## Change history
 
+- 2026-07-23 — Recorded that two intentionally-different "committed/done" definitions coexist:
+  the canonical sprint-scoring definition (`statusNow IN (STATUS_IN__DONE)` + `workTypeAtLock`,
+  incl. the reusable `_pointsByWorkType`/`_tasksByWorkType` helpers on `_Model_Team_Sprint` in
+  `_underscore`) vs. the Power BI / current-state definition (`dtDone IS NOT NULL` +
+  `workTypeNow`) used by dashboard tiles such as the api2 `committedTile()` Record Script.
+  Added `_underscore/Model/Team/Sprint.php` to this doc's files. (kyalamarthi)
 - 2026-07-21 — Added `SprintLockScheduled()` action + a `Core.CronJobs` seed
   (`0 10 * * 3`, every Wednesday 10 AM Central, action `Team/Sprint/SprintLockScheduled`,
   maxExecutionTime 600) to run **Sprint Lock automatically at the start of each biweekly

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 37 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 31 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 13 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 14 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)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/knowledge/clients/rate/features/aig-contract-creation.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-06-29
-owners: [mhammontree]
+updated: 2026-07-23
+owners: [mhammontree, tcox]
 files:
   - _underscore/Model/Rate/Entitlement.php
   - _underscore/ApiRequest.php
@@ -96,9 +96,21 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
   address, so an entitlement with no address never even attempts contract creation (and
   never logs a `/contract` call).
 - **Auth-induced failures are blind to the monitor** — see the detection limitation above.
+- **The AIG-success branch REASSIGNS `$payload->uuid`** (`$payload->uuid = _String::generateUuid()`,
+  repurposed as the AIG contract number) — and it does so **in the same `postPost`** that pins the WH
+  service address. On the pre-redesign build the pin step ran **after** this reassignment and keyed
+  off `$payload->uuid`, so **every successful AIG contract silently broke the WH address pin** (the
+  pin lookup matched no row). Preserve the ordering fix — snapshot the entitlement uuid **before**
+  this branch. See the
+  [WH per-address purchase guard](whole-home-warranty-purchase-guard.md) "AIG-success clobbers the
+  pin" gotcha (`_underscore` `_beta` `9c2e4b1c`).
 
 ## Change history
 
+- 2026-07-23 — Documented that the **AIG-success branch reassigns `$payload->uuid`** (as the contract
+  number) inside the shared `postPost`, which silently broke the WH service-address pin on the
+  pre-redesign build (pin keyed off the now-reassigned uuid). Fixed by snapshotting the entitlement
+  uuid before the AIG branch (`_underscore` `_beta` `9c2e4b1c`). Cross-linked the WH guard doc. (tcox)
 - 2026-07-07 — `postPost` now also persists the validated service address
   (`Entitlements.c_serviceAddressId`, `Addresses.isValidated=1`), wrapped so it never blocks the
   AIG-contract/email flow; a new WH `prePost` guard carrier-normalizes the address onto the

package/knowledge/clients/rate/features/whole-home-warranty-purchase-guard.md

@@ -106,6 +106,10 @@ Ticket: TRUE-79533. Business rule owner: PM Paulina.
    `Addresses.isValidated = 1` and writes `Entitlements.serviceAddressId`. This block is
    wrapped so a failure never interrupts the AIG-contract creation or the confirmation email
    (see the [AIG contract creation doc](aig-contract-creation.md) — the same `postPost`).
+   **The entitlement UUID is snapshotted up front** (`$entitlementUuid = $payload->uuid`) at the
+   top of `postPost`, **before** the AIG branch runs — because the AIG-success branch reassigns
+   `$payload->uuid` (see the "AIG-success clobbers the pin" gotcha). The pin lookup must use the
+   snapshot, not `$payload->uuid`.
 6. All SQL uses `_Database::escape()` / int-casts — `_Query` has **no bind API** in this path.
 
 ## Field & model: `serviceAddressId` is now a STANDARD field (reviewer Jeff)
@@ -280,6 +284,22 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
 - **`ApiPayloadInterceptors` (Client_Rate) has no `phpMethod` column.** The interceptor method
   is resolved **by convention** from `(prePostProcessing, httpMethod)`: `PRE+POST → prePost`,
   `POST+POST → postPost` (matches the framework `[pre|post][HttpMethod]` convention).
+- **ROOT CAUSE of NULL pins on the pre-redesign build: the pin silently fails whenever the AIG
+  contract is created SUCCESSFULLY.** The old `postPost` pinned the entitlement by `$payload->uuid`,
+  but the **AIG-success branch reassigns `$payload->uuid = _String::generateUuid()`** (reusing it as
+  the AIG contract number) **before** the pin step. So on an AIG success the pin lookup by
+  `$payload->uuid` matches **no row**, logs `"TRUE-79533: could not resolve service address"`, and
+  gives up — leaving `Entitlements.serviceAddressId` (and, pre-redesign, `c_serviceAddressId`) NULL
+  and the purchase's `Addresses.isValidated` NULL (that pair is the fingerprint of a lost pin).
+  Pinning is therefore **intermittent — it works only when AIG auth FAILS** (the branch that
+  clobbers the uuid never runs). Proven on beta `Client_Rate` 2026-07-23: entitlement 68 pinned,
+  69/70/71 unpinned despite an intact Contact→`primaryContactAddressId`→ContactAddresses chain.
+  **Fixed in `_underscore` `_beta` commit `9c2e4b1c`**: `postPost` snapshots
+  `$entitlementUuid = $payload->uuid` up front, before the AIG branch, and pins by the snapshot.
+  **DEPLOY DEPENDENCY:** any environment still running a **pre-redesign** `api2`/`_underscore` build
+  loses the address pin every time AIG succeeds; the fix only takes effect on **EB redeploy**
+  (api2 pulls `_underscore` at deploy). This is the mechanism behind the COALESCE fallback and the
+  dangling-pin gotcha below — the fallback is what keeps the dedup correct while pins are missing.
 - **Dedup is defeated by a DANGLING pin (not just a NULL one).** The COALESCE fallback covers a
   **NULL** `serviceAddressId`, but if `serviceAddressId` points at a **deleted `Addresses` row**,
   the join drops that entitlement and it becomes **invisible to the guard** — a duplicate WH slips
@@ -324,6 +344,17 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
   (verified in `api2/Component/Api/V2/V2.php` `getAclFieldPermissions()` ~line 5731), which is why
   a custom→standard promotion must re-create the read grant as an `AclFieldPermissions` row.
   (mhammontree)
+- 2026-07-23 — **Root cause of intermittent NULL pins + guard hardening confirmed** (tcox). (1) The
+  `postPost` service-address pin **silently fails whenever the AIG contract creation SUCCEEDS**,
+  because the AIG-success branch reassigns `$payload->uuid` before the pin step, so pinning by
+  `$payload->uuid` matches no row (fingerprint: `serviceAddressId` + `Addresses.isValidated` both
+  NULL). Proven on beta (entitlement 68 pinned, 69/70/71 not). Fixed in `_underscore` `_beta`
+  `9c2e4b1c` (snapshot `$entitlementUuid` up front). Deploy-dependency: pins are lost on AIG success
+  on any pre-redesign build until EB redeploy. (2) The dedup blind spot (unpinned entitlements
+  invisible to `hasActiveWarrantyAtAddress` — demonstrated live: two active WH at "STE 250" slipped
+  through on the old build) is **CLOSED in `_beta` `a9f408bc`** — the dedup joins Addresses via
+  `COALESCE(serviceAddressId, ContactAddresses.addressId)`, disables the query cache for the read,
+  and documents an accepted TOCTOU. (tcox)
 - 2026-07-23 — **LAUNCH BLOCKER found: the standard `serviceAddressId` field has NO read ACL grant**
   (tcox). Probe-verified on beta: `GET /v2/entitlements?fields=serviceAddressId` → 403 `EZ-2` for
   roles 1/2/4 (`aclDatabase=CLIENT`). Standard fields are authorized via **`AclFieldPermissions`**

package/knowledge/clients/rate/profile.md

@@ -3,6 +3,7 @@ title: "Rate"
 framework: "2.0"
 apps:
   - _underscore
+  - api2
   - saml
   - toga2-view
   - worker
@@ -12,8 +13,8 @@ project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-06-30
-owners: ["rgirish", "bala", "mhammontree"]
+updated: 2026-07-23
+owners: ["rgirish", "bala", "mhammontree", "tcox"]
 files: []
 related:
   - clients/rate/features/saml-sso.md

package/package.json

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