toga-ai 1.0.849 → 1.0.850

package/knowledge/2.0/apps/_underscore/features/apirequest-json-content-type.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: ["jcardinal", "ajean", "rgirish"]
+updated: 2026-09-21
+owners: ["jcardinal", "ajean", "rgirish", "kyalamarthi"]
 files:
   - _underscore/ApiRequest.php
   - _underscore/Model/Client/Logs/Api.php
@@ -137,6 +137,18 @@ case-insensitive scan of already-set headers, so a caller-supplied `Content-Type
 - **A hand-rolled `curl` never appears in `Logs.Api`.** The logging belongs to `_ApiRequest`, so a
   manual/CLI `curl` reproduction of a vendor call is *correctly* absent from the log. Do not read
   that absence as "the platform did not call the vendor."
+- **⚠ OPEN: valid JSON is rejected as "XML" when the body merely CONTAINS an XML declaration.**
+  `ApiRequest.php:360` decides a response is XML with
+  `stripos($this->responsePayload, '<?xml version=') === false` — a substring search over the
+  **whole body**, not a prefix check. So any JSON response carrying that literal anywhere inside it
+  throws `API response was received in XML encoding when it was expecting JSON encoding`. Live case
+  (2026-09-21): a ClickUp task description holding a pasted cXML document (an ODP cXML sample on
+  task TRUE-82107) broke a valid ClickUp task-page response. **The message blames the API, not the
+  ticket**, so it is very hard to diagnose — and the team handles cXML routinely, so expect it
+  again. **Workaround:** delete the `<?xml version="1.0"?>` line from the offending record (only
+  that exact literal is searched for). **Proposed fix, NOT shipped:** anchor the test —
+  `stripos(ltrim($this->responsePayload), '<?xml version=') !== 0`. It sits on every caller's path,
+  so get a `cto` opinion plus the normal reviewers before shipping it.
 - **`Logs.Api` is 1.4M+ rows and `source` is NOT indexed.** Any diagnostic query must be bounded by
   `dtStamp` (indexed) or it times out — `WHERE source = '…'` alone will not return.
 

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

@@ -18,6 +18,7 @@
 | [ClickUp Subtask Activity → Parent Opportunity/Epic Comments](features/clickup-subtask-activity.md) | Mirrors subtask status/comment activity up to its top-level Opportunity/Epic as one comment; open for the subtask fan-out, its dedup ledger, or structural ances |
 | [ClickUp Task Description Fluffer (Talos KB Investigation)](features/clickup-task-fluffer-talos.md) | Async worker that "fluffs" a new ClickUp task by running its name+description through the Talos `dev-core` KB agent and writing the report back; open for the fl |
 | [ClickUp Work Type Automation (Committed / Conditional / Stretch)](features/clickup-work-type-automation.md) | Auto-maintains each ClickUp task's Work Type (Committed/Conditional/Stretch) from its dependencies, status, and due date; open when work-type promotion/demotion |
+| [worker2 — Committed Secrets & Config Exposure (debt register)](features/committed-secrets-and-config-debt.md) | Standing list of credentials committed to the worker2 repo (locations only); open before adding a credential to worker2 or assuming a config value is private. |
 | [Compass VIP Support Importer (worker2)](features/compass-vip-support-importer.md) | worker2 action that ingests Compass's quarterly VIP spreadsheet and sets each VIP's support tech (`Users.c_supportedByUserId` in `Client_Compass`); open when wo |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). |
 | [Cross-account AWS access for worker2 crons (_Component_Aws_Workloads)](features/cross-account-aws-access.md) | The standard, and only sanctioned, way any new worker2 cron obtains AWS access (any account/region/SDK client) via role-assume; open before writing worker2 code |
@@ -63,4 +64,5 @@
 | [Rotating the ClickUp API credential (and migrating to the devteam service account)](workflows/clickup-credential-rotation.md) | Procedure to rotate the ClickUp API token (or move traffic onto the `devteam@togatech.com` service account) without killing the live webhook subscription or sil |
 | [PHP Runtime Upgrade on Elastic Beanstalk (worker2 8.3 → 8.5 + PhpSpreadsheet 1.x → 3.x)](workflows/php-runtime-upgrade-dependency-audit.md) | Reusable checklist for moving a TOGA repo across an EB PHP runtime jump (worker2 8.3 → 8.5 + PhpSpreadsheet 1.x → 3.x); open before any runtime bump or when a c |
 | [Running worker2 locally against real NetSuite (and what EB does instead)](workflows/running-worker2-locally.md) | Boot worker2 on a dev machine to run a real worker action against live NetSuite + a local Forecast DB; open when local boot fails or before any local NetSuite r |
+| [Repointing the Sprint Tooling at a New ClickUp Sprints Folder (+ table reset)](workflows/sprint-clickup-folder-repoint.md) | Move worker2's sprint tooling onto a new ClickUp "True Dev Sprints" folder and reset the Team sprint tables; open when the sprints folder id changes. |
 | [Ticket → ClickUp Pseudocode Planning (Talos-grounded)](workflows/ticket-to-pseudocode-planning.md) | Procedure to turn a ClickUp ticket into a reviewed, formatted plan posted to its `📝 Pseudocode` field (ClickUp + codebase + Talos); open when planning a ticket |

package/knowledge/2.0/apps/worker2/features/committed-secrets-and-config-debt.md

@@ -0,0 +1,72 @@
+---
+title: "worker2 — Committed Secrets & Config Exposure (debt register)"
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-09-21
+owners: ["kyalamarthi"]
+files:
+  - worker2/.gitignore
+  - worker2/Worker/Team/Github.php
+  - worker2/.ebextensions/git.json
+  - worker2/Config/production.ini
+  - worker2/Config/netsuite_ec_key.pem
+  - worker2/Worker/Team/Sprint.php
+related:
+  - ./automated-pr-merger-force-push-race.md
+  - ./team-sprint-management.md
+  - ../../_underscore/features/apirequest-json-content-type.md
+  - ../../../../clients/rate/features/paypal-subscription-purchase-webhook.md
+---
+
+Standing list of credentials committed to the worker2 repo (locations only); open before adding a credential to worker2 or assuming a config value is private.
+
+## Summary
+
+Every item below is **pre-existing** debt, found in a 2026-09-21 audit. Root cause:
+`worker2/.gitignore` contains only `/vendor/`, so **every `Config/*.ini` and key file in the repo is
+committed**. The repo is private (verified 2026-09-21 — the unauthenticated GitHub API returns 404),
+which is the only thing containing the blast radius.
+
+**Locations only. Never paste a credential value into this or any knowledge doc** — `validate` fails
+the publish on a credential literal.
+
+## How it works
+
+### Inventory — where each credential lives
+
+| Credential | Location | Why it is worse than it looks |
+|---|---|---|
+| GitHub personal access token, `agilantgit` account | `worker2/Worker/Team/Github.php:9` **and** `worker2/.ebextensions/git.json:4` (same token, two copies) | Committed since 2025-01-17 and present in **166 of 167 branches**, so scrubbing history is not a fix — **rotation is the only fix**. Org-wide reach. It is also interpolated into a `shell_exec` clone URL, so it shows up in the instance process list. |
+| NetSuite EC private key | `worker2/Config/netsuite_ec_key.pem` | Tracked in git as a file. |
+| TOGa IQ (`api.togaiq.com`) API key | `worker2/Worker/Team/Sprint.php:43`, used ~L422 | Still a class constant. There is **no `[togaiq]` config group yet**, so moving it means adding the config group first. |
+| PayPal webhook signature verification **off** in production | `worker2/Config/production.ini:182` | Impact already written up — a caller who knows the URL can create a paid SalesOrder. See [Rate PayPal subscription webhook](../../../../clients/rate/features/paypal-subscription-purchase-webhook.md). |
+
+### Fixed / no longer true
+
+- **ClickUp API token in `Sprint.php`** — the hardcoded `CLICKUP_API_ACCESS_TOKEN` constant is
+  **gone**. All 6 call sites now use `_Component_Api_Clickup::accessToken()`, which reads
+  `[clickup] token` from config. The component's own hardcoded fallback token, and the plaintext
+  `Authorization` header written into `Logs.Api`, are separate open items — see
+  [_ApiRequest gotchas](../../_underscore/features/apirequest-json-content-type.md#gotchas).
+
+## Gotchas
+
+- **Config is not private here.** Moving a secret from a PHP constant into
+  `Config/production.ini` hides it from a grep of the source, not from git — it is still committed.
+  Treat that move as a refactor, not a remediation.
+- **Any credential that has ever been committed must be rotated**, not just deleted. Deleting the
+  line leaves it in history and in every branch that still carries it (166 of 167, for the GitHub
+  token).
+- **Keep this table current.** Add an entry whenever a committed credential is found, and move it to
+  *Fixed* when it is rotated and relocated, so this stays the one place the team looks.
+
+## Related
+
+- [Automated PR Merger — force-push clobber race](./automated-pr-merger-force-push-race.md) (owns `Worker/Team/Github.php`)
+- [Team Sprint Management & Reporting](./team-sprint-management.md)
+- [_ApiRequest — encode/decode & api-logging behavior](../../_underscore/features/apirequest-json-content-type.md)
+- [Rate PayPal Subscription Purchase & Webhook Pipeline](../../../../clients/rate/features/paypal-subscription-purchase-webhook.md)

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

@@ -6,17 +6,19 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-21
 owners: ["jcardinal", "kyalamarthi"]
 files:
   - worker2/Worker/Team/Sprint.php
+  - worker2/Config/production.ini
   - _underscore/Model/Team/Sprint.php
-  - dbchanges2/Core/CronJobs (SprintLockScheduled seed)
 related:
   - ../architecture.md
   - ./creating-worker-actions.md
   - ./clickup-work-type-automation.md
   - ./clickup-project-routing.md
+  - ./committed-secrets-and-config-debt.md
+  - ../workflows/sprint-clickup-folder-repoint.md
   - ../workflows/php-runtime-upgrade-dependency-audit.md
 ---
 
@@ -48,8 +50,9 @@ 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.
+- ClickUp config lives in class constants: `CLICKUP_TEAM_ID` and `CLICKUP_DEV_SPRINTS_FOLDER_ID` (the
+  folder whose child lists are the sprints). The API token is **no longer** a constant here — all 6
+  call sites use `_Component_Api_Clickup::accessToken()`, reading `[clickup] token` from config.
 - 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` /
@@ -106,8 +109,8 @@ Otherwise it returns a skip message (captured to `Core.WorkerJobs.output`) and d
 `SprintLock()` itself is unchanged — this only decides *whether* to run it today. Action path
 `Team/Sprint/SprintLockScheduled` → `_Worker_Team_Sprint::SprintLockScheduled`.
 
-**Deploy coupling.** The worker2 code deploy and the dbchanges2 migration that seeds the
-`Core.CronJobs` row must be **released together** — the cron row references the
+**Deploy coupling.** The worker2 code deploy and the `Core.CronJobs` row insert must land
+**together** (no committed migration seeds it — see Gotchas) — the cron row references the
 `Team/Sprint/SprintLockScheduled` action, which must exist in the deployed code or the scheduled job
 fails when it fires.
 
@@ -327,13 +330,50 @@ see [TOGa IQ Sprint Dashboard API](../../api2/features/sprint-dashboard-api.md)
 - **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.
+- **The sprint list NAME is a contract, and the YEAR is required.** All three capture paths
+  (`CaptureSprintDaily` ~L3477, `CaptureSprintEnd` ~L3231, `SprintLock` ~L3801) run the same
+  `preg_match('/Sprint (\d+) \((\d{1,2}\/\d{1,2}\/\d{2,4}) - (\d{1,2}\/\d{1,2}\/\d{2,4})\)/')` over
+  the list name. A list named `Sprint 1 (9/16 - 9/30)` — no year — does **not** match, `$matches[1]`
+  is undefined, and the run **fatals** two lines later (~L3479). A name that merely misses the date
+  window instead gives a silent "sprint not found" leadership alert. ClickUp's end date is the
+  **next** sprint's start (exclusive); the code stores `dateEnd` minus one day. **Proper fix for a
+  future ticket:** take the number from the name but the dates from the list object's `start_date` /
+  `due_date` (epoch ms), already fetched for the date-window match.
+- **The tooling cannot bootstrap from an empty `Sprints` table — it deadlocks.** `SprintDaily`
+  (~L4806), `SprintEnd` (~L473-474) and `SendSprintEndWarnings` (~L218) all call `getSprint()`
+  **before** the `Capture*` method that would create the `Sprints` row, and `getSprint()`
+  (~L5702-5740) does `fetchRow()` with **no null check** — so on an empty table every entry point
+  fatals with `Attempt to read property "id" on null`. The thing that creates the row is never
+  reached. **Workaround (proven in production 2026-09-16):** `INSERT` one `Sprints` row by hand
+  (`sprint`, `dateStart`, `dateEnd`); `CaptureSprintDaily`'s "ensure the sprint record exists" block
+  (~L3478) self-heals from there. Anyone truncating these tables hits this — see
+  [Repointing the sprint tooling](../workflows/sprint-clickup-folder-repoint.md).
+- **`getSprint()` uses `LIMIT 1` with no `ORDER BY`** (~L5717 and ~L5721, both branches). With
+  duplicate sprint numbers it returns an **arbitrary** row — a live violation of the
+  deterministic-`LIMIT 1` rule in
+  [backend-php standards](../../../standards/backend-php.md#a-limit-1-on-a-non-unique-key-must-have-a-deterministic-order-by).
+- **`SprintLock` is NOT a safe way to repopulate empty tables.** It captures before it reads, so it
+  looks like a bootstrap (its `getSprint()` call is gated behind `$generateSprintLockReport`), but
+  its capture block (~L4016-4030) **writes back to ClickUp for every task** — sets Previous Sprint
+  Work Type, sets "Added at sprint launch" = true, sets Condition = "On Track". Run outside the real
+  launch ceremony it corrupts those fields across the whole sprint.
+- **`SprintDaily` returns nothing on success** — a production run reads `Successfully Executed
+  (4.255 seconds): <no return message>`, so a run that worked is indistinguishable from one that
+  never fired. Breaks the return-on-both-paths rule in the
+  [worker2 architecture](../architecture.md); fix by returning a structured summary.
+- **The Team/Sprint cron rows are not in git.** Nothing in `dbchanges2/Core/` registers
+  `Team/Sprint/%` (searched 2026-09-21), despite this doc previously listing a `CronJobs
+  (SprintLockScheduled seed)` file. A concrete case of "a committed migration records intent, not
+  deployed state" ([framework-rules](../../../standards/framework-rules.md)) — read the real
+  schedule from `Core.CronJobs` in the target environment.
+- **The dev-sprints folder id lives in THREE places** — the `Sprint.php` constant, the
+  `Monitor/Oneuptime.php` fallback, and `[clickup] sprint_folder_id` in `Config/production.ini`.
+  They must move together, and `Worker/Clickup/Design.php`'s own Design-Sprints folder must not move
+  with them. Procedure:
+  [Repointing the sprint tooling](../workflows/sprint-clickup-folder-repoint.md).
+- **Credentials.** The ClickUp token now comes from config (`_Component_Api_Clickup::accessToken()`);
+  the TOGa IQ AI key is **still a hardcoded constant** at `Sprint.php:43`. Locations and remediation
+  status: [committed secrets register](./committed-secrets-and-config-debt.md).
 - **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.
 - **ClickUp pagination returns duplicate tasks — the sync loop must be idempotent.** ClickUp's

package/knowledge/2.0/apps/worker2/workflows/sprint-clickup-folder-repoint.md

@@ -0,0 +1,79 @@
+---
+title: Repointing the Sprint Tooling at a New ClickUp Sprints Folder (+ table reset)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-09-21
+owners: ["kyalamarthi"]
+files:
+  - worker2/Worker/Team/Sprint.php
+  - worker2/Worker/Monitor/Oneuptime.php
+  - worker2/Config/production.ini
+  - dbchanges2/Team/2026-09-16a - Reset sprint tables for new ClickUp folder.sql
+related:
+  - ../features/team-sprint-management.md
+  - ../features/creating-worker-actions.md
+  - ../../dbchanges2/architecture.md
+---
+
+Move worker2's sprint tooling onto a new ClickUp "True Dev Sprints" folder and reset the Team sprint tables; open when the sprints folder id changes.
+
+## Summary
+
+Sprint numbering restarts at 1 in a new folder and collides with existing `Team.Sprints` rows, so a
+repoint is a code + config change **plus** a data reset **plus** a manual seed row — not a one-line
+constant edit. Done once on 2026-09-16 under TRUE-82052 (worker2 + dbchanges2).
+
+## Steps
+
+1. **Name the ClickUp lists `Sprint <n> (M/D/YY - M/D/YY)` — with the year.** Capture parses the list
+   name with a regex that requires the year; a list created as `Sprint 1 (9/16 - 9/30)` does not
+   match and the run fatals. See
+   [team-sprint-management → gotchas](../features/team-sprint-management.md#gotchas).
+2. **Update all three copies of the folder id — they must move together**, or the tooling
+   split-brains:
+   - `CLICKUP_DEV_SPRINTS_FOLDER_ID` — `worker2/Worker/Team/Sprint.php` (~L10)
+   - `CLICKUP_SPRINTS_FOLDER_ID_FALLBACK` — `worker2/Worker/Monitor/Oneuptime.php` (~L25)
+   - `[clickup] sprint_folder_id` — `worker2/Config/production.ini` (~L270); the escalation cron
+     reads this and it **wins** over the Oneuptime fallback.
+
+   Do **not** touch `DESIGN_SPRINTS_FOLDER_ID` in `worker2/Worker/Clickup/Design.php` — Design
+   Sprints is a different folder with its own id.
+3. **Run the reset migration alone, on a fresh connection**, against the `Team` database:
+   `dbchanges2/Team/2026-09-16a - Reset sprint tables for new ClickUp folder.sql`. It truncates
+   child → parent (`Tasks_Developers` → `Tasks` → `Sprints`) wrapped in
+   `SET FOREIGN_KEY_CHECKS = 0 / 1`, because MySQL refuses `TRUNCATE` on a table a foreign key
+   points at **even when the child is already empty**.
+4. **Insert one `Sprints` row by hand** (`sprint`, `dateStart`, `dateEnd`). Required: the tooling
+   **cannot bootstrap from an empty `Sprints` table** — every entry point calls `getSprint()` before
+   the capture that would create the row. See
+   [team-sprint-management → gotchas](../features/team-sprint-management.md#gotchas).
+5. **Deploy worker2, then run `Team/Sprint/SprintDaily` once** (manual POST — see
+   [creating-worker-actions](../features/creating-worker-actions.md)). From there
+   `CaptureSprintDaily`'s own "ensure the sprint record exists" block (~L3478) keeps `Sprints`
+   current on its own.
+6. **Verify in the DB, not from the reply.** `SprintDaily` returns nothing on success, so a good run
+   reads `Successfully Executed (…): <no return message>`. Confirm `Sprints` / `Tasks` repopulated.
+
+## Gotchas
+
+- **`FOREIGN_KEY_CHECKS` is session-scoped.** Run nothing else on that connection, and if the file
+  stops part-way the flag stays **off** for the rest of that session — reconnect.
+- **Do not use `SprintLock` to repopulate the tables.** It captures before it reads, so it looks
+  like a safe bootstrap, but its capture block **writes back to ClickUp** for every task. See
+  [team-sprint-management → gotchas](../features/team-sprint-management.md#gotchas).
+- **Truncate throws away sprint history.** The alternative is renumbering the old rows. On
+  2026-09-16 the developer chose truncate and declined a backup — if history matters next time,
+  renumber, or back up `Sprints` / `Tasks` / `Tasks_Developers` first.
+- **The cron rows are not in git.** No committed migration seeds the `Team/Sprint/%` `CronJobs`
+  rows, so after a repoint the live schedule can only be read from `Core.CronJobs` in the target
+  environment.
+
+## Related
+
+- [Team Sprint Management & Reporting](../features/team-sprint-management.md)
+- [Creating Worker Actions](../features/creating-worker-actions.md)
+- [dbchanges2 Architecture](../../dbchanges2/architecture.md)

package/knowledge/INDEX.md

@@ -20,7 +20,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 87 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 71 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 73 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 19 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 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.849",
+  "version": "1.0.850",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",