toga-ai 1.0.392 → 1.0.394

package/knowledge/1.0/apps/library/features/netsuite-suiteql-api-reference.md

@@ -6,8 +6,8 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
-owners: ["dfranks"]
+updated: 2026-07-21
+owners: ["dfranks", "jcardinal"]
 files:
   - library/app/api/netsuite/rest.php
   - library/ssl/netsuite_ec_key.pem
@@ -343,6 +343,13 @@ numbers. Budget hours for multi-year runs and launch them under `nohup`/`tmux`.
   arrow functions (`fn() =>`), typed properties (`public int $x`), `??=`, `match()`, numeric
   separators (`1_000`). Lint with `C:\xampp7\php\php.exe -l` before deploying — `C:\xampp8\php`
   (PHP 8.0) is for running probes on the laptop only, **not** for compat checking.
+  - **⚠ Blast radius: a SINGLE PHP 7.4+ token here is a FULL outage, not a localized bug.** On
+    2026-06-10 one `static fn(...)` left in `library/app/api/netsuite/rest.php` **parse-errored
+    `App_Api_Netsuite_Rest` on class load** — since the parse failure happens at require time, it
+    took down **every** consumer of the class at once: **all** 5-minute REST sync crons crashed and
+    stayed down until the token was reverted. There is no partial degradation — a banned token
+    anywhere in this file crashes the whole NetSuite REST tier. Lint before every deploy; treat a
+    7.4+ token in `rest.php` as a production-down defect, not a style nit.
 - Field/relationship availability varies by NetSuite account **and** record type — probe the live
   account before assuming a column exists.
 - **`IS NOT NULL` on a custom `transactionline` column inside an aggregate query is a ~15× planner
@@ -364,6 +371,11 @@ numbers. Budget hours for multi-year runs and launch them under `nohup`/`tmux`.
 
 ## Change history
 
+- 2026-07-21 — **Recorded the "one PHP 7.4+ token = total outage" blast-radius lesson** on the PHP
+  7.2 compat gotcha (folded in from a retired project-local CLAUDE.md). On 2026-06-10 a single
+  `static fn(...)` in `rest.php` parse-errored `App_Api_Netsuite_Rest` on class load and crashed ALL
+  5-minute REST sync crons until reverted — a banned token here is production-down, not localized.
+  (jcardinal)
 - 2026-07-07 — **Added the `systemnote` field-change forensics section and qualified the custom-column
   perf rule** (Forecast2 SALES profit-drift forensics). `systemnote` filtered by `field`+`"date"` is
   ~1s vs ~279s by `recordid` alone; it carries `context` (`UIF`), `name` (acting user), `role`,

package/knowledge/1.0/apps/worker/INDEX.md

