toga-ai 1.0.434 → 1.0.436

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/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.434",
+  "version": "1.0.436",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",