toga-ai 1.0.435 → 1.0.437

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

@@ -9,8 +9,9 @@
 | [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 FK object embedding is gated by the CHILD record's own ACL](features/nested-fk-acl-embedding.md) | When the V2 JSON engine serializes a foreign-key field into a **nested object** (in `getFullModelData()`, ~V2.php L6016-6060), it re-checks the **child** record | api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.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 |
+| [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, _underscore/Query.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 |
+| [TOGa IQ Sprint Dashboard API (Record Scripts)](features/sprint-dashboard-api.md) | The internal **TOGa IQ sprint dashboard** is served in production by **six api2 Record Scripts** on `_Model_Team_Sprint` (`_underscore/Model/Team/Sprint.php`), | _underscore/Model/Team/Sprint.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql, dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql |
 | [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 |
 | [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql |

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

@@ -6,12 +6,14 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-07-24
 owners: ["kyalamarthi"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Team/Sprint.php
+  - _underscore/Query.php
 related:
+  - ./sprint-dashboard-api.md
   - ./scripted-api-post-body-args.md
   - ./tableview-apiwhereclause-row-filtering.md
   - ../architecture.md
@@ -35,7 +37,13 @@ register one). For the POST + JSON-request-body variant (large argument values),
 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.
+a bespoke controller or standing the data up inside the talos / TOGa IQ app. This contract was
+subsequently validated by productionizing the whole sprint dashboard into six Record Scripts —
+see [TOGa IQ Sprint Dashboard API](./sprint-dashboard-api.md) for the concrete endpoint set.
+
+**The model class lives in `_underscore`, not api2.** `_Model_Team_Sprint` is
+`_underscore/Model/Team/Sprint.php`, pulled in at deploy — api2 has **no `Model/` directory**
+of its own. Write the static method in `_underscore`, not in the api2 repo.
 
 ## The method contract
 
@@ -51,9 +59,17 @@ Rules the engine enforces (see `getRecordScriptPhpMethod()` + the dispatch in
 - **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.
+- **The return value becomes the envelope `data` — but nested under the route segment.** The
+  engine does `$outData[$requestedUuid] = method(...)` then `return (object)$outData`
+  (`V2.php` ~:4121, :6305), so the script's payload lands **under the script's route-segment
+  key**, not flat. `GET /v2/sprints/tile` yields `data: { tile: {…} }`, not `data: {…}`;
+  `campaigns/jobs` yields `data: { jobs: … }`. **A consumer must unwrap `data[<route>]`.** The
+  method itself still returns the raw object/array — do not echo, and never build the
+  success/error envelope yourself.
 - Invocation is effectively `$model::$phpMethod(...$args)`.
+- **No current-sprint (or any per-request context) middleware.** Unlike a hand-built app, the
+  `/v2` engine has no middleware that pre-resolves a "current" entity for a script. Each Record
+  Script must resolve its own context (e.g. the current sprint) inside the method.
 
 ## Running SQL inside a Record Script
 
@@ -66,7 +82,11 @@ then `->fetchRow()`) rather than going through model CRUD. Two framework realiti
   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.
+  statements `_Query` does not offer. For a query-string arg drawn from a **fixed set** (an
+  enum-like `?category=`), the safest handling is a **value allowlist** — map the arg to a
+  trusted server-side constant (e.g. the sprint dashboard maps `?category=` to the
+  `_Model_Team_Task::WORK_TYPE__*` constants) and reject anything unrecognized, so no raw
+  user value ever reaches the SQL text.
 - **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
@@ -104,6 +124,18 @@ grant under the per-client `Client_<Name>` folder. See the
 [api2 architecture — metadata CRUD engine](../architecture.md) for the surrounding Records
 metadata model.
 
+**Registration conventions** (confirmed against
+`Core/… - TrackingNumberReprintRecordScript.sql` + its `Client/… - …ScriptAcl.sql`):
+
+- Write the migrations **id-agnostic** — resolve FKs by looking the parent up **by route**,
+  and guard every insert with a **`NOT EXISTS`** subquery on its natural key so the file is
+  re-runnable and environment-agnostic (auto-increment ids differ per environment).
+- `Core.Records` carries the human-facing `name` / `description`.
+- The `AclRecordScripts` grant is a **CLIENT-DB** table. Put it in the specific
+  **`Client_<Name>`** folder for the tenant that should get the script — an internal-only
+  endpoint goes in `Client_True`. The generic **`Client/`** folder runs against **every**
+  tenant DB, so putting an ACL grant there hands the endpoint to all clients.
+
 ## Data source note (core DB hosts/credentials)
 
 The core cluster hosts and credentials this endpoint reads through are **not** documented here;
@@ -137,6 +169,15 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Change history
 
+- 2026-07-24 — Refined the engine contract from productionizing the sprint dashboard (verified
+  in `V2.php` + `_underscore/Query.php`): the return value **nests under the route-segment key**
+  (`data[<route>]`, not flat — consumers must unwrap); there is **no current-sprint/context
+  middleware** (each script resolves its own context); the `_Model` class lives in
+  **`_underscore`** (pulled at deploy — api2 has no `Model/` dir). Added registration
+  conventions (id-agnostic resolve-by-route + `NOT EXISTS` guards; the `AclRecordScripts` grant
+  belongs in the tenant-specific `Client_<Name>` folder, never generic `Client/`, or it grants
+  every tenant) and the value-allowlist pattern for enum-like query args. Linked the new
+  [Sprint Dashboard API](./sprint-dashboard-api.md). (kyalamarthi)
 - 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()` +
@@ -149,6 +190,8 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Related docs
 
+- [TOGa IQ Sprint Dashboard API](./sprint-dashboard-api.md) — the concrete six-endpoint set
+  that productionized this contract.
 - [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

package/knowledge/2.0/apps/api2/features/sprint-dashboard-api.md

@@ -0,0 +1,140 @@
+---
+title: TOGa IQ Sprint Dashboard API (Record Scripts)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: ["kyalamarthi"]
+files:
+  - _underscore/Model/Team/Sprint.php
+  - api2/Component/Api/V2/V2.php
+  - dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql
+  - dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql
+related:
+  - ./record-scripts.md
+  - ../architecture.md
+  - ../../worker2/features/team-sprint-management.md
+---
+
+## Summary
+
+The internal **TOGa IQ sprint dashboard** is served in production by **six api2 Record
+Scripts** on `_Model_Team_Sprint` (`_underscore/Model/Team/Sprint.php`), reading the `Team`
+schema on the core cluster. This replaced the prior session's local Node/React + Express
+(mysql2) stand-in — the prototype only ever proved the metric SQL; this is the real `/v2`
+path. **No api2 code was written**: the endpoints are the generic `/v2` engine plus the
+model methods (which live in `_underscore`) plus metadata rows seeded via dbchanges2.
+
+Producer/consumer split: **worker2** (`_Worker_Team_Sprint`) captures ClickUp sprint data
+into `DB_TEAM`; **api2** serves it read-only through these Record Scripts. The dashboard is
+internal-only — its `AclRecordScripts` grant is scoped to the **True** (staff) tenant.
+
+For the general authoring/registration contract these follow, see
+[Record Scripts](./record-scripts.md). For the metric definitions the SQL implements, see
+[Team Sprint Management](../../worker2/features/team-sprint-management.md).
+
+## The six endpoints
+
+All are `public static` methods on `_Model_Team_Sprint`, each run as `new \_Query($sql,
+\_underscore::DB_TEAM)` returning a raw object the `/v2` engine envelopes. Route is
+`GET /v2/sprints/<scriptRoute>` (record route `sprints` → `_Model_Team_Sprint`).
+
+| phpMethod | Purpose |
+|-----------|---------|
+| `current` | Resolve the current sprint (never hardcoded — see below). |
+| `sprintTile` | A single KPI tile; selected by **`?category=`** (Committed / Conditional / Stretch / Unplanned). |
+| `statusBreakdown` | Status-rollup pie (the SWITCH-into-five-buckets, default → Review). |
+| `workTypeBreakdown` | Work-type pie — `SUM(sprintPointsNow) GROUP BY workTypeNow`. |
+| `pointsByDev` | Sprint points by developer (Tasks ⋈ Tasks_Developers ⋈ Developers). |
+| `burndown` | Burndown over working days (CCU vs CCUS), `dayNumber` 1-based. |
+
+## Envelope nesting — data is under the route-segment key
+
+The engine nests a scripted return value **under the script's route segment**, it is not
+flattened: `GET /v2/sprints/tile` returns `data: { tile: {…} }`, and `GET /v2/sprints/current`
+returns `data: { current: {…} }`. A consumer must unwrap `data[<route>]`, not read `data`
+directly. (Same shape as the live `campaigns/jobs` script → `data: { jobs: … }`.) This is the
+single biggest gotcha for the frontend cutover.
+
+## Current-state (Power BI) scoring — deliberate, not canonical
+
+These endpoints reproduce the **Power BI current-state** numbers the dashboard was validated
+against: done = `dtDone IS NOT NULL` and category from `workTypeNow`. They do **not** use the
+canonical **at-lock** sprint scoring (`workTypeAtLock` + `statusNow IN (STATUS_IN__DONE)`) used
+by the model's `_score*` / `_reliabilityScore` helpers. Reconciling current-state vs canonical
+for a leadership view is a **separate, deliberate decision left open** — do not assume these
+tiles agree with sprint scores. See the two-definitions section in
+[Team Sprint Management](../../worker2/features/team-sprint-management.md).
+
+Verified against live prod (sprint 83): the **Conditional** KPI tile reads `workTypeAtLock`
+(72 pts) while the work-type pie reads `workTypeNow` (67 pts) — a real at-lock-vs-now
+divergence, by design, not a bug.
+
+## SQL safety (no bound params in `_Query`)
+
+`_Query` has no `?`/`:name` binding, so injection safety is by construction, matching the
+model's existing `_score*` helpers:
+
+- The sprint number is `(int)`-cast.
+- The `?category=` query-string value is **not interpolated raw** — it is mapped through a
+  value allowlist to the `_Model_Team_Task::WORK_TYPE__*` constants; an unrecognized category
+  is rejected, never placed into SQL.
+- Every other column/value in the query text is a trusted server-side constant.
+
+Work-type values in the `Team` schema are stored **UPPERCASE** (`COMMITTED` / `CONDITIONAL`
+/ `STRETCH` / `UNPLANNED`); the productionized code sources them from the
+`_Model_Team_Task::WORK_TYPE__*` constants rather than mixed-case literals (the prototype's
+`'Committed'` only worked because the collation is case-insensitive).
+
+## Registration (two dbchanges2 files)
+
+Registered as metadata, not a code deploy (see [Record Scripts](./record-scripts.md) for the
+full contract). Two migrations, both **id-agnostic resolve-by-route + `NOT EXISTS` guards** so
+they are re-runnable and environment-agnostic:
+
+- `dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql` — one `Core.Records` row
+  (`route 'sprints'` → `_Model_Team_Sprint`, with `name`/`description`, `aclDatabase = 'CORE'`
+  because `Team` is co-located on the core cluster) + six `Core.RecordScripts` rows.
+- `dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql` — the
+  `Client.AclRecordScripts` grant. It is a **CLIENT-DB** table, so it lives in the per-client
+  **`Client_True`** folder (roles **1 / 3 / 4**). Putting it in the generic `Client/` folder
+  would grant the internal dashboard to **every** tenant.
+
+## Data source note
+
+The core-cluster hosts/credentials the `Team` reads flow through live in api2 `Config/*.ini`
+(`[database]`) — never in knowledge or code.
+
+## Open items (frontend cutover)
+
+- Frontend `fetchEnvelope` must unwrap `data[<route>]` (see nesting above).
+- Replace the prototype's empty-placeholder `AUTH_TOKEN` with real Bearer-JWT auth, and
+  reconcile the ACL role (True 1/3/4) to the dashboard's auth identity.
+- Verify `Tasks_Developers` has a `UNIQUE (taskId, developerId)` key plus sprint/workType
+  indexes.
+- `pointsByDev` filters to a first-name allowlist (excludes non-roster devs) — keep that
+  allowlist in sync with the roster.
+
+## Change history
+
+- 2026-07-24 — Productionized the TOGa IQ sprint dashboard as six api2 Record Scripts on
+  `_Model_Team_Sprint` (`current`, `sprintTile ?category=`, `statusBreakdown`,
+  `workTypeBreakdown`, `pointsByDev`, `burndown`), replacing the local Express/mysql2
+  prototype with no api2 code change. Documented the **route-segment envelope nesting**
+  (`data[<route>]`), the deliberate Power BI current-state scoring (Conditional tile
+  `workTypeAtLock` 72 pts vs work-type pie `workTypeNow` 67 pts on sprint 83), UPPERCASE
+  work-type values sourced from `_Model_Team_Task::WORK_TYPE__*`, the `?category=` allowlist
+  as the `_Query` injection defense, and the two-file dbchanges2 registration (Core records
+  + `Client_True` ACL grant to roles 1/3/4). (kyalamarthi)
+
+## Related docs
+
+- [Record Scripts](./record-scripts.md) — the authoring/registration contract these follow.
+- [Team Sprint Management & Reporting](../../worker2/features/team-sprint-management.md) — the
+  worker2 producer and the metric definitions the SQL implements.
+- [api2 architecture](../architecture.md) — the metadata-driven `/v2` engine.
+</content>
+</invoke>

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

@@ -186,9 +186,11 @@ All sprint state lives in the Team database (`_underscore::DB_TEAM`). Core table
 **Column vocabularies & datetime columns (dashboard-relevant).** For current-state reporting the
 exact values matter:
 
-- **`workTypeNow` / `workTypeAtLock`** — enum `COMMITTED / CONDITIONAL / STRETCH / UNPLANNED`.
-  MySQL string comparison is **case-insensitive** by default, so `'Committed'`/`'STRETCH'`/etc.
-  all match regardless of case.
+- **`workTypeNow` / `workTypeAtLock`** — enum `COMMITTED / CONDITIONAL / STRETCH / UNPLANNED`,
+  stored **UPPERCASE** in prod. MySQL string comparison is **case-insensitive** by default, so
+  a mixed-case literal (`'Committed'`) still matches — but production code should source these
+  from the **`_Model_Team_Task::WORK_TYPE__*` constants** rather than typing literals (the api2
+  sprint-dashboard Record Scripts do this).
 - **`statusNow` / `statusAtLock` / `statusAtEnd`** — free-form varchar, values stored
   **lower-case**: `complete`, `to do`, `in progress`, `stage review`, `hotfix review`,
   `back-end review`, `ui review`, `on hold`, `roadblocked`, `awaiting client`, `rework`,
@@ -319,7 +321,9 @@ Points = `sprintPointsNow`; each task is assigned **one** segment via a SWITCH e
 3. else → the task's **`workTypeNow`** value (Committed / Conditional / Unplanned).
 
 Joined `Tasks → Tasks_Developers → Developers` and grouped by developer. Because the join is
-many-to-many, each assigned developer is credited the task's **full** `sprintPointsNow`.
+many-to-many, each assigned developer is credited the task's **full** `sprintPointsNow`. The
+chart also filters developers to a **first-name allowlist** (the active roster), so non-roster
+developers who happen to be assigned are excluded from the per-dev breakdown.
 
 ### Sprint Burndown (over working days)
 Plotted over **working days only** (Mon–Fri, ~10 per two-week sprint; call the count `N`,
@@ -350,12 +354,21 @@ middleware defaults every tile/chart endpoint to it when no `?sprint=` is suppli
 > [per-client database connections](../../_underscore/features/per-client-database-connections.md))
 > by a local Node/React + Express (mysql2) prototype that stands in for the api2 `/v2` engine and
 > returns the standard api2 envelope. The prototype's DB credentials live in an **uncommitted
-> `.env`** (never in the repo or this doc). When productionized, the tiles become api2 Record
-> Scripts registered via **dbchanges2** — see
-> [Record Scripts](../../api2/features/record-scripts.md).
+> `.env`** (never in the repo or this doc). The dashboard has since been **productionized**:
+> the tiles/charts are now six api2 Record Scripts on `_Model_Team_Sprint`, registered via
+> **dbchanges2** and granted to the True tenant — see
+> [TOGa IQ Sprint Dashboard API](../../api2/features/sprint-dashboard-api.md) and the general
+> [Record Scripts](../../api2/features/record-scripts.md) contract. The Express stand-in is
+> retired.
 
 ## Change history
 
+- 2026-07-24 — Productionized the dashboard: the metric definitions above are now served by six
+  api2 Record Scripts on `_Model_Team_Sprint` (see
+  [Sprint Dashboard API](../../api2/features/sprint-dashboard-api.md)), retiring the Express
+  prototype. Refined the data model: work-type values are stored **UPPERCASE** and should be
+  sourced from the `_Model_Team_Task::WORK_TYPE__*` constants; the Sprint-Points-By-Dev chart
+  filters to a **first-name roster allowlist**. (kyalamarthi)
 - 2026-07-24 — Documented the full **Power BI dashboard metric definitions (DAX → SQL)** for the
   TOGa IQ sprint dashboard: KPI tiles by work type (with the non-uniformity that **Conditional
   filters on `workTypeAtLock`** while Committed/Stretch/Unplanned filter on `workTypeNow`), the

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 38 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) — 16 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 17 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/true/profile.md

@@ -6,12 +6,13 @@ apps:
   - tools
   - worker2
   - dbchanges2
+  - api2
 project: _Underscore
 client: true
 type: profile
 status: active
-updated: 2026-06-29
-owners: [jcardinal]
+updated: 2026-07-24
+owners: [jcardinal, kyalamarthi]
 files: []
 related:
   - clients/true/features/users-personas-data-model.md
@@ -28,6 +29,11 @@ by staff role (e.g. the planned Toolbox app) reads its `Users` / `Personas` mode
 - **Client identifier:** `True`
 - **SSO mapper:** `_Model_True_ClientAuthentication` (base; matches by email from NameID)
 
+The internal **TOGa IQ sprint dashboard** is served to True from **api2** as six Record
+Scripts on `_Model_Team_Sprint` (over the `Team` schema), with the `AclRecordScripts` grant
+scoped to True roles 1/3/4 — hence `api2` is in this client's `apps`. See
+[Sprint Dashboard API](../../2.0/apps/api2/features/sprint-dashboard-api.md).
+
 The **Tools** app (1.0; repo `tools`) authenticates True users via **SSO** through
 `saml.togahub.com` and reads the `Client_True` DB **read-only** to gate its internal tooling by
 staff persona (see `1.0/apps/tools/`). Its gateway return domain is registered in `Core.Domains`

package/knowledge/sessions/2026-07-24-sprint-dashboard-kyalamarthi.md

@@ -0,0 +1,72 @@
+---
+type: session
+slug: sprint-dashboard
+title: TOGa IQ Sprint Dashboard prototype (React + Express stand-in)
+author: kyalamarthi
+repos: [test]
+framework: "standalone"
+client: shared
+status: active
+created: 2026-07-24
+updated: 2026-07-24
+---
+
+# Session: sprint-dashboard
+**Date:** 2026-07-24
+**Project/Repo:** test (standalone Node/React prototype in `@krishna/React`; reads 2.0 TOGa IQ `Team` data)
+**Task:** Build a Power BI-parity TOGa IQ sprint dashboard in `test/@krishna/React` — React (CDN, no build) frontend + Express/mysql2 backend that stands in for the api2 `/v2` engine — with KPI tiles, Status/Work Type pies, Sprint Burndown, Sprint Points By Dev, and a Time-Progression header, all auto-resolving the current sprint from the live `Team` schema.
+
+---
+
+## What WORKED
+- **`backend/server.js`** — Express + a single mysql2 pool, `MOCK_MODE` switch, api2 `/v2` envelope (`{transactionId,timestamp,isSuccess,status,error,messages,meta,data}`), and `express.static` serving the frontend with `Cache-Control: no-store`. Live-verified against the `Team` schema (core-cluster reader): server boots "LIVE (querying MySQL)".
+- **Parameterized tile endpoint** `GET /v2/sprints/tile?category=committed|conditional|stretch|unplanned` driven by a `CATEGORIES` map (per-tile `column`+`value`+mock) and a `COLUMN_ALLOWLIST`. Injection-safe: `value`/`sprint` are bound `?` params, the work-type **column** is only ever taken from the server-side allowlist. Verified all four categories, a clean **400** on `category=bogus`, and the back-compat `/v2/sprints/committed-tile` alias.
+- **Status rollup** (`/status-breakdown`) mirrors the Power BI "Status now Category Group" SWITCH (default→Review); returns **both `count` and `points`** per bucket. **Work Type pie** (`/worktype-breakdown`) = `SUM(sprintPointsNow) GROUP BY workTypeNow`. **Points-by-Dev** (`/points-by-dev`) joins `Tasks→Tasks_Developers→Developers` (many-to-many, full points per dev) with the "New Status" SWITCH (`dtCompleted`→Complete; else statusNow-not-in-active→In Review; else workTypeNow). **Burndown** (`/burndown`) = Target `CCU×(1−day/N)` + actual `total−done-to-date` (CCU vs CCUS) over Mon–Fri working days, actuals stop at today. All live-verified for sprint 83.
+- **Current-sprint auto-resolution** — a `/v2/sprints` middleware defaults every endpoint to the sprint whose range contains today (`CURDATE() BETWEEN dateStart AND dateEnd`, else most recently started), and `GET /v2/sprints/current` feeds the header. Verified → auto-resolves to **sprint 83** (Jul 22–Aug 4); no hardcoded sprint anywhere.
+- **`frontend/dashboard.html`** — 2×2 grid (tiles top; Status/Work Type left column `1fr`; Burndown/Points-by-Dev right column `2fr`), fits one viewport, no scroll. Reusable `Donut`/`PieChart`/`Legend`/`StackedBarChart`/`BurndownChart` + shared `fetchEnvelope`/`useApi`. Time-Progression header bar (business hours) + Full-screen button. Verified via browser screenshots and `evaluate_script` (10px row gaps, `docScrollH == viewportH`).
+- **`frontend/dashboard1.html`** — copy of dashboard.html, since customized into a **donut** variant (center totals + value legend). `USE_MOCK=false` (live). Its **Status donut shows POINTS** (center "208 points", legend point values) via `b.points` + `unit="points"`.
+- **Knowledge captured** — `/capture` UPDATED `knowledge/2.0/apps/worker2/features/team-sprint-management.md` with the full DAX→SQL metric definitions + Team-schema precision; **pushed to `_main`**.
+
+## What did NOT work — DO NOT RETRY THESE
+- **Layout attempt #1:** `.page { min-height:100vh }` + `.main-grid { grid-template-rows: minmax(240px,1fr) minmax(240px,1fr) }`. On a 768px viewport the grid grew to **750px** and the bottom row was clipped ~170px (`document.scrollHeight = 939 > 768`). Reason: `min-height` + the `minmax` row **minimums** let the grid exceed the viewport instead of shrinking.
+- **Layout attempt #2:** `.page { height:100vh; overflow:hidden }` + `grid-template-rows: 1fr 1fr` **alone** → rows still **overlapped by exactly 20px** (row-1 cards ran 169→490, row-2 started at 470). Reason: cards were `box-sizing: content-box`, so their `14px×2` padding + `1px×2` border added **30px on top** of the computed `290.5px` track height → each card rendered **321px** and overflowed its grid row. **Root fix:** global `*, *::before, *::after { box-sizing: border-box }`.
+- **Absolutely-positioning the chart SVGs** (`.chart-fill { position:absolute; inset:0 }`) did **not** fix the row overlap on its own — the overlap was the card padding (content-box), not the SVG's intrinsic height. (Kept the absolute-fill regardless — it's correct for scaling charts to their cell — but it was not the fix.)
+- **`/committed-tile` alias via `app._router.handle(req,res)`** — reached into Express internals and was fragile. Refactored both routes to call a shared `serveTile()` function instead.
+- **First full-content Write to each new file** was denied once by the fact-forcing gate (keys on path, ignores content). Use stub-first for large new files to avoid re-emitting the whole body.
+
+## Not tried yet (candidates for next session)
+- **Productionize the tiles as real api2 Record Scripts** (`_Model_Team_Sprint::sprintTile` on `_underscore`, registered via **dbchanges2**) to replace the Express stand-in. `sql/register_committed_tile_endpoint.sql` is the starting template. This is the natural next step (user asked how the real data path works: worker2 ingests → Team DB → api2 Record Script serves).
+- **Auth** — `AUTH_TOKEN` in the frontend is an empty placeholder; wire the Bearer JWT + confirm header names against a real `/v2/auth` call.
+- **Reconcile current-state vs canonical scoring** — dashboard uses Power BI current-state (`dtDone`+`workTypeNow`); canonical scoring uses `statusNow IN DONE`+`workTypeAtLock`. Decide which a leadership-facing view should use.
+- **Burndown day-numbering** — currently 1-based (Target starts at 90% on day 1, hits 0 on day N). Confirm against Power BI whether it should be 0-based (start at 100%). One-char change (`k=i` vs `k=i+1`).
+- **Multi-dev point splitting** — Points-by-Dev currently credits each assigned dev the task's full points (matches the KB rule). Add a split option only if Power BI splits.
+- **Time-progression live refresh** — currently a snapshot computed on page load; add a timer if a wall display needs it to tick.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| `test/@krishna/React/backend/server.js` | Created/rewritten | Live-verified; current-sprint middleware + 6 `/v2/sprints/*` endpoints; injection-safe; `no-store`; `FALLBACK_SPRINT=82` only if table empty. |
+| `test/@krishna/React/frontend/dashboard.html` | Created | 2×2 dashboard; Status shows task **counts**; box-sizing fix applied; live. |
+| `test/@krishna/React/frontend/dashboard1.html` | Created (copy, then edited) | Donut variant; `USE_MOCK=false`; Status donut shows **points** (`unit="points"`); live. |
+| `test/@krishna/React/frontend/committed-tile.html` | Untouched | Original single-tile page; left as-is. |
+| `test/@krishna/React/sql/tile_query.sql` | Created | Parameterized query reference (documents column/value per tile). |
+| `test/@krishna/React/sql/committed_tile.sql`, `register_committed_tile_endpoint.sql` | Pre-existing | The latter is the api2 Record Script registration template for productionizing. |
+| `test/@krishna/React/backend/.env` | Present, NOT committed | `MOCK_MODE=false`, `DB_NAME=Team`, core-cluster reader host + `admin` user. Credentials live here only — never commit. |
+| `knowledge/2.0/apps/worker2/features/team-sprint-management.md` | UPDATED + pushed | DAX→SQL metric definitions + Team schema vocabularies (`dtDone` vs `dtCompleted`, many-to-many points). |
+
+## Decisions made
+- **One parameterized tile endpoint** over four near-identical routes (DRY). Rejected: separate `committed-tile`/`stretch-tile`/… files (the original single-tile approach) — too much duplication for a 4-tile dashboard.
+- **Backend resolves the current sprint per request** (middleware) and the frontend sends **no `?sprint=`**. Rationale: "always show the current sprint, never hardcode." Accepted the minor cost of an extra resolve query per endpoint; `/current` skips the middleware to avoid a double query.
+- **Express + mysql2 as a local api2 stand-in** that imitates the `/v2` envelope, so the React frontend is drop-in for the real api2 later. Rejected: querying the DB from the browser (impossible/insecure) or building the real Record Script now (out of scope for the prototype).
+- **Knowledge placed in `worker2/features/team-sprint-management.md`**, not a new `test/` doc. Rationale: that doc already owns the Team-schema + sprint-metric subject and is cross-linked from api2; the `test` sandbox's per-developer folders are excluded from the KB.
+- **`dashboard1.html` is a separate file** for the donut/points variant; `dashboard.html` stays on task counts. Rationale: user wanted a distinct second dashboard without changing the first.
+- **Global `box-sizing: border-box`** — the correct fix for the row-overlap (not min-heights, not absolute positioning).
+
+## Blockers
+None functional. Operational note: **the dev server does not persist across Claude sessions** — it must be restarted each time (`cd test/@krishna/React/backend && npm start`). It also serves `dashboard1.html` automatically (static folder).
+
+## Exact next step
+> Restart the server (`cd c:/www/test/@krishna/React/backend && npm start`) and open `http://localhost:3001/dashboard1.html` to confirm it still auto-resolves the current sprint. Then, to move off the prototype stand-in, implement the **api2 Record Script** version of the tiles — `_Model_Team_Sprint::sprintTile()` on `_underscore`, registered via **dbchanges2** using `sql/register_committed_tile_endpoint.sql` as the template — so the dashboard fetches through the real api2/`_underscore` path (worker2 keeps populating the `Team` tables; api2 serves them).
+
+---
+_Saved by /session-save on 2026-07-24_

package/package.json

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