@@ -5,7 +5,7 @@
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
 | [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php |
-| [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/checker.php, worker2/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
+| [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/checker.php, worker2/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/reconcile_drift_2023plus.php, test/@dave/probe_invoice_gap_2026.php, test/@dave/probe_creditmemo_gap_detail.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, library/app/api/netsuite/rest.php, library/app/systemmonitor/netsuiteintegration.php |
 | [OneUptime external uptime monitoring for 1.0 workers](features/oneuptime-worker-uptime-monitoring.md) | Every 1.0 worker box self-reports its liveness to an external OneUptime monitor once per minute by curl-POSTing to a per-worker "Incoming Request" heartbeat URL | library/app/worker.php, worker/crons/worker/worker_heartbeat.php |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |

package/knowledge/1.0/apps/worker/features/forecast2-netsuite-reconciliation.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-14
-owners: [dfranks]
+updated: 2026-07-21
+owners: [dfranks, jcardinal]
 files:
   - test/@dave/checker.php
   - worker2/Component/Forecast/SaleImport/SaleImport.php
@@ -16,6 +16,9 @@ files:
   - test/@dave/fixer.php
   - test/@dave/analyze_netsuite_forecast_diff.php
   - test/@dave/trueup_sales.php
+  - test/@dave/reconcile_drift_2023plus.php
+  - test/@dave/probe_invoice_gap_2026.php
+  - test/@dave/probe_creditmemo_gap_detail.php
   - test/@dave/trueup_open_orders.php
   - test/@dave/loop_trueup_open_orders.php
   - test/@dave/trueup_opportunities.php
@@ -98,6 +101,15 @@ by reconciling a chosen tranDate range directly against NetSuite.
   NS_ONLY (missing from FC), FC_ONLY (stale/extra), DRIFT (value differs). Read-only.
 - `trueup_sales.php --from --to [--chunk-days N] [--prod] [--dry-run]` — makes `Forecast.Sales`
   match NetSuite for a tranDate range (insert/update/delete per line).
+- `reconcile_drift_2023plus.php` — **transaction-level** (NOT line-level) reconciler for a
+  **known, small, discrepant set** of transactions. Distinct from the line-level trueup tools: for
+  **only the flagged transactions** it **DELETEs all lines then re-INSERTs them from REST**, writes
+  a **pre-image CSV backup** first, and is **dry-run by default** (`--commit` to write). Built to
+  close the SOAP-era double-line bug (below): it took the 2023 gap from **+$2.27M to +$31.8K**.
+  **Decision rule — which reconciler:** a **known small discrepant set** → `reconcile_drift_2023plus`
+  (transaction-level delete+reinsert); an **unknown full-window** drift → `trueup_sales`
+  (line-level insert/update/delete). **Diagnostic ladder to identify the set:**
+  `probe_sales_gap_direct` → `probe_invoice_gap_2026` → `probe_creditmemo_gap_detail`.
 - `trueup_open_orders.php --from= --to= [--prod] [--dry-run] [--verbose] [--quiet] [--by-lastmodified]`
   — same for `Forecast.OpenOrderItems` (currently-open SOs whose tranDate falls in range).
   - **`--by-lastmodified`** windows **both** passes on `lastmodifieddate` instead of `tranDate`:
@@ -303,6 +315,17 @@ None — Forecast2 is a single shared dataset.
 
 ## Gotchas / known issues
 
+- **SOAP-era double-line bug (2023) — lines inserted TWICE under consecutive-but-different line
+  numbers, evading the dup check.** The SOAP-era importer **ran twice for some invoice batches** and
+  inserted each invoice's lines **twice** under consecutive-but-*different* `lineNumber`s — so the
+  `(txnId, lineNumber)` duplicate check never caught it (the second copy had a different line
+  number). **Fingerprint:** Forecast revenue is **exactly 2× NetSuite**, **transaction counts
+  match** (it's line duplication, not extra transactions), and **FC line rows > NS line count**.
+  Affected **3 months in 2023** (transaction dates **May 1 / Jul 2 / Dec 7**). Fixed with
+  `reconcile_drift_2023plus.php` (transaction-level delete-all-lines-then-reinsert-from-REST), which
+  closed the 2023 gap from **+$2.27M to +$31.8K**. When a window shows exact-2× revenue with matching
+  txn counts and more FC lines than NS, suspect this pattern and use the transaction-level reconciler,
+  not the line-level trueup.
 - **CROSS-TYPE CONTAMINATION: once JEs share `Forecast.Sales`, any FC Sales read missing a type scope
   treats JE rows as rogue sales.** Discovered live (TRUE-79862): the SALES fix **deleted 74 JE rows
   (8 JEs) as "stale sales"** because `findSalesDiscrepancies`'s FC query had **no type filter**, so JE
@@ -549,6 +572,17 @@ None — Forecast2 is a single shared dataset.
 
 ## Change history
 
+- 2026-07-21 — **Documented `reconcile_drift_2023plus.php` + the SOAP-era double-line bug (2023)**
+  (folded in from a retired project-local CLAUDE.md). The SOAP-era importer ran twice for some
+  invoice batches and inserted each invoice's lines twice under consecutive-but-different line
+  numbers, evading the `(txnId, lineNumber)` dup check — fingerprint = FC revenue exactly 2× NS,
+  matching txn counts, FC line rows > NS lines; affected 3 months in 2023 (txn dates May 1 / Jul 2 /
+  Dec 7). `reconcile_drift_2023plus.php` reconciles a **known small set** at the **transaction level**
+  (DELETE all lines then re-INSERT from REST for only flagged txns; pre-image CSV backup; dry-run by
+  default, `--commit` to write), closing the 2023 gap from +$2.27M to +$31.8K. Recorded the decision
+  rule (known small set → `reconcile_drift_2023plus`; unknown full window → `trueup_sales`) and the
+  diagnostic ladder (`probe_sales_gap_direct` → `probe_invoice_gap_2026` →
+  `probe_creditmemo_gap_detail`). (jcardinal)
 - 2026-07-14 — **`fixer.php` now resolves `customerId` on JE lines, mirroring the importer +
   recorded the manual all-time backfill** (TRUE-80129, dfranks). `fixJournalEntries()` (the
   hand-maintained mirror of `buildJournalEntryRows`) previously hard-coded `customerId = NULL`;

package/knowledge/2.0/apps/_underscore/features/netsuite-rest-client.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-26
-owners: ["dfranks"]
+updated: 2026-07-21
+owners: ["dfranks", "jcardinal"]
 files:
   - _underscore/Component/Api/Netsuite/Netsuite.php
 related:
@@ -31,6 +31,40 @@ SuiteQL escaping rule — that callers in other repos depend on.
 > (`\api\_Component_Api_Netsuite`) for its own use. Editing the api2 copy has **no effect** on the
 > worker2/webhook path — change the `_underscore` one.
 
+## Authentication & config
+
+- **OAuth 2.0 certificate-signed JWT client assertion.** The adapter authenticates by signing a
+  JWT client assertion with a certificate registered on the NetSuite integration record — no
+  username/password, no stored bearer. Signing algorithm is **ES256 preferred** (EC private key),
+  with **RS256 as fallback**. The access token is **cached and auto-refreshed ~60s before expiry**,
+  so callers never manage token lifecycle.
+- **All credentials come from the `[netsuite]` ini section — nothing is hardcoded.** Keys:
+  - `host` — the NetSuite REST host.
+  - `clientId` — the integration record's client id.
+  - `certificateId` — the integration record's certificate id (the JWT **`kid`**).
+  - `privateKeyPath` — filesystem path to the signing private key.
+  The per-developer block lives in `worker2/Config/dev-<name>-laptop.ini`. **Document only the key
+  names/locations — never paste the values.** (See the 1.0 `netsuite-suiteql-api-reference.md`
+  *Authentication* section for the sibling `App_Api_Netsuite_Rest` client, which reads the same
+  `[netsuite]` section via `_Config::netsuite()` in the 2.0 context.)
+
+### Public API surface
+
+- **`send($method, $route, $payload, $headers, $throwExceptionsOnError)`** — the general REST call.
+  Verb + route + JSON payload + optional extra headers; `$throwExceptionsOnError` toggles whether a
+  non-2xx raises or is returned. (Record writes go through `createRecord`/`send('PATCH', …)` above;
+  reads through `fetchRecord`/`send('GET', …)`.)
+- **`RECORD_*` constant catalog** — canonical route constants so callers never hardcode record
+  paths: `SALES_ORDER`, `INVOICE`, `CASH_SALE`, `CASH_REFUND`, `CREDIT_MEMO`, `OPPORTUNITY`, `ITEM`,
+  `INVENTORY_ITEM`, `CUSTOMER`, `EMPLOYEE`, `VENDOR`, `PURCHASE_ORDER`.
+- **`QUERY_SUITEQL`** — the SuiteQL query route; **`METADATA_CATALOG`** — the metadata/catalog route
+  (record & field metadata discovery).
+- **`?expandSubResources=true`** — append to a record GET to inline sub-resources (sublists) in one
+  call rather than issuing follow-up requests.
+- **Response normalization rule:** the underlying transport may hand back an already-decoded object
+  **or** a raw JSON string, so normalize every response with `is_string($x) ? json_decode($x) : $x`
+  before consuming it.
+
 ## Record writes — REST has no SOAP `baseRef->internalId`
 
 ### Create — `createRecord(string $route, array $payload): string`
@@ -121,6 +155,13 @@ doc.)
 
 ## Change history
 
+- 2026-07-21 — **Documented the auth mechanism, config-key locations, `send()` signature, and the
+  `RECORD_*`/query/metadata constant catalog** (folded in from a retired project-local
+  `worker2/netsuite/CLAUDE.md`). Auth = OAuth 2.0 certificate-signed JWT client assertion
+  (ES256 preferred / RS256 fallback), token cached + refreshed ~60s before expiry; all credentials
+  from the `[netsuite]` ini section (`host`/`clientId`/`certificateId`=`kid`/`privateKeyPath`),
+  per-dev block in `worker2/Config/dev-<name>-laptop.ini`. Recorded `?expandSubResources=true` and
+  the `is_string($x) ? json_decode($x) : $x` response-normalization rule. (jcardinal)
 - 2026-06-26 — **`fetchRecord` (generic NS REST GET + decode) moved onto this class** from
   `_Component_Forecast_Db`, beside `createRecord`; 7 callers reprefixed (SaleImport ×2,
   Opportunity ×3, SalesOrder ×2), git-grep clean + runtime-verified. Recorded the

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

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-07-20
+updated: 2026-07-21
 owners: [jcardinal, mhammontree, bala]
 files:
   - Core/
@@ -173,6 +173,13 @@ its own header.)
    the relevant clients list `<module>` in their `_modules.txt`.
 5. Never edit or re-date an already-applied file — add a new dated file instead. Never put new
    work in a `HISTORIC` folder.
+6. **Never seed a `uuid` column with MySQL `UUID()`.** The 2.0 standard requires a fully-random
+   **v4** UUID; `UUID()` is time/MAC-based (v1) and violates it. Since a migration can't call
+   `_String::generateUuid()`, **pre-generate a v4 UUID literal** (e.g. a v4 generator) and
+   hardcode the literal string in the `VALUES` clause. One earlier migration
+   (`Core/2026-05-08 … CronJobs_WorkerCleanup_insert`) used `UUID()` — that is a known violation,
+   not a precedent to copy. First applied correctly in
+   `Core/2026-07-21b - Insert - SprintLockScheduled CronJob.sql`.
 
 ## Bulk data loads — batch, and stage large sets in a temp table
 
@@ -285,3 +292,10 @@ platform-wide infrastructure, not a single application. It has no code dependenc
 folder names mirror the DB families (`Core`, `Logs`, `Client_<Tenant>`, `Logs_<Tenant>`)
 defined in `2.0/apps/_underscore/architecture.md`, and its change files create/alter the
 tables that `_Model_*` classes map to.
+
+## Change history
+- 2026-07-21 — Added rule #6 to *Adding a new change*: never seed a `uuid` column with MySQL
+  `UUID()` (time/MAC-based v1, violates the 2.0 v4-UUID standard); pre-generate a v4 UUID
+  literal and hardcode it in `VALUES`. `Core/2026-05-08 … CronJobs_WorkerCleanup_insert` is a
+  known violation, not a precedent; first applied correctly in
+  `Core/2026-07-21b - Insert - SprintLockScheduled CronJob.sql`. (jcardinal)

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

@@ -28,7 +28,7 @@
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |
 | [Talos Pricing Automation (worker2 Cron — AWS Actuals, Calibration, Monthly Report)](features/talos-pricing-automation.md) | The worker2 half of the **Talos Pricing Platform** (see the talos `pricing-cogs-model` and tools `talos-pricing-ui` docs for the other halves). | worker2/Worker/Talos/Pricing.php, worker2/Database/TalosPricingCrons.sql |
 | [Talos Transcript Ingestion Pipeline (worker2 → AWS Bedrock KBs)](features/talos-transcript-ingestion.md) | `_Worker_Team_Transcripts` runs a fully automated, cron-driven pipeline that ingests raw Teams transcripts into the **Talos / TOGa IQ** AWS Bedrock knowledge ba | worker2/Worker/Team/Transcripts.php, worker2/bin/sync-knowledge-bases.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Team/2026-06-30a, dbchanges2/Team/2026-06-30b, dbchanges2/Team/2026-06-30c, dbchanges2/Team/2026-06-30d, dbchanges2/Team/2026-06-30e, dbchanges2/Core/2026-06-30a, dbchanges2/Core/2026-07-02a, dbchanges2/Team/2026-07-02a, dbchanges2/Team/2026-07-08a, dbchanges2/Team/2026-07-09a, dbchanges2/Team/2026-07-10a |
-| [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 |
+| [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, dbchanges2/Core/CronJobs (SprintLockScheduled seed) |
 | [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 |

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -111,11 +111,29 @@ No Lambda/routing changes — just create the file:
 2. Insert a `Core.CronJobs` row:
    ```sql
    INSERT INTO Core.CronJobs (uuid, isActive, name, schedule, maxExecutionTime, action, parameters)
-   VALUES (UUID(), 1, 'Daily Report Generation', '0 6 * * *', 300, 'Reports/Daily/Generate', NULL);
+   VALUES ('xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx', 1, 'Daily Report Generation', '0 6 * * *', 300, 'Reports/Daily/Generate', NULL);
+   -- uuid MUST be a pre-generated v4 UUID literal, NOT MySQL UUID() (v1) — see dbchanges2 architecture.md rule #6
    ```
    `schedule` is evaluated in **Central time**; `maxExecutionTime` is the watchdog timeout.
 3. CronScheduler fires it at the next matching minute — no code wiring needed.
 
+Adding a recurring job is **pure data**: inserting the `Core.CronJobs` row (uuid, isActive,
+name, schedule, maxExecutionTime, action, parameters) is all that's needed. The CronScheduler
+Lambda runs every minute, matches active schedules via `croniter`, and enqueues a `WorkerJobs`
+job. There is **no Lambda/code change** beyond the row — but the referenced `action` must exist
+in the deployed worker code, so ship the code deploy and the dbchanges2 cron-row migration
+**together**.
+
+> **Biweekly / non-cron schedules — run often, self-gate in PHP.** Cron (5-field) can express
+> "every Wednesday" but **not** "every *other* Wednesday" (or any period cron can't name).
+> Don't try to encode it in the schedule. Instead schedule the job at the coarser recurring
+> interval it fits (e.g. `0 10 * * 3`) and have the action **self-gate against a date/state
+> table** at the top of the method — run the real work only when the gate says today qualifies,
+> otherwise return a skip message (captured to `Core.WorkerJobs.output`). Proven by
+> `Team/Sprint/SprintLockScheduled`, which fires every Wednesday but only runs `SprintLock()`
+> when a `Sprints` row ends yesterday — see
+> [team-sprint-management](./team-sprint-management.md).
+
 ## Test any action directly
 
 ```bash
@@ -175,6 +193,12 @@ be reattempted.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-07-21 — Documented that adding a recurring job is **pure data** (a `Core.CronJobs` row;
+  CronScheduler Lambda matches via croniter every minute, no code wiring beyond the row — but
+  the action must be deployed), and the **biweekly self-gating pattern**: for schedules cron
+  can't express (e.g. every-other-Wednesday), run at a coarser cron interval and gate in PHP
+  against a date/state table, returning a skip otherwise. Proven by
+  `Team/Sprint/SprintLockScheduled`. (jcardinal)
 - 2026-07-21 — `WorkerJobs.failureReason` column renamed to **`output`** and repurposed to store
   successful execution results as well as failure text; success now writes the composed
   "Successfully Executed" message (return value `json_encode`d for arrays/objects). (jcardinal)

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

@@ -6,10 +6,11 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-24
+updated: 2026-07-21
 owners: ["jcardinal"]
 files:
   - worker2/Worker/Team/Sprint.php
+  - dbchanges2/Core/CronJobs (SprintLockScheduled seed)
 related:
   - ../architecture.md
   - ./creating-worker-actions.md
@@ -64,6 +65,10 @@ A sprint runs ~14 days. Across the cycle these actions fire (scheduled as crons)
 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.
+   In production this is now invoked via the scheduled self-gating wrapper
+   `SprintLockScheduled` (see below), not by a cron that targets `SprintLock` directly —
+   because the launch day is **every other Wednesday** and cron cannot express a biweekly
+   schedule.
 4. **Daily during the sprint** — `SprintDaily` emails leadership a progress dashboard.
 
 Most methods accept an optional `$sprint` number; when omitted they resolve the relevant
@@ -89,6 +94,21 @@ alert. With `$generateSprintLockReport`, emits an Excel lock report of committed
 unplanned/stretch points and tasks. When `$allowUnplannedTasks` is false, tasks appearing
 after lock with an UNPLANNED work type are flagged.
 
+### `SprintLockScheduled(): string`
+A thin **scheduled wrapper around `SprintLock()`** that solves the biweekly-schedule problem.
+The launch/lock ceremony runs every *other* Wednesday, but cron has no biweekly expression, so
+its `CronJobs` row fires **every** Wednesday (`0 10 * * 3`, 10:00 AM Central) and this method
+**self-gates in PHP** against the `Sprints` table: it queries for a sprint whose `dateEnd` =
+**yesterday**. If one exists, today is a new-sprint start day → it calls `self::SprintLock()`.
+Otherwise it returns a skip message (captured to `Core.WorkerJobs.output`) and does nothing.
+`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
+> `Team/Sprint/SprintLockScheduled` action, which must exist in the deployed code or the
+> scheduled job fails when it fires.
+
 ### `SprintDaily($sprint = null, …)`
 In-sprint **leadership dashboard**, read-only with respect to metrics. Optionally re-captures
 ClickUp data, then builds a multi-sheet workbook:
@@ -210,6 +230,13 @@ backfills `workTypeAtLock` the first time a task is seen).
 
 ## Change history
 
+- 2026-07-21 — Added `SprintLockScheduled()` action + a `Core.CronJobs` seed
+  (`0 10 * * 3`, every Wednesday 10 AM Central, action `Team/Sprint/SprintLockScheduled`,
+  maxExecutionTime 600) to run **Sprint Lock automatically at the start of each biweekly
+  sprint**. Cron can't express "every other Wednesday", so the job runs every Wednesday and
+  self-gates in PHP: it calls the unchanged `SprintLock()` only when a `Sprints` row has
+  `dateEnd = yesterday` (i.e. today starts a new sprint), else returns a skip. Worker code and
+  the dbchanges2 cron-row migration must deploy together. (jcardinal)
 - 2026-06-24 — Fixed a duplicate-key crash (`Tasks.sprintId_clickupIdentifier`) in the
   ClickUp→DB sync: ClickUp pagination can return the same task on multiple pages, and the
   loop was overloading one map (`$lookupTaskByClickUpId`) for both update-vs-insert and

package/package.json

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