toga-ai 1.0.184 → 1.0.185

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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.184",
+  "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",