toga-ai 1.0.183 → 1.0.185

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

@@ -0,0 +1,5 @@
+# toga2-view (TOGa View Frontend) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [TOGa View Frontend (toga2-view) Architecture](architecture.md) | `toga2-view` is the **React/TypeScript single-page frontend** for the TOGa 2.0 platform — the customer-facing web app (home warranty / tech-support portals). | toga2-view/src/main.tsx, toga2-view/src/App.tsx, toga2-view/src/routes.tsx, toga2-view/src/api/axiosInstance.ts, toga2-view/src/api/apiFunctions.ts, toga2-view/src/utils/queryHelpers.ts, toga2-view/src/contexts/AuthContext.tsx, toga2-view/src/contexts/useUserStore.ts, toga2-view/src/hooks/useAuthenticationFlow.ts, toga2-view/vite.config.ts, toga2-view/package.json |

package/knowledge/2.0/apps/toga2-view/architecture.md

@@ -0,0 +1,184 @@
+---
+title: TOGa View Frontend (toga2-view) Architecture
+framework: "2.0"
+repo: toga2-view
+project: TOGa View Frontend
+client: shared
+type: architecture
+status: active
+updated: 2026-06-24
+owners: [apeterson]
+files:
+  - toga2-view/src/main.tsx
+  - toga2-view/src/App.tsx
+  - toga2-view/src/routes.tsx
+  - toga2-view/src/api/axiosInstance.ts
+  - toga2-view/src/api/apiFunctions.ts
+  - toga2-view/src/utils/queryHelpers.ts
+  - toga2-view/src/contexts/AuthContext.tsx
+  - toga2-view/src/contexts/useUserStore.ts
+  - toga2-view/src/hooks/useAuthenticationFlow.ts
+  - toga2-view/vite.config.ts
+  - toga2-view/package.json
+related:
+  - clients/rate/profile.md
+  - clients/rate/features/saml-sso.md
+  - clients/rate/features/service-card-entitlements.md
+---
+
+## Summary
+
+`toga2-view` is the **React/TypeScript single-page frontend** for the TOGa 2.0
+platform — the customer-facing web app (home warranty / tech-support portals). It is
+a pure client: it holds no server logic and talks exclusively to the **`api2`** backend
+(the `/v2/...` JSON API) for all data and auth. It is **not** a PHP app and does **not**
+build on `_underscore` directly — its only runtime dependency is `api2` (declared in
+`registry.json` as `dependsOn: ["api2"]`).
+
+**Stack:** React 18 + TypeScript, built with **Vite 7**. Routing via **React Router v7**
+(`createBrowserRouter`). Server state via **TanStack React Query v5** (persisted to
+`localStorage`). Client/global state via **Zustand** (user) + **React Context** (auth).
+HTTP via a single **Axios** instance with auth/transaction interceptors. Styling via
+**Tailwind CSS v3 + SCSS**. Shared UI primitives come from the **`@agilant/toga-blox`**
+component library (npm package, versioned). Errors report to **Sentry**. Forms use
+`react-hook-form`; animation via `framer-motion`; icons from FontAwesome Pro.
+
+## Project layout
+
+```
+src/
+├── main.tsx                 # Vite entry; mounts <App/>, imports global styles
+├── App.tsx                  # Providers: PersistQueryClientProvider + AuthProvider + RouterProvider
+├── routes.tsx               # createBrowserRouter route table + route guards
+├── api/                     # Shared HTTP layer
+│   ├── axiosInstance.ts     # Single axios client + interceptors (auth, transactionId, 401 refresh)
+│   ├── apiFunctions.ts      # Generic apiGet / apiPost / apiPut / apiDelete<TData> wrappers
+│   └── genericApi.ts
+├── contexts/
+│   ├── AuthContext.tsx      # isAuthenticated, user, login(), logout(); cross-tab sync
+│   └── useUserStore.ts      # Zustand user store (persisted to localStorage "zu-user")
+├── hooks/                   # Shared hooks reused across pages
+│   ├── useAuthenticationFlow.ts   # SAML + domain-SSO orchestration (see Auth)
+│   ├── useApiQuery.ts / useApiMutation.ts   # React Query wrappers
+│   ├── useBundleServices.ts / useActiveServices.ts   # shared service-data hooks
+│   └── useBreakpoint.tsx, useAnnouncements.ts, ...
+├── components/              # Reusable, non-page UI (BaseButton, BaseInputs, MobileNav, ...)
+├── pages/<Page>/            # Feature pages — see "Page convention" below
+├── utils/
+│   └── queryHelpers.ts      # assembleOptions(): JS query object → /v2 query string
+├── services/                # External integrations (e.g. paypalService.ts)
+└── styles/                  # index.scss (source) → index.css (Tailwind + SCSS output)
+```
+
+## Page convention (the dominant pattern)
+
+Each feature lives under `src/pages/<PageName>/` with a **view / viewModel / api** split:
+
+```
+pages/<PageName>/
+├── view/
+│   ├── <PageName>.tsx          # presentational component; consumes the viewModel hook
+│   └── components/             # page-local subcomponents
+├── viewModels/                 # business-logic hooks  (⚠ some pages use singular "viewModel/")
+│   ├── use<PageName>ViewModel.ts
+│   └── DUMMYFIELDS/*.json      # static labels/copy for the page
+├── api/<page>Api.ts            # page-specific API calls (build options, call apiGet/apiPost)
+├── types.ts                    # page-local TypeScript interfaces
+└── index.ts                    # re-exports the view component
+```
+
+**ViewModel-hook pattern.** The view component is "dumb": it calls
+`use<PageName>ViewModel()` and renders what it returns. The hook owns all state,
+data-fetching, and event handlers, and returns a typed object
+(`<PageName>ViewModel` interface). It composes shared hooks (`useUserStore()`,
+`useBundleServices()`, `useNavigate()`, …) and the page's own `api/` functions.
+
+> **Convention drift to know:** most pages name the folder `viewModels/` (plural), but a
+> few (e.g. `CheckOut`, `Login`) use `viewModel/` (singular). When adding a page, match the
+> plural form unless editing one of the existing singular ones. The hook itself is always
+> `use<PageName>ViewModel` (singular "ViewModel").
+
+## API / data layer
+
+All HTTP goes through the single axios instance in `src/api/axiosInstance.ts`. Never
+create ad-hoc `fetch`/`axios` calls in components — go through `apiFunctions.ts`
+(`apiGet`/`apiPost`/`apiPut`/`apiDelete`) and React Query.
+
+- **Base URL is resolved per-hostname.** The instance reads the first label of
+  `window.location.hostname`, upper-cases it, and looks up `VITE_API_<LABEL>`, falling
+  back to `VITE_API`. E.g. `homewarranty.rate.com` → `VITE_API_HOMEWARRANTY`. This is why
+  there are many `.env.<mode>` files and per-subdomain `VITE_API_*` vars.
+- **transactionId** — a fresh UUID is attached to every request's query params (request
+  interceptor) for end-to-end tracing.
+- **Query builder** — `assembleOptions()` in `utils/queryHelpers.ts` converts a structured
+  JS object (`fields`, `where`, `join`/`ojoin`, `sort`) into the `api2` `/v2` query string.
+  Use `ojoin` (LEFT JOIN) when a related row may be absent — `join` (INNER JOIN) silently
+  drops parent rows that have no match.
+
+## Auth & tokens
+
+- **AuthContext** holds `isAuthenticated`, `user`, `login()`, `logout()`. It persists to
+  `localStorage` and syncs across browser tabs via the `storage` event.
+- **`useAuthenticationFlow.ts`** orchestrates two entry paths:
+  1. **SAML landing** — a `?saml=<payload>` query param on load: the param is **stripped
+     immediately via `replaceState`** (leaving it in causes stale-payload replay on
+     refresh — this was a live bug), then exchanged at the API for tokens + user, after
+     which `login()` runs and the app navigates to `/landing`.
+  2. **Domain SSO check** — if not authenticated and no `?saml=`, it queries `/domains`
+     for the current host; if the client is SSO-type it redirects to the IdP, otherwise
+     it falls through to `/login`.
+- **Token storage (localStorage):** `accessToken`, `refreshToken`, `user`. Unauthenticated
+  requests use a **public token** auto-fetched via `POST /auth/public`. A `401` triggers a
+  one-shot refresh via `POST /auth/refresh`; if refresh fails, a `UserLoginRequired` window
+  event is dispatched to force re-login.
+
+## Routing & guards
+
+Routes are defined in `src/routes.tsx` with `createBrowserRouter`:
+- `/` → `AuthRedirect` (sends to `/login` or `/landing` by auth state).
+- `/login` → public (redirects already-authenticated users away).
+- Everything else sits behind **`PrivateRoute`** (checks `useAuth().isAuthenticated`,
+  shows a loading state while `useAuthenticationFlow` resolves) and is wrapped by
+  `MobileNavToggle`. Pages: `/home`, `/landing`, `/services`, `/activity`, `/checkout`,
+  `/zip-validation`, `/payment-success`, `/activation`, `/get-support`, `/select-service`,
+  `/create-ticket`, `/choose-plan`.
+
+## Build, environments & deploy
+
+- **Tooling:** `npm run dev` (Vite dev server, port 5173), `npm run build`
+  (`tsc && vite build --mode production`), plus `buildBeta` / `buildGamma`. `npm run lint`
+  runs ESLint with `--max-warnings 0`. E2E via Cypress (`npm run cypress`).
+- **Many environments:** `.env.{development,alpha,beta,gamma,sprint,stage,test,production}`.
+  Each supplies the `VITE_API_*` base URLs consumed by `axiosInstance.ts`. A client/brand is
+  selected by hostname at runtime (not a separate build), via the `VITE_API_<SUBDOMAIN>`
+  lookup.
+
+## Critical rules
+
+- **All HTTP goes through `axiosInstance` + `apiFunctions`** — never raw `fetch`/`axios` in
+  components. The shared instance is what attaches auth, the transactionId, and 401-refresh.
+- **Use `ojoin` (LEFT JOIN), not `join` (INNER JOIN), in `assembleOptions` queries** when a
+  joined row may be missing — an inner join silently drops parent records.
+- **Strip the `?saml=` param before using it** (already handled in `useAuthenticationFlow`);
+  do not reintroduce code paths that leave it in the URL.
+- **Append `T00:00:00` to date-only strings before parsing** to avoid timezone shift moving
+  a date back a day (a recurring display bug on service/entitlement dates).
+- **Keep view components presentational** — logic, state, and side effects belong in the
+  `use<PageName>ViewModel` hook, not the `.tsx` view.
+- **Shared hooks fan out.** A change to a shared hook (e.g. `useBundleServices`) affects every
+  page/viewModel that consumes it — check call sites before changing its shape.
+- **Tokens live in `localStorage`** (`accessToken`/`refreshToken`/`user`). Treat them as
+  sensitive; never log token values or echo them into Sentry extras.
+
+## Client notes
+
+**Rate** is the primary consumer of this frontend (SAML-only auth via Azure AD; warranty
+service cards show Address instead of Price). See `clients/rate/profile.md` and the Rate
+feature docs in `related:` for client-specific behavior layered on top of this architecture.
+
+## Gaps / not yet captured
+
+- `2.0/standards/frontend.md` — no shared 2.0 React/TS standard doc exists yet; conventions
+  above are documented here per-repo until one is written.
+- Per-page feature docs (Home, Activity, Checkout, etc.) are not individually captured; add
+  under `2.0/apps/toga2-view/features/` as they stabilize.

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,12 +16,12 @@ _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)
 - **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
-- **toga2-view** (TOGa View Frontend) — 1 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
+- **toga2-view** (TOGa View Frontend) — 2 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **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)

package/package.json

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