toga-ai 1.0.474 → 1.0.475

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

@@ -2,7 +2,7 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
-| [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php |
+| [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php, worker2/composer.json |
 | [Deploy-Time Auto-Registration to the Shared ALB Target Group (non-production)](features/alb-target-group-auto-registration.md) | TOGA does **not** pay for EB-managed load-balancer registration, so an EB instance is normally **not** added to its environment's ALB target group — a fresh or | worker2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, worker2/ebs/register_instance_to_shared_application_load_balancer.php, worker2/.platform/hooks/prebuild/_shared/040-write-instance-id.sh, worker2/.platform/hooks/prebuild/_shared/041-write-region.sh, worker2/.platform/hooks/postdeploy/015_install_composer.sh, api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
 | [Automated PR Merger — Concurrent Force-Push Clobber Race](features/automated-pr-merger-force-push-race.md) | The automated PR merger `_Worker_Team_GitHub::Merge` (`worker2` `Worker/Team/Github.php`) merges approved PRs to `_production` by **force-pushing from a clone t | Worker/Team/Github.php |
 | [ClickUp Connectivity Watchdog](features/clickup-connectivity-watchdog.md) | A cron watchdog that emails when the ClickUp integration looks disconnected during business hours. | worker2/Worker/Clickup/Health.php, worker2/Database/ClickupHealthWatchdog.sql |
@@ -34,4 +34,5 @@
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | > **SUPERSEDED (2026-07-09) — the S3-staging model below is history.** `Export` is now a thin > **GRAPH-DIRECT** cron poller: it no longer archives raw VTT to ` | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
 | [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php |
 | [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 |
+| [PHP Runtime Upgrade on Elastic Beanstalk (worker2 8.3 → 8.5 + PhpSpreadsheet 1.x → 3.x)](workflows/php-runtime-upgrade-dependency-audit.md) | The procedure used to move worker2 from **PHP 8.3 to PHP 8.5** on Elastic Beanstalk, and the dependency work that had to land first. | worker2/composer.json, worker2/composer.lock, worker2/Worker/Team/Sprint.php, worker2/Worker/Client/TowFoundation/ProcessReceipts.php, worker2/Worker/Forecast/Import.php |
 | [Ticket → ClickUp Pseudocode Planning (Talos-grounded)](workflows/ticket-to-pseudocode-planning.md) | A repeatable procedure for turning a ClickUp ticket into a reviewed, formatted implementation plan posted back to the ticket's `📝 Pseudocode` custom field. | test/@dave/clickup_md2delta.js |

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

@@ -6,17 +6,19 @@ project: Worker
 client: shared
 type: architecture
 status: active
-updated: 2026-07-28
+updated: 2026-07-29
 owners: [jcardinal]
 files:
   - worker2/Controller/Index.php
   - worker2/Worker/
   - worker2/LambdaFunctions/
   - _underscore/Worker.php
+  - worker2/composer.json
 related:
   - ./features/creating-worker-actions.md
   - ./features/alb-target-group-auto-registration.md
   - ../_underscore/features/async-query-execution.md
+  - ./workflows/php-runtime-upgrade-dependency-audit.md
 ---
 
 ## Summary
@@ -32,6 +34,18 @@ processes background jobs. It's a `_underscore` 2.0 app (`index.php` is just
 **MySQL is the source of truth; SQS is delivery only.** All job state lives in
 `Core.WorkerJobs`. Every worker invocation reads from that table and writes its result back.
 
+**PHP runtime baseline: 8.5 on both environments.** `_production` and `_sandbox-dev` both run
+*PHP 8.5 on 64bit Amazon Linux 2023 / platform 4.13.4* (production was moved off 8.3 on
+2026-07-29). `vendor/` is gitignored, so a dependency that is incompatible with the environment's
+PHP **only ever fails at EB deploy time**, never locally — and if two environments run different
+PHP, identical code deploys to one and fails on the other. worker2's root `require` therefore
+carries an explicit upper bound, `"php": ">=8.2 <8.6"`, so the next platform jump fails pointing
+at *our* requirement instead of at a confusing transitive library error; `composer update` is run
+on the **lowest** supported runtime so one lock is valid everywhere. Never silence such a failure
+with a `config.platform.php` pin or a downgrade to a version that merely *permits* the new PHP —
+that trades a loud deploy failure for silent runtime breakage. Full procedure:
+[PHP Runtime Upgrade on Elastic Beanstalk](./workflows/php-runtime-upgrade-dependency-audit.md).
+
 **Production vs. non-production inbound differ.** The SQS/Lambda job pipeline above describes
 **production**. **Non-production worker2 environments do not incorporate SQS at all** — they exist
 for **manual invocation over HTTP** (hence `index.php` dispatch and `.platform/httpd/conf.d/`, and
@@ -44,6 +58,17 @@ passes through SQS** — a queue-based reproduction of a prod issue will not wor
 listener rules and security groups must restrict non-prod to internal/VPN sources, and the
 HTTP-triggered job endpoints must enforce auth.
 
+**Critical rules:** MySQL is the source of truth and SQS is delivery only — all job state lives in
+`Core.WorkerJobs`, so never treat a queue message as the record of a job. Every worker/webhook
+endpoint must return **HTTP 200 on every path, including failure** (failures are recorded in
+`WorkerJobs`): there is no DLQ and the visibility timeout is 3600s, so a single 500 becomes a
+poison-message storm. Workers are `abstract class _Worker_<Name>` with `public static` entry
+methods and are invoked **only** through `_Worker::runTask(action, parameters)` — never call a
+worker method directly. This repo is PHP and Python only: never add a `.sql` file here, as all
+schema changes and cron seeds belong to `dbchanges2`. Both environments run **PHP 8.5**, and the
+repo's own root `require` (`">=8.2 <8.6"`) is the deliberate binding upper bound — never pin
+`config.platform.php` or downgrade a package merely to make a deploy install on a newer runtime.
+
 ## AWS infrastructure
 
 | Component | Notes |

package/knowledge/2.0/apps/worker2/features/platform-cache-cleanup.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
+updated: 2026-07-29
 owners: [jcardinal]
 files:
   - worker2/Worker/Platform/Cache.php
@@ -18,6 +18,7 @@ related:
   - ./creating-worker-actions.md
   - ../../_underscore/features/per-client-database-connections.md
   - ../architecture.md
+  - ../workflows/php-runtime-upgrade-dependency-audit.md
 ---
 
 ## Summary
@@ -123,6 +124,9 @@ environment.
   re-reads its own just-emptied tables from the query cache and mis-decides what is left.
 
 ## Change history
+- 2026-07-29 — Verified `Platform/Cache/Truncate` working on **PHP 8.5** after worker2's EB
+  runtime upgrade from 8.3 (both environments now 8.5, AL2023 platform 4.13.4). No code change.
+  See [PHP Runtime Upgrade on Elastic Beanstalk](../workflows/php-runtime-upgrade-dependency-audit.md). (jcardinal)
 - 2026-07-28 — Added second action `_Worker_Platform_Cache::Truncate()` on the same class: manual /
   administrative, deliberately **not** scheduled. Removes the entire cross-client cache
   (`DELETE FROM Tables` + cascade, defensive `DELETE FROM Tables_Clients` for orphaned cursors, then

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-24
+updated: 2026-07-29
 owners: ["jcardinal", "kyalamarthi"]
 files:
   - worker2/Worker/Team/Sprint.php
@@ -17,6 +17,7 @@ related:
   - ./creating-worker-actions.md
   - ./clickup-work-type-automation.md
   - ./clickup-project-routing.md
+  - ../workflows/php-runtime-upgrade-dependency-audit.md
 ---
 
 ## Summary
@@ -222,6 +223,13 @@ backfills `workTypeAtLock` the first time a task is seen).
 
 ## Gotchas
 
+- **PhpSpreadsheet coordinates are ARRAYS now (3.x).** All `*ByColumnAndRow` methods were
+  removed in PhpSpreadsheet 2.0; `Sprint.php` had **828** of them (the bulk of the repo's 856)
+  and they are all now the array form — `->setCellValue([$col, $row], $v)`,
+  `->getStyle([$c1, $r1, $c2, $r2])`, `->mergeCells([$c1, $r1, $c2, $r2])`. Do not reintroduce
+  the old signatures when copying older report code into this file; the full mapping and the
+  safe transform method are in
+  [PHP Runtime Upgrade on Elastic Beanstalk](../workflows/php-runtime-upgrade-dependency-audit.md#step-5--migrate-the-call-sites-bycolumnandrow-removed-in-20).
 - **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.
@@ -363,6 +371,12 @@ middleware defaults every tile/chart endpoint to it when no `?sprint=` is suppli
 
 ## Change history
 
+- 2026-07-29 — Migrated all **828** `*ByColumnAndRow` call sites in `Sprint.php` to
+  PhpSpreadsheet's array-coordinate API as part of the phpspreadsheet 1.30.2 → 3.10.7 upgrade
+  required by the worker2 PHP 8.5 runtime move. No report behavior change intended; the
+  array-range forms of `getStyle`/`mergeCells` were verified empirically against 3.10.7
+  (including an Xlsx save/load round-trip). See
+  [PHP Runtime Upgrade on Elastic Beanstalk](../workflows/php-runtime-upgrade-dependency-audit.md). (jcardinal)
 - 2026-07-24 — Productionized the dashboard: the metric definitions above are now served by six
   api2 Record Scripts on `_Model_Team_Sprint` (see
   [Sprint Dashboard API](../../api2/features/sprint-dashboard-api.md)), retiring the Express

package/knowledge/2.0/apps/worker2/workflows/php-runtime-upgrade-dependency-audit.md

@@ -0,0 +1,196 @@
+---
+title: PHP Runtime Upgrade on Elastic Beanstalk (worker2 8.3 → 8.5 + PhpSpreadsheet 1.x → 3.x)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-07-29
+owners: [jcardinal]
+files:
+  - worker2/composer.json
+  - worker2/composer.lock
+  - worker2/Worker/Team/Sprint.php
+  - worker2/Worker/Client/TowFoundation/ProcessReceipts.php
+  - worker2/Worker/Forecast/Import.php
+related:
+  - ../architecture.md
+  - ../features/team-sprint-management.md
+  - ../features/platform-cache-cleanup.md
+  - ../../../1.0/apps/tools/workflows/deploy-to-elastic-beanstalk-al2023.md
+  - ../../../clients/tow-foundation/features/receipt-processing.md
+---
+
+## Summary
+
+The procedure used to move worker2 from **PHP 8.3 to PHP 8.5** on Elastic Beanstalk, and the
+dependency work that had to land first. It is written as a reusable checklist because every
+TOGA repo will face the same sequence as EB platform branches advance.
+
+Trigger: an EB `app-deploy` to `_sandbox-dev` failed at **"Install composer dependencies"** with
+
+```
+Your lock file does not contain a compatible set of packages...
+phpoffice/phpspreadsheet is locked to version 1.30.2 ... requires php >=7.4.0 <8.5.0
+-> your php version (8.5.8) does not satisfy that requirement.
+```
+
+Outcome: worker2 now runs **phpspreadsheet 3.10.7** on a single lock valid on both 8.3 and 8.5,
+and **both** EB environments (`_production` and `_sandbox-dev`) run PHP 8.5 on Amazon Linux 2023
+platform 4.13.4.
+
+## Step 1 — Diagnose the environment, not the branch
+
+`_production` and `_sandbox-dev` were **byte-identical** in `composer.json`, `composer.lock`
+(both phpspreadsheet 1.30.2), and all 21 `.platform/` + `.ebextensions/` files. The only
+difference was the EB environment's **PHP runtime**:
+
+| Environment | Platform |
+|---|---|
+| `_production` | PHP **8.3** running on 64bit Amazon Linux 2023/4.13.4 |
+| `_sandbox-dev` | PHP **8.5** running on 64bit Amazon Linux 2023/4.13.4 |
+
+Same platform branch, different PHP. The developer deleted and re-branched `_sandbox-dev` from
+`_production` and the failure **reproduced identically** — re-branching cannot fix an
+environment/runtime mismatch. When a deploy fails on one environment and not another with
+identical code, diff the **environment**.
+
+`vendor/` is gitignored in worker2, so this class of failure only ever surfaces at EB deploy
+time, never locally.
+
+## Step 2 — Audit the WHOLE lock for upper PHP bounds
+
+Composer reports only **"Problem 1"**. Before sizing a runtime upgrade, walk every locked
+package's `require.php` for an upper bound. Of worker2's **36** locked packages, exactly **one**
+carried a bound below 8.5 — `phpoffice/phpspreadsheet`. Everything else
+(`aws/aws-sdk-php`, `sentry/sentry`, guzzle, `phpseclib`, `phpmailer`, `symfony/*`,
+`markbaker/*`) was open-ended or 8.5-inclusive. Do not fix the first reported package and
+assume you are done.
+
+## Step 3 — Read the library's version-line policy, not just its constraint
+
+PhpSpreadsheet lines, all released 2026-07-12 (verified on Packagist + GitHub Releases):
+
+| Line | `require.php` | PHP 8.5? |
+|---|---|---|
+| 1.30.6 | `>=7.4.0 <8.5.0` | **deliberately excluded** (1.30.1+ tightened from 1.30.0) |
+| 2.4.7 | `>=8.1.0 <8.6.0` | yes, but capped at 8.6 |
+| 3.10.7 | `^8.1` | yes, no upper cap |
+| 5.9.0 | `^8.2` | current line |
+
+**Trap:** 1.30.0's `^7.4 || ^8.0` technically *permits* 8.5, and maintainers narrowed 1.30.1+
+to `<8.5.0` **on purpose**. So downgrading to 1.30.0 — or pinning `config.platform.php` — makes
+`composer install` succeed while the code runs on an explicitly unsupported runtime. That
+converts a loud deploy failure into silent runtime breakage. There is a composer-only way to
+make 1.x *install* on both 8.3 and 8.5; there is **no** composer-only way to make it *safe*.
+
+## Step 4 — Pick the target: `^3.10`, not 2.4 and not 5.x
+
+- **`^3.10`** (resolved 3.10.7) — supports 8.3 and 8.5 with **no 8.6 cap**, and its breaking
+  surface is limited to the 2.0 removals (Step 5).
+- **2.4.7** rejected: its `<8.6.0` cap would force a repeat migration at PHP 8.6.
+- **5.x** rejected: adds 4.0 behavioral changes (DataValidation stored per-worksheet not
+  per-cell; CSV reader stops auto-detecting Mac line endings; HTML writer emits `TRUE`/`FALSE`
+  instead of `1`/empty string; Xlsx writer `forceFullCalc` default flips) and 5.0 changes
+  (external images need `setAllowExternalImages(true)`; `DefaultValueBinder` binds integers
+  >15 digits as strings) — real risk to report output for **zero gain** on the 8.5 question.
+
+Also add an explicit **upper** bound to the repo's own root require:
+
+```json
+"php": ">=8.2 <8.6"
+```
+
+3.10.7 itself allows up to `<9.0`, so the repo bound is the deliberate binding constraint —
+when a future EB platform lands PHP 8.6, composer fails pointing at **worker2's own**
+requirement rather than at a confusing transitive library error.
+
+**Resolve the lock on the lowest runtime you must support.** The lock was produced locally on
+PHP 8.2.12 (below both 8.3 and 8.5), which yields the most **conservative** package set — valid
+on 8.3 and 8.5 alike, so no `config.platform.php` pin was needed.
+
+`ezyang/htmlpurifier` is **dropped** as a transitive dependency going 1.x → 3.x. Safe here
+(zero direct usage in worker2) — check it in any other repo doing this upgrade.
+
+## Step 5 — Migrate the call sites (`*ByColumnAndRow` removed in 2.0)
+
+PhpSpreadsheet 2.0 removed **all** deprecated `*ByColumnAndRow` methods ("All deprecated things
+have been removed"). **856** call sites migrated across 3 files: `Worker/Team/Sprint.php` (828),
+`Worker/Client/TowFoundation/ProcessReceipts.php` (20), `Worker/Forecast/Import.php` (8).
+
+The mapping — coordinates become an **array**:
+
+```php
+->setCellValueByColumnAndRow($c, $r, $v)             => ->setCellValue([$c, $r], $v)
+->setCellValueExplicitByColumnAndRow($c, $r, $v, $t) => ->setCellValueExplicit([$c, $r], $v, $t)
+->getCellByColumnAndRow($c, $r)                      => ->getCell([$c, $r])
+->getStyleByColumnAndRow($c1, $r1, $c2, $r2)         => ->getStyle([$c1, $r1, $c2, $r2])
+->mergeCellsByColumnAndRow($c1, $r1, $c2, $r2)       => ->mergeCells([$c1, $r1, $c2, $r2])
+```
+
+Per-method counts: `setCellValue` 447, `getStyle` 341, `mergeCells` 53, `getCell` 14,
+`setCellValueExplicit` 1.
+
+**Method gotcha:** a naive regex breaks on nested calls and on commas inside string literals.
+The migration used a paren/quote/comment-aware transform that splits only **top-level** commas
+and **validates each call's arity** against an expected set, skipping and reporting anomalies
+rather than silently rewriting. Result: 856/856 converted, 0 skipped, 0 anomalies, `php -l`
+clean on all three files, zero residual `ByColumnAndRow` in the repo.
+
+**Verified empirically against installed 3.10.7** (not assumed from docs): 4-element
+`getStyle([1,1,3,1])` really does style the full range (A1 and C1 both bold), the 2-element
+`getStyle([2,2])` targets a single cell, `mergeCells([1,5,3,5])` yields `A5:C5`, and both styles
+and merges survive an Xlsx save/load round-trip.
+
+## Step 6 — Bump the runtime as its own isolated change
+
+The safe sequence, and the reason it is safe:
+
+1. Make the code run on **both** runtimes first — one lock valid on 8.3 and 8.5. `_production`
+   therefore stayed deployable to the old 8.3 environment throughout the transition.
+2. Prove it on `_sandbox-dev` (already 8.5).
+3. **Then** bump `_production`'s EB platform 8.3 → 8.5 as an isolated, independently
+   revertible change.
+
+Never a combined code+runtime jump — if it breaks you cannot tell which half did it. The
+alternative of downgrading `_sandbox-dev` to 8.3 was explicitly declined: it hides the problem
+that production will hit next.
+
+Post-upgrade verification: `Platform/Cache/Truncate` confirmed working on PHP 8.5 (see
+[Platform Cache Cleanup](../features/platform-cache-cleanup.md)).
+
+## Open risk — pre-existing composer advisories (own ticket)
+
+**Unrelated to this work and not introduced by it.** `composer audit` reports **16
+medium-severity** advisories across 4 packages, principally:
+
+| Package | Locked | Fixed in | Advisories |
+|---|---|---|---|
+| `guzzlehttp/guzzle` | 7.10.0 | >= 7.15.1 | CVE-2026-59883, CVE-2026-55767, CVE-2026-55568 |
+| `guzzlehttp/psr7` | 2.9.0 | >= 2.12.3 | CVE-2026-59882, CVE-2026-55766, CVE-2026-49214 |
+
+Plus cookie-scope / `Referer` / `Proxy-Authorization` leakage advisories. Deliberately left out
+of the 8.5 branch to keep it a single-concern change — **needs its own ticket.**
+
+## Key rules
+
+- **Identical code failing on one environment only = diff the environment.** Re-branching never
+  fixes a runtime mismatch.
+- **Audit every locked package's PHP bound**, not just the one composer names.
+- **Never pin `config.platform.php` or downgrade to a version that merely *permits* the new
+  PHP** to silence a deploy error — that trades a loud failure for a silent one.
+- **Run `composer update` on the lowest runtime you must support** so one lock covers all
+  environments.
+- **Carry an explicit upper PHP bound in the repo's own root `require`** so the next runtime
+  jump fails pointing at us.
+- **Code first (dual-runtime), runtime second (isolated).**
+
+## Change history
+- 2026-07-29 — Initial capture. worker2 upgraded phpspreadsheet 1.30.2 → 3.10.7 (`^3.10`) and
+  root require `>=8.2` → `>=8.2 <8.6`; 856 `*ByColumnAndRow` call sites migrated to the array
+  coordinate form across `Team/Sprint.php`, `Client/TowFoundation/ProcessReceipts.php`, and
+  `Forecast/Import.php`; `ezyang/htmlpurifier` dropped as a transitive dep. Production EB
+  environment then bumped PHP 8.3 → 8.5 (AL2023 platform 4.13.4) as an isolated change — both
+  environments now 8.5. 16 pre-existing medium composer advisories (guzzle 7.10.0, psr7 2.9.0)
+  flagged for a separate ticket. (jcardinal)

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 40 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 34 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 35 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 19 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 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/knowledge/clients/tow-foundation/features/receipt-processing.md

@@ -5,8 +5,8 @@ project: Worker
 client: tow-foundation
 type: client-feature
 status: active
-updated: 2026-07-17
-owners: ["rgirish"]
+updated: 2026-07-29
+owners: ["rgirish", "jcardinal"]
 files:
   - worker2/Worker/Client/TowFoundation.php
   - worker2/Worker/Client/TowFoundation/ProcessReceipts.php
@@ -14,6 +14,7 @@ files:
   - worker2/Worker/Client/TowFoundation/TowFoundationCategories.php
 related:
   - clients/tow-foundation/profile.md
+  - ../../../2.0/apps/worker2/workflows/php-runtime-upgrade-dependency-audit.md
 ---
 
 ## Summary
@@ -353,6 +354,13 @@ Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
 
 ## Gotchas / known issues
 
+- **PhpSpreadsheet coordinates are ARRAYS now (3.x).** worker2 runs phpspreadsheet 3.10.7 on
+  PHP 8.5; every `*ByColumnAndRow` method was removed in PhpSpreadsheet 2.0. The 20 call sites
+  in `ProcessReceipts.php` use the array form (`->setCellValue([$col, $row], $v)`,
+  `->getStyle([$c1, $r1, $c2, $r2])`). Do not paste older QB-Excel layout code using the old
+  signatures. See
+  [PHP Runtime Upgrade on Elastic Beanstalk](../../../2.0/apps/worker2/workflows/php-runtime-upgrade-dependency-audit.md).
+
 - **`$year` variable shadowing** — `Run()` uses `$year` as both a filter parameter and a
   loop variable (line ~159: `$year = $receipt['year']`). After the loop `$year` holds the
   last receipt's year, not the original filter value. Harmless now but fragile if the loop
@@ -465,6 +473,10 @@ Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
 
 ## Change history
 
+- 2026-07-29 — Migrated the **20** `*ByColumnAndRow` call sites in `ProcessReceipts.php` to
+  PhpSpreadsheet's array-coordinate API (phpspreadsheet 1.30.2 → 3.10.7, required by worker2's
+  PHP 8.3 → 8.5 runtime move). No intended change to the QB Excel output. (jcardinal)
+
 - 2026-07-17 — **Memo fidelity overhaul + in-sheet Review column + cycle-aware MoveBack + offline export.** All in `ProcessReceipts.php`. (1) FIXED: the AI was paraphrasing/inventing the payment memo — rewrote the `extractReceiptData()` prompt + `payment_memo` schema to transcribe a human-added note **verbatim** and return **`null`** (never infer) when none exists; removed the old "infer a memo" instruction (client-reported: `"Lucy Ball of Lone Pine Foundation"`→`"LB LPFoundation"`, and a fabricated Asana memo). (2) FIXED: statement `Notes` override silently failed when AI OCR'd the wrong **year** — `matchStatementCandidate()` now falls back to a month+day (year-ignoring) date match so the authoritative Notes memo still wins despite year drift. (3) BUILT: in-sheet `Review` column (`buildExcelRow`+`generateExcel`) flags `"VERIFY AMOUNT (no matching charge on statement)"` (e.g. Ololo Safari KES `$172,872` OCR'd vs USD `$1,340.09`) and `"ADD MEMO (no note found on receipt)"` — the client reviews the Excel, not the email, so unverified/blank rows must surface in the sheet. (4) BUILT: prompt now scans the **entire page** (margins/corners/header/beside address) for visually-distinct human notes (missed a highlighted Optimum "Telephone & Internet" box, a red Garelick "Board Meeting … Remaining Deposit", an orange Lucid "IT Software License"). (5) BUILT: strip a leading 1–2-caps-plus-colon initials tag (`"RF:"`) from the memo — enforced in the prompt **and** as a deterministic `stripInitialsPrefix()` backstop that leaves 3+-letter prefixes (`"Postage:"`) alone. (6) BUILT: cycle-aware `MoveBack($scopeToCycle=true)` + `cycleDateWindow()`/`archivedFileDate()` — restore now moves only files whose archived-filename date falls in the cycle window (Amex = day-after-prior-3rd → this-3rd), instead of dumping the whole Archive into one cycle. (7) BUILT: read-only `DownloadCycleFiles(person, billingCycle, destDir, year, match, includeArchive)` — downloads a person's cycle receipts + statement Excel(s) to a local dir (constrained inside `__DIR__`), walking Archive via `collectPersonArchiveFiles()`, falling back to all statements when none matches. (8) DISCOVERED: local `Run()` always ends in a non-fatal `Unknown database 'logs_towfoundation'` at `_Email->send()` (Excel is generated + uploaded before that step, so work succeeds); Nadia Alia's statements are raw Amex "Transaction Details" exports with no `Notes` column (blank `ADD MEMO` memos are correct for her; no statement covers `06-04..07-03`); Talos is currently pointed at beta (`api.beta.togaiq.com`). Code changes remain **uncommitted** on the `_production` working tree (`fix/towfoundation-memo-verbatim` branch proposed, not yet created). (rgirish)
 - 2026-07-13 — **Read-only Preview action + Ligia map-key fix + July cycle findings.** (1) BUILT: `Preview(?year, ?person, ?billingCycle): string` — a true dry-run that reuses `walkReceiptsFolder()` and the same filters as `Run()` but only tallies (downloads/extracts/moves nothing, sends no email), returning pretty JSON with per-person receipt counts, cycles, fileTypes, up-to-3 sampleFiles, and hasStatement, plus a softer `personsWithNoReceipts` list. Read `persons[]` as the authoritative empty signal; `personsWithNoReceipts` is derived from statement-only folders and also surfaces stray top-level folders (e.g. "Processed") as cosmetic noise. (2) FIXED: `CLASS_MAP`/`PAYMENT_ACCOUNT_MAP` keys for Ligia Marroquin Soto were `"Ligia Marroquin"` (no "Soto") — never hit against the folder-derived `"Ligia Marroquin Soto"`, so her Class + Payment Account silently blanked (both maps fall back to `''` with no warning). Renamed keys to `"Ligia Marroquin Soto"` (Class ⇒ `Administration:Operations`, Payment Account ⇒ `AMEX Open Credit Card:Ligia Marroquin-Soto Amex CC`); broadened the person-folder-normalization gotcha — map keys MUST equal `folder − " CC receipts"`. (3) DISCOVERED: July Amex `"07-03-2026"` has 72 receipts across 9 people (Nadia Alia 43 …); Diane Sierpina, Brent Peterkin, Susan Ransden empty for July; Ryan Farrell + Magdalena Minta have July receipts but no statement → AI-inferred memos; **Michael Zuber Zander** has a receipts folder but is in neither map (and zero receipts) → left unmapped pending client-provided QB Class + Payment Account. Also recorded that SharePoint creds live in the `[sharepoint_towfoundation]` Config ini section, read via `_Config::sharepoint_towfoundation()`. (rgirish)
 - 2026-07-13 — **Per-person QB Excel location fix + two production findings.** (1) FIXED: `uploadExcelToSharePoint()` now writes each person's generated QB Excel to that person's own `Credit Card Receipts/{Person} CC receipts/{Year}/3. QB Excel/` subfolder (matching the docblock and client expectation) instead of a single shared root `3. QB Excel/`; signature is now `(accessToken, driveId, personFolderName, year, excelName, tmpFile)`, fed by a `$personFolders` map populated first-write-wins in Pass 1 with an `error_log` fallback to `{personName}/{currentYear}`. (2) DISCOVERED (production-critical gotcha): the statement-Notes lookup is EXACT string equality between the statement filename (`cycleKey`) and the receipt's billing-cycle FOLDER name — no date/fuzzy fallback — so a card whose folder has no identically-named statement silently skips the authoritative Notes memo and falls back to AI inference with zero signal (confirmed for Ryan Farrell's Mastercard folder vs. an Amex-named statement); also noted `computeRefNo()` hard-codes cycle-end day `03`, giving Mastercard rows a `…03…` Ref No. (pre-existing, unchanged). (3) DECIDED: monthly production procedure is two explicit per-card `Run` invocations (Amex + Ryan Farrell's Mastercard), NOT a "MM-YYYY month sweep" — the sweep prototype was deliberately reverted because `PAYMENT_ACCOUNT_MAP` is keyed per-person not per-card and would misattribute the QB Payment Account for anyone holding two cards in a swept month; recorded production-safety facts (no dry-run — `limit` still archives + emails; file moves reversible via `MoveBack` but email is not recallable; recipients are compile-time `NOTIFY_*` constants). (rgirish)

package/package.json

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