toga-ai 1.0.434 → 1.0.435

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-07-24
 owners: ["jcardinal", "kyalamarthi"]
 files:
   - worker2/Worker/Team/Sprint.php
@@ -178,7 +178,28 @@ All sprint state lives in the Team database (`_underscore::DB_TEAM`). Core table
   (`reworkEvents`, `hygieneMisses`, `unjustifiedStatusChanges`,
   `unjustifiedWorkEffortChanges`, `timeInProgressThisSprint`). Task statuses use the
   `_Model_Team_Task::STATUS_*` constants (e.g. `STATUS_IN__DONE`).
-- **`Tasks_Developers`** — task ↔ developer assignment join table.
+- **`Tasks_Developers`** — task ↔ developer assignment join table. This is a **many-to-many**
+  relationship: a task can have several assigned developers. Any per-developer points rollup
+  (e.g. "points by dev") credits **each** assigned developer the task's *full* points — the
+  points are not split across assignees.
+
+**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.
+- **`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`,
+  `pseudocode`, `ongoing`, `archived` (list is open-ended — treat unknown values as "review", see
+  the status rollup below).
+- **`dtDone` vs `dtCompleted` are two different datetime columns** and are **not**
+  interchangeable. `dtDone IS NOT NULL` is the Power BI "done" test used by the KPI tiles and
+  burndown; `dtCompleted IS NOT NULL` is the "Complete" test used by the per-dev segment
+  breakdown. Do not substitute one for the other.
+- **`sprintPointsNow` / `sprintPointsAtLock`** — the points measured by every dashboard metric
+  below use `sprintPointsNow` (current state), not the at-lock value.
 
 `CaptureSprintEnd()` and `CaptureSprintDaily()` are the private sync routines that walk the
 ClickUp sprint list (paginated, `include_timl=true`), upsert `Sprints`/`Developers`/`Tasks`/
@@ -249,8 +270,102 @@ Neither is "wrong" — they answer different questions (scored performance vs. l
 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.
 
+## Power BI dashboard metric definitions (DAX → SQL)
+
+These are the **current-state / Power BI-parity** definitions behind the TOGa IQ sprint
+dashboard (the same set of tiles and charts the Power BI report shows). They translate the
+Power BI DAX into SQL against the `Team` schema so any consumer — a worker2 report, an api2
+Record Script tile, or a local prototype — produces numbers that match Power BI. All of them
+use current-state columns (`workTypeNow`, `statusNow`, `sprintPointsNow`) except where noted,
+and follow the **Power BI / current-state definition** above (`dtDone IS NOT NULL`), not the
+canonical scoring definition.
+
+### KPI tiles — points by work type
+Per tile: `points = SUM(sprintPointsNow)`, `done = dtDone IS NOT NULL`, filtered by a work-type
+column + value. **Non-uniform on purpose — the column differs by tile:**
+
+- **Committed / Stretch / Unplanned** filter on **`workTypeNow`** (`'Committed'` / `'STRETCH'` /
+  `'UNPLANNED'`).
+- **Conditional** filters on **`workTypeAtLock` = `'Conditional'`** — a *different column*
+  (the at-lock baseline), not `workTypeNow`. Miss this and the Conditional tile is wrong.
+
+MySQL string comparison is case-insensitive, so casing of the literal does not matter.
+
+### Status rollup (status pie) — "Status now Category Group" DAX SWITCH
+A `SWITCH` over `statusNow` (case-insensitive) into five buckets:
+
+| Bucket | `statusNow` values |
+|--------|--------------------|
+| **Complete** | `complete`, `archived` |
+| **In Progress** | `in progress`, `rework` |
+| **Stalled** | `on hold`, `roadblocked`, `awaiting client` |
+| **To Do** | `to do` |
+| **Review** | **everything else (SWITCH default)** — all the review-type statuses fall here |
+
+The default → **Review** case is load-bearing: any new/unknown status is a Review, not an error.
+Shown by **task count** (dashboard.html) or by **`SUM(sprintPointsNow)`** (dashboard1.html donut
+variant) — same rollup, different measure.
+
+### Work Type pie
+`SUM(sprintPointsNow) GROUP BY workTypeNow` — all four work-type values live in `workTypeNow` for
+this chart (unlike the KPI tiles, Conditional is *not* read from `workTypeAtLock` here).
+
+### Sprint Points By Dev — "New Status" DAX SWITCH
+Points = `sprintPointsNow`; each task is assigned **one** segment via a SWITCH evaluated in order:
+
+1. `dtCompleted IS NOT NULL` → **Complete** (note: `dtCompleted`, not `dtDone`).
+2. else `statusNow NOT IN ('to do','in progress','rework','on hold','roadblocked','awaiting client')`
+   → **In Review**.
+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`.
+
+### Sprint Burndown (over working days)
+Plotted over **working days only** (Mon–Fri, ~10 per two-week sprint; call the count `N`,
+`dayNumber` 1-based):
+
+- **Target line:** `CCU_total × (1 − dayNumber / N)`, clamped to `≥ 0`.
+- **Committed actual:** `CCU_total − (CCU points with dtDone on or before that day)`.
+- **All actual:** `CCUS_total − (CCUS points done-to-date)`.
+- Actual series **stop at today** (no future points).
+
+Two work-type universes: **CCU** = Committed + Conditional + Unplanned; **CCUS** = CCU + Stretch.
+
+### Time Progression
+Business-hours elapsed vs. total. Working days are Mon–Fri only, each **8h (09:00–17:00)**, so a
+10-working-day sprint = **80h**. `% = elapsed business hours ÷ 80`, using the local clock.
+
+### Current-sprint auto-resolution
+Dashboards must **never hardcode a sprint number.** Resolve the current sprint as:
+
+1. the sprint whose date range contains today: `CURDATE() BETWEEN dateStart AND dateEnd`;
+2. else the most recently started: `ORDER BY (dateStart <= CURDATE()) DESC, dateStart DESC LIMIT 1`.
+
+In the local prototype this is exposed as `GET /v2/sprints/current`, and a `/v2/sprints`
+middleware defaults every tile/chart endpoint to it when no `?sprint=` is supplied.
+
+> **Prototype provenance & credentials.** These definitions were reverse-engineered and verified
+> against the live `Team` schema (which resolves to the **core cluster reader** — see
+> [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).
+
 ## Change history
 
+- 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
+  status-rollup SWITCH (default → Review), the work-type pie, the per-dev "New Status" segment
+  SWITCH (`dtCompleted`-based, many-to-many full-points-per-dev), the burndown target/actual over
+  working days (CCU vs CCUS), time-progression (Mon–Fri 8h days, 80h/sprint), and current-sprint
+  auto-resolution. Enriched the data model with column vocabularies (workType/status enums), the
+  **`dtDone` vs `dtCompleted`** distinction, and the Tasks↔Developers many-to-many points rule.
+  Reverse-engineered/verified via a local Node/React + Express prototype (creds in uncommitted
+  `.env`). (kyalamarthi)
 - 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

package/package.json

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