toga-ai 1.0.184 → 1.0.186

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform | src/main.tsx, src/App.tsx, src/routes.tsx, src/contexts/AuthContext.tsx, src/contexts/helpers/getLoginSettings.ts, src/api/axiosInstance.ts, src/stores/, src/themeConfig/ThemeContext.tsx, src/fieldsConfig/index.ts, src/hooks/useAssignClientFields.ts, vite.config.ts, package.json |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
+| [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |

package/knowledge/2.0/apps/toga2-commerce/features/cart-notification-emails.md

@@ -14,7 +14,9 @@ files:
   - src/stores/useEmailOptionsStore.ts
   - src/stores/useCartSalesQuoteZu.ts
   - src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts
-related: []
+related:
+  - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
 ---
 
 ## Summary

package/knowledge/2.0/apps/toga2-commerce/features/cart-page-config-architecture.md

@@ -0,0 +1,155 @@
+---
+title: Cart Page — config-driven form architecture (current state + planned refactor)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-24
+owners: ["apeterson"]
+files:
+  - src/pages/Cart/CartPage.tsx
+  - src/pages/Cart/view/cartForm/CartForm.tsx
+  - src/pages/Cart/view/cartForm/CartFormSection.tsx
+  - src/pages/Cart/view/cartForm/CartFormRenderer.tsx
+  - src/pages/Cart/view/EditCart.tsx
+  - src/pages/Cart/view/EditOrder.tsx
+  - src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts
+  - src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts
+  - src/hooks/useAssignClientFields.ts
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
+  - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
+  - 2.0/apps/toga25-supply/features/client-configurable-fields.md
+---
+
+## Summary
+
+The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. As of
+`_production` it is **config-driven at the field level but hardcoded at the section level**, and it
+renders the cart through **two near-duplicate dual-mode forms** (cart-checkout vs edit-order). A
+config-driven refactor is **planned but not yet implemented** (see *Planned refactor* below). This
+doc records both the current architecture and the agreed target so the work can be picked up without
+re-deriving it. The cart consumes the per-tenant `CARTPAGE.ts` config resolved through
+`useAssignClientFields` — see [client-fields](client-fields.md) for that resolution model.
+
+## Current architecture (`_production`)
+
+```
+CartPage.tsx (~1052 lines)        owns useForm(), watched values, all handlers; picks EditCart vs EditOrder
+  ├─ EditCart.tsx (~596)          cart-checkout mode: sync useEffects + renders <CartForm> (~30 props)
+  └─ EditOrder.tsx (~665)         edit-order mode:    near-duplicate sync useEffects + renders <CartForm>
+       └─ CartForm.tsx (~1074)    HARDCODED section layout (summary / orderFor / shippingAddress /
+                                  costCenter / notifications / confirm) as JSX; calls CartFormSection per section
+            └─ CartFormSection.tsx (~296)   ALREADY config-driven: renders inputs from a `fields` prop,
+                                            honoring visibleWhen / inputButtons / labelButton / isEditable / inputType
+```
+
+`useEditOrderOrEditCartViewModel.ts` is a dispatcher hook that returns one view-model or the other
+based on `inEditMode`. `CartFormRenderer.tsx` exists only on the `implement-config` spike branch
+(reads `section.fields`); it is **not on `_production`**.
+
+### What is already config-driven (keep it)
+- **Field-level rendering** — `CartFormSection` maps over a section's input array and interprets
+  `visibleWhen`, `inputButtons`, `labelButton`, `isEditable`/`isVisible`, `inputType`
+  (advancedSelect / BaseInput / display variants). This mirrors toga2.5's `renderField`/`BaseInput`.
+- **Per-tenant `CARTPAGE.ts`** per client/language/role, resolved via `useAssignClientFields`
+  (React-Query cached) — the same resolution model as toga2.5's `useClientFields`.
+
+### What is NOT config-driven / is duplicated (the refactor target)
+- **Section layout is code, not config** — `CartForm.tsx` (~1074 lines) hardcodes which sections
+  exist and their order in JSX.
+- **The form is built twice** — `EditCart` and `EditOrder` share ~80% of their logic but are
+  separate files, each holding its own copy of the mount / orderFor-cascade / form-sync effects.
+- **Prop drilling** — `CartPage → EditCart/EditOrder → CartForm → CartFormSection` passes ~30 props
+  by hand.
+
+## Gotchas (current state — all pre-existing on `_production`)
+
+- **Config-key naming drift.** `CARTPAGE.ts` uses `inputs:` for the `orderFor` section but
+  `formFields:` for `shippingAddress` / `costCenter` / `notifications`, while `CartFormSection`
+  reads a `fields` prop. Three names for one concept; `CartForm` hand-maps each section's array into
+  the `fields` prop. This pre-existing drift is what tripped the prior spike. (Target: rename all to
+  a single `fields` key.)
+- **`useForm` is seeded with a hardcoded union of every client's fields.** `CartPage.tsx`
+  (~lines 230–258) calls `useForm` with one static `defaultValues` object that is the **union** of
+  all clients' fields, with the **COMPASS-only magic shipping-method UUID `087a9d0b-…` baked in**.
+  Two mode-change `reset()` effects (~lines 267, 282) re-seed from that same union shape. This is
+  wrong for per-client field sets: it registers fields a client never renders and bakes one client's
+  default into all of them, and risks RHF controlled/uncontrolled warnings.
+- **Client differences are hardcoded, not config.** Examples observed: COMPASS renders
+  `DuplicateKitGuardrail`, QUAD does not; COMPASS seeds the cart form (cost center / manager / emails)
+  from the order-for user, QUAD does not. These are per-client conditionals in cart code today.
+- `useAssignClientFields.ts` returns `FIELDS?.[clientName]?.[language]?.[role]` with no transform —
+  there is no fallback (a missing combo renders empty). See [client-fields](client-fields.md).
+
+## Planned refactor (DECIDED 2026-06-24 — plan only, not implemented)
+
+**Approach (Route B): rebuild the config-driven cart from the working `_production` branch**, using
+the broken `implement-config` spike branch only as a *reference blueprint* (its target-shaped files
+— `CartFormContext`, `CartFormRenderer`, `useCartFormViewModel`, `useCartFormSync`, standalone
+sections — are architecturally sound but mid-rename and non-functional; lift code where correct,
+do not finish that branch). Rationale: the spike's −3,940-line deletion silently dropped real
+behavior (email seeding, duplicate-email validation, edit-order cost-center/address). The risk is
+**behavior parity, not architecture**, so migrate in verifiable slices against the running
+`_production` app as the oracle. Target pattern = toga2.5 (`toga25-supply`): one form, section
+layout from config, state via context, consolidated sync effects.
+
+Plan document (in the toga2-commerce repo, not in the KB):
+`docs/reviews/implement-config-cart-refactor-PLAN.md`.
+
+Phases: **P0** pin a behavior oracle + inventory hardcoded client branches · **P1** behavior-neutral
+config-key rename (`inputs`/`formFields` → single `fields`) · **P2** `CartFormContext` to kill
+prop-drilling + config-derived form defaults · **P3** consolidate the dual view-models and the three
+sync effects into `useCartFormViewModel` + `useCartFormSync`, branching on `inEditMode` once · **P4**
+drive section layout from config (`type` + dispatch map with explicit fallback) + capability flags,
+then delete `CartForm`/`EditCart`/`EditOrder` · **P5** hydration memo + standards sweep (magic UUID
+removed from code, lives in config).
+
+### Key principle established — client behavior comes from config, never `if (client === ...)`
+
+A new client must be onboarded by **editing `CARTPAGE.ts`**, not by adding `clientSlug` branches to
+cart code. Two flavors, modeled exactly on toga2.5's SalesOrder approval pattern (config carries
+`approvalActionStatuses` + `approveButtonRule:{type:"requireStepTwoAssigned"}`; a pure
+`evaluateApproveRule(rule, ctx)` switch over a discriminated union in `useApprovalModalViewModel.tsx`
+interprets it — the component never knows it is COMPASS):
+
+1. **Capability flags** — pure on/off presence, no runtime data:
+   `capabilities.duplicateKitGuardrail.isEnabled` (COMPASS true, QUAD omits). The renderer reads the
+   flag to decide whether to mount `DuplicateKitGuardrail`.
+2. **Named rules** — conditional logic depending on runtime data, declared as `{ type }` and
+   evaluated generically: e.g. `orderForSeedRules: [{type:"seedCostCenterFromUser"}, …]` iterated by
+   an `applySeedRule` evaluator in `useCartFormSync` (mirrors `evaluateApproveRule`). QUAD omits the
+   rules → seeds nothing, no branch.
+
+### Config-derived form defaults (cart-specific extension of the toga2.5 pattern)
+
+The config already enumerates exactly the fields a client renders, so derive `useForm`
+`defaultValues` from it via a `buildCartDefaultValues(fields, ctx)` builder with three sources:
+- per-field `defaultValue` in config (where the COMPASS shipping UUID **moves to**; QUAD omits it);
+- type-derived empties (`text`/`textArea`→`""`, `checkbox`→`false`,
+  `select`/`advancedSelect`→`{uuid:"",name:""}`);
+- dynamic `defaultValueRules` reusing the same `{type}` rule shape
+  (e.g. `currentUserWhenNotEditable`, `fromSalesOrderErpEntity`).
+
+The two mode-change `reset()` effects call the **same builder** so defaults and rendered inputs can
+never drift. Noted honestly: toga2.5 uses a *static* `emptyItemDefaults` because its item-create form
+is a single shape; the cart is genuinely multi-shape per client, so config-derived defaults is a
+**cart-specific extension** of toga2.5's philosophy, not a literal copy.
+
+> The general "no `if (client === ...)` — drive client behavior from config via capability flags and
+> named rules evaluated by a generic evaluator" rule, applied across 2.0 React frontends beyond just
+> the cart, is being proposed as a team **standard** separately (senior-owned / pending approval).
+
+## Change history
+- 2026-06-24 — Initial: documented the current `_production` Cart architecture (field-level config
+  via `CartFormSection`, hardcoded section layout in `CartForm`, dual `EditCart`/`EditOrder` forms +
+  dispatcher VM, prop-drilling), its gotchas (config-key drift `inputs`/`formFields`/`fields`,
+  hardcoded union `defaultValues` with the COMPASS magic shipping UUID, hardcoded per-client
+  branches), and the DECIDED config-driven refactor approach (rebuild from `_production`, branch as
+  blueprint; capability flags + named rules à la toga2.5 approval; config-derived
+  `buildCartDefaultValues`). Plan only — not implemented (apeterson)
+</content>
+</invoke>

package/knowledge/2.0/apps/toga2-commerce/features/client-fields.md

@@ -22,6 +22,7 @@ related:
   - 2.0/apps/toga2-commerce/architecture.md
   - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
   - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
+  - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
 ---
 
 ## Summary

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

@@ -12,5 +12,6 @@
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
+| [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 |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
 | [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

@@ -0,0 +1,203 @@
+---
+title: Team Sprint Management & Reporting
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-24
+owners: ["jcardinal"]
+files:
+  - worker2/Worker/Team/Sprint.php
+related:
+  - ../architecture.md
+  - ./creating-worker-actions.md
+  - ./clickup-work-type-automation.md
+  - ./clickup-project-routing.md
+---
+
+## Summary
+
+`_Worker_Team_Sprint` (file `Worker/Team/Sprint.php`) is the engine behind TOGA's internal
+**development-sprint process and reporting**. It is an `abstract` worker class of `static`
+methods — each public method is a dispatchable worker action (`Team/Sprint/<Method>`, e.g.
+`Team/Sprint/SprintEnd`) invoked on a schedule via `_Worker::runTask()`.
+
+The feature mirrors the team's two-week (`SPRINT_LENGTH_DAYS = 14`) ClickUp-based sprint
+ceremony into the `DB_TEAM` database, then produces:
+
+- **Warning emails** before sprint-end capture and before sprint lock.
+- A **Sprint Lock** snapshot that freezes each task's committed/planned state ("at lock").
+- **Daily** leadership progress reports during the sprint.
+- A comprehensive **Sprint End** run that scores every developer across four metrics,
+  emails per-developer report workbooks and a leadership summary workbook.
+- **AI-generated Release Notes** (via TOGa IQ) emailed to leadership.
+
+ClickUp is the source of truth for tasks/assignees; `DB_TEAM` is the durable store of
+sprint history and computed metrics; Excel (`PhpOffice\PhpSpreadsheet`) is the report
+format; `_Email` delivers everything.
+
+## Key files / entry points
+
+- `Worker/Team/Sprint.php` — the entire feature (one abstract class, static methods).
+- `initialize()` — registers the `Logs_True` DB connection used for ClickUp API logging.
+- ClickUp config lives in class constants: `CLICKUP_TEAM_ID`, `CLICKUP_DEV_SPRINTS_FOLDER_ID`
+  (the folder whose child lists are the sprints), and the API access token.
+- AI config constants: `AI_API_ENDPOINT` (TOGa IQ `…/api/ai/generate`), `AI_MODEL_ID`
+  (`bedrock/us.anthropic.claude-haiku-4-5-…`), temperature, max-tokens, timeout.
+- Report distribution: `SEND_LEADERSHIP_REPORTS_TO` (leadership email list);
+  `SEND_EMAILS_FROM` / `SEND_EMAILS_FROM_NAME`.
+
+> **Dispatch reminder (2.0 worker contract).** Action `Team/Sprint/SprintEnd` routes to
+> `_Worker_Team_Sprint::SprintEnd`. New actions are only reachable once registered as a
+> `CronJobs` row (or webhook route). See [creating-worker-actions](./creating-worker-actions.md).
+
+## The sprint lifecycle (and which action runs when)
+
+A sprint runs ~14 days. Across the cycle these actions fire (scheduled as crons):
+
+1. **Sprint launch day, 8:30 AM** — `SendSprintEndWarnings` and `SendSprintLockWarnings`
+   email every developer who had a task in the latest sprint, reminding them to (a) finalize
+   the *previous* sprint's task data before the 9:00 AM End capture, and (b) get their *new*
+   sprint commitments ready to lock before the 9:45 AM launch ceremony.
+2. **~9:00 AM** — `SprintEnd` captures and scores the just-finished sprint, emails reports,
+   and (optionally) sends release notes.
+3. **~9:45 AM (after launch ceremony)** — `SprintLock` freezes the new sprint's plan.
+4. **Daily during the sprint** — `SprintDaily` emails leadership a progress dashboard.
+
+Most methods accept an optional `$sprint` number; when omitted they resolve the relevant
+sprint by date via `getSprint()` (which returns the sprint whose `dateStart…dateEnd` range
+contains today, or, for end-of-sprint, the previous sprint).
+
+## Public actions (entry points)
+
+### `SendSprintEndWarnings()` / `SendSprintLockWarnings()`
+Look up the latest `Sprints` row, find every distinct developer with a task in that sprint
+(`Developers ⋈ Tasks_Developers ⋈ Tasks`), and email each a templated reminder. End-warning =
+"clean up your data before the 9:00 AM End capture"; Lock-warning = "have your commitments
+ready before the 9:45 AM lock; work added after lock is treated as unplanned/interrupt work."
+Both send via the `Notification/Email/Send` worker action.
+
+### `SprintLock($sprint = null, $captureSprintLock = true, $generateSprintLockReport = true, $allowUnplannedTasks = false)`
+Freezes the sprint's plan at launch time. Optionally re-captures ClickUp data first, then for
+each task records the **"at lock" baseline** — `workTypeAtLock`, `sprintPointsAtLock`,
+`statusAtLock` — and initializes the per-sprint tracking counters (rework events, unjustified
+status/work-effort changes, in-progress time). These at-lock values are what later metrics
+measure *against*. If the target sprint list cannot be found in ClickUp it emails a leadership
+alert. With `$generateSprintLockReport`, emits an Excel lock report of committed/conditional/
+unplanned/stretch points and tasks. When `$allowUnplannedTasks` is false, tasks appearing
+after lock with an UNPLANNED work type are flagged.
+
+### `SprintDaily($sprint = null, …)`
+In-sprint **leadership dashboard**, read-only with respect to metrics. Optionally re-captures
+ClickUp data, then builds a multi-sheet workbook:
+- **Dashboard** — sprint progress by *time elapsed* vs. *points completed* (and the
+  difference, i.e. ahead/behind pace); counts of tasks in attention statuses (Roadblocked,
+  On Hold, Awaiting Client, the various Review states); points/tasks by work type.
+- **Team Summary** — per-developer committed/conditional/unplanned/stretch completion plus
+  N-sprint historical averages.
+- **Stalled Task Detail** — tasks in Roadblocked / Awaiting Client / On Hold with the reason.
+Emailed to the leadership list as `TeamSprintDailyReport_Sprint{N}_{date}.xlsx`.
+
+### `SprintEnd($sprint = null, …)`
+The largest method and the heart of the feature. Phases:
+1. **Resolve** the target (previous) sprint and its developers; optionally call
+   `CaptureSprintEnd()` to sync the final ClickUp state into `DB_TEAM`.
+2. **Score every developer** across the four metrics below.
+3. **Per-developer report workbook** (Dashboard, Team Summary, Sprint History, Task Detail,
+   and a Score-Trends chart over the last `SPRINTS_BACK_FOR_AVERAGES` sprints), emailed to
+   each developer.
+4. **Leadership summary workbook** (team-wide dashboard, all-developer summary with a
+   *recommended commitment* for next sprint, and stalled-task detail), emailed to leadership.
+5. Optionally call the release-notes generator.
+
+### `SendReleaseNotes($sprint = null)`
+Pulls every **completed** task in the sprint (`statusNow IN (…DONE)`) into a CSV of
+`workType, taskType, stakeholders, applications, sprintPoints, title`, then POSTs it to the
+TOGa IQ AI endpoint with a detailed system prompt that rewrites technical task titles into
+business-friendly, stakeholder-grouped HTML release notes. The returned HTML (code fences
+stripped) is emailed to the leadership list as "Sprint N Release Notes".
+
+## The scoring model (Sprint End)
+
+Each developer receives four 0–100 sub-scores and a weighted **Final Score**:
+
+| Metric | What it measures | Penalized by |
+|--------|------------------|--------------|
+| **Reliability** | Did they deliver what they committed to | Committed points/tasks not completed |
+| **Quality** | Did the work hold up | Rework events |
+| **Hygiene** | Was ClickUp data kept clean | Missing "Task Knowledge" / "Work Knowledge" custom fields (`hygieneMisses`) |
+| **Integrity** | Were estimates honest | Unjustified work-effort (point/estimate) changes |
+
+Key rules driven by the class constants:
+- **Team-relative zero-out:** for Quality, Hygiene, and Integrity, if a developer's negative
+  rate is more than `FACTOR_OF_TEAM_AVERAGE_*_FOR_ZERO_SCORE` (= 4×) the team average for that
+  metric, that sub-score floors at 0. Scores are graded against the team, not an absolute bar.
+- **Weighting:** `Final = 0.7·Reliability + 0.1·Quality + 0.1·Hygiene + 0.1·Integrity`
+  (`FINAL_SCORE_WEIGHT_*`). Reliability dominates.
+- **Caps:** a low sub-score caps the final regardless of the others —
+  Reliability < 80 caps final at 80; Quality/Hygiene/Integrity < 90 cap final at 90
+  (`FINAL_SCORE_CAP_*`).
+- **Recommended next commitment:** `PERCENT_OF_PREVIOUS_COMMITTED_TASK_AVERAGE_FOR_RECOMMENDED_COMMITMENT`
+  (= 0.9) × the developer's recent committed-points average, over the last 4 sprints.
+- `scoreHeatMap($score)` interpolates a red→green cell color for the spreadsheets (stops
+  roughly at 60/70/80/90/100).
+
+## Data model (`DB_TEAM`)
+
+All sprint state lives in the Team database (`_underscore::DB_TEAM`). Core tables:
+
+- **`Sprints`** — one row per sprint: `id`, `sprint` (number), `dateStart`, `dateEnd`.
+- **`Developers`** — `id`, `name`, `emailAddress`, ClickUp user identifier.
+- **`Tasks`** — one row per sprint task, keyed to ClickUp. Carries the lifecycle snapshots
+  (`workTypeAtLock` vs `workTypeNow`, `sprintPointsAtLock` vs `sprintPointsNow`,
+  `statusAtLock` / `statusNow` / `statusAtEnd`), classification fields (`taskType`,
+  `stakeholders`, `applications`, `link`), and the computed metric counters
+  (`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.
+
+`CaptureSprintEnd()` and `CaptureSprintDaily()` are the private sync routines that walk the
+ClickUp sprint list (paginated, `include_timl=true`), upsert `Sprints`/`Developers`/`Tasks`/
+`Tasks_Developers`, count hygiene misses, and archive tasks no longer present. They differ
+mainly in which snapshot columns they write (End → `statusAtEnd`; Daily → `statusNow`, and it
+backfills `workTypeAtLock` the first time a task is seen).
+
+## External integrations
+
+- **ClickUp API v2** — the dev-sprints **folder** (`CLICKUP_DEV_SPRINTS_FOLDER_ID`) holds one
+  list per sprint, named like `Sprint NN (M/D/YY - M/D/YY)`. Tasks are fetched page-by-page;
+  custom fields read include Work Type (committed/conditional/unplanned/stretch), Task Type,
+  Stakeholders, Application, and the two Knowledge fields used for hygiene scoring.
+- **TOGa IQ / AI** (`api.togaiq.com/api/ai/generate`) — release-notes generation only.
+- **Email** (`_Email`) — all reports and warnings; per-developer reports go to the developer,
+  everything else to `SEND_LEADERSHIP_REPORTS_TO`.
+- **Excel** (`PhpOffice\PhpSpreadsheet`) — every report is an `.xlsx` attachment.
+
+## Gotchas
+
+- **Single source file, huge methods.** `SprintEnd` alone is ~2,700 lines; `SprintLock` and
+  `SprintDaily` are each ~1,000. Almost all report layout/formatting is inline. Treat the
+  method boundaries (and the constants block at the top) as the map.
+- **At-lock baseline is load-bearing.** Reliability/Integrity compare *now* vs *at lock*. If
+  `SprintLock` did not run (or ran without capture), the `*AtLock` columns are empty and the
+  end-of-sprint scores are meaningless. Lock must happen at launch.
+- **Sprint list naming is a contract.** Capture matches the ClickUp sprint list by its
+  `Sprint NN (dates)` name / date range. A mis-named list is silently not found → leadership
+  gets a "sprint not found" alert instead of a report.
+- **Hardcoded credentials.** ⚠ The ClickUp access token and the TOGa IQ AI API key are
+  currently **hardcoded as class constants** in `Sprint.php` rather than read from config.
+  This is a known security debt (secrets in source) — they should move to `Config/*.ini`
+  and the committed values should be rotated. See team coding/security standards.
+- **Worker contract.** Like all 2.0 workers this must return cleanly and commit writes via
+  the `_Db`/transaction layer to be durable — uncommitted captures can be silently dropped.
+
+## Change history
+
+- 2026-06-24 — Initial documentation of `_Worker_Team_Sprint` (`Worker/Team/Sprint.php`):
+  the sprint lifecycle (warnings → lock → daily → end → release notes), the four-metric
+  developer scoring model (reliability/quality/hygiene/integrity with weights, team-relative
+  zero-out, and final-score caps), the `DB_TEAM` data model, and the ClickUp / TOGa IQ / email
+  integrations. Flagged hardcoded ClickUp + AI credentials as security debt.

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 11 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 12 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 13 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 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)
@@ -26,7 +26,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 5 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 6 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 5 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 

package/knowledge/clients/quad/profile.md

@@ -5,6 +5,7 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga2-commerce
   - dbchanges2
 project: _Underscore
 client: quad

package/package.json

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