toga-ai 1.0.272 → 1.0.274

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

@@ -9,7 +9,7 @@
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Error Reporting — Issue/Event Aggregation (exceptionHandler)](features/error-reporting-issue-event.md) | `_underscore`'s global exception handler persists every uncaught exception into a two-table **Issue / Event** model in the **shared Core Logs DB** (`_underscore | _underscore/Error.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |
-| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
+| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |

package/knowledge/2.0/apps/_underscore/features/forecast-sale-import.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-07
 owners: [dfranks]
 files:
   - _underscore/Component/Forecast/SaleImport/SaleImport.php
@@ -29,6 +29,7 @@ files:
   - test/@dave/verify_je_classification.php
   - test/@dave/probe_je_accounts.php
   - test/@dave/probe_je_shape.php
+  - test/@dave/fixer.php
   - test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js
   - test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js
 related:
@@ -184,12 +185,21 @@ item-line upsert/reconcile machinery (`syncLines`/`guardedInsert`/`deleteRows`).
   per-run **account-number allowlist isolates exactly the lines that carry the rep** — offset/
   balancing lines omit class/entity/`custcol_sales_rep_line`, so they group to null and are
   dropped. No schema/migration (`salesRepEmployeeId` already on `Forecast.Sales`).
-- **JE lines carry NO item field at all — item ingestion from NetSuite is not possible.**
-  Confirmed across multiple Apr–May 2026 JEs: the full union of line keys is
-  `{account, class, cleared, debit, credit, custcol_sales_rep_line, entity, line, memo, location}`.
-  There is **no native `item` and no custom item column**. `JE_LINE_ITEM_FIELD` stays **null
-  by design**; kept lines now group **per-salesRep with a null item**. The dimension that
-  exists *instead of* item is **`entity`** (the customer ref). Probe tool:
+- **JE lines carry their item in a CUSTOM column `custcol_item_sku` — NOT the native item
+  field (corrected 2026-07-07, TRUE-79973).** The **native** `transactionline.item` /
+  REST `line.item` is **empty on every JE rev/cost line** (live probe 2026-07-07: empty on
+  all 12,293 2026 JE revenue/cost lines) — which is why earlier probing concluded "no item
+  column exists." The SKU actually lives **line-level** on each rev/cost GL line in
+  **`custcol_item_sku`**, shaped **identically to `custcol_sales_rep_line`**: a NetSuite
+  **reference object** `line.custcol_item_sku = {id, refName, links}` where `.id` (a JSON
+  string) is the item **internalId** (e.g. `"1103457"`). It maps to Forecast via
+  `lookupId('Items','netsuiteItemInternalId', .id)`. In SuiteQL it is `tl.custcol_item_sku`
+  returning the raw internal id — **filter/group with `> 0`, never `IS NOT NULL`** (same
+  ~15x IS-NOT-NULL perf trap as `custcol_sales_rep_line`; see the SuiteQL custom-column doc).
+  This is the plug-in point for `JE_LINE_ITEM_FIELD` (previously null "no item column
+  exists"). Consequence: the earlier TRUE-79968/79970 design that grouped every kept JE line
+  under `itemId=NULL` is now **wrong** — kept lines carry a real item. The `entity`
+  (customer ref) dimension still exists in addition to item. Probe tool:
   `test/@dave/probe_je_shape.php` (dumps line column shapes + custom columns).
 - **No salesRep self-heal (unlike the item path).** `journalLineLookup()` for Employees has
   **no `syncEmployee()` fallback** (the item path self-heals via
@@ -442,6 +452,20 @@ record is deleted in NetSuite.)
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 2026-07-07 — **CORRECTION: JE lines DO carry an item — in the custom column
+  `custcol_item_sku`, not the native item field** (TRUE-79973, dfranks). Live probe
+  2026-07-07 confirmed native `transactionline.item` / REST `line.item` is empty on **all
+  12,293** 2026 JE rev/cost lines, while the SKU is populated **line-level** on each rev/cost
+  GL line in `custcol_item_sku` as a reference object `{id, refName, links}` (`.id` = item
+  internalId, e.g. `"1103457"`), identical in shape to `custcol_sales_rep_line`. Maps via
+  `lookupId('Items','netsuiteItemInternalId', .id)`; SuiteQL exposes `tl.custcol_item_sku`
+  (raw id) — filter/group with `> 0`, not `IS NOT NULL` (same perf trap). This is the plug-in
+  point for `JE_LINE_ITEM_FIELD` (previously null "no item column exists") and **overturns**
+  the earlier TRUE-79968/79970 assumption that JE lines carry no item and group under
+  `itemId=NULL`. Touch-points for the backfill/import work:
+  `_underscore/Component/Forecast/SaleImport/SaleImport.php` (`JE_LINE_ITEM_FIELD`,
+  `journalLineLookup`, `buildJournalEntryRows`) and `test/@dave/fixer.php` (JE line SuiteQL).
+  (dfranks)
 - 2026-06-30 — **JE import now keeps ONLY rep-bearing lines** (TRUE-79968, dfranks).
   `buildJournalEntryRows` skips any GL line whose **raw** `custcol_sales_rep_line` is empty,
   applied **per-line before** the (salesRep,item) bucketing: a no-rep JE → 0 Sales rows, a

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

@@ -3,6 +3,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 |
+| [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 |
 | [ClickUp Design Sprint Automation (Final Design Outcome)](features/clickup-design-sprint-automation.md) | `_Worker_Clickup_Design` is meant to drive the design-sprint workflow in ClickUp via the API, replacing a set of native ClickUp automations. | worker2/Worker/Clickup/Design.php, worker2/Worker/Clickup.php |
 | [ClickUp GitHub-tab Auto-linking & Ticket-id Branch Naming](features/clickup-github-autolink.md) | How ClickUp surfaces branches/PRs/commits in a ticket's **GitHub tab**, and the branch / PR-title naming convention that triggers it. |  |

package/knowledge/2.0/apps/worker2/features/automated-pr-merger-force-push-race.md

@@ -0,0 +1,71 @@
+---
+title: Automated PR Merger — Concurrent Force-Push Clobber Race
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-07-06
+owners: [dfranks]
+files:
+  - Worker/Team/Github.php
+related:
+  - ./clickup-github-autolink.md
+---
+
+## Summary
+
+The automated PR merger `_Worker_Team_GitHub::Merge` (`worker2` `Worker/Team/Github.php`)
+merges approved PRs to `_production` by **force-pushing from a clone taken before the read,
+without rebasing**. When two merges run concurrently, the second force-push silently
+overwrites the first merge's commit, orphaning it. This is a silent data-loss failure mode
+in shared deploy tooling — it affects **every repo** merged through the automated merger,
+not just one file.
+
+## How it works (the failure mode)
+
+- The merger clones/reads `_production`, applies the merge, then `git push --force`.
+- Because the push is a `--force` from a stale clone with no rebase, a merge that landed
+  in the window between the read and the push is **overwritten** — its commit is no longer
+  an ancestor of `_production`.
+- GitHub still reports the clobbered PR as **MERGED** (the merge happened; it was just
+  force-pushed away afterward), so **no error surfaces**. The changed files never reach the
+  deployed bundle.
+- Real occurrence: a merged `worker2` webhook handler file was orphaned ~40s later by a
+  concurrent automated merge — MERGED on GitHub, absent from `_production`.
+
+## Diagnostic — auditing for clobbered PRs
+
+For every PR GitHub reports as MERGED into `_production`, test whether its merge commit is
+still an ancestor of the branch:
+
+```
+gh pr list --repo <repo> --base _production --state merged --json number,mergeCommit
+git merge-base --is-ancestor <mergeCommitSHA> origin/_production   # exit 0 = ancestor (fine)
+```
+
+If `--is-ancestor` is **false**, the PR was clobbered (orphaned). Then **confirm real loss**:
+check whether the PR's changed files actually exist on `_production` today. A stale
+force-push artifact can be non-ancestor yet have had its content re-applied by a later
+merge — that case is benign.
+
+## Fix direction (do NOT just add a rebase)
+
+Rebasing alone is **insufficient**: it only narrows the check-then-act window. A `--force`
+push after a rebase can still clobber a merge that lands between the rebase and the push.
+
+Durable fix:
+- **Drop `--force`** — use a plain `push` (or `--force-with-lease`) so a stale push is
+  **rejected as non-fast-forward** instead of silently overwriting.
+- Add a **retry loop** (re-fetch → re-rebase → retry) on rejection, **or serialize merges
+  behind a lock**.
+- Rebase makes the non-force push succeed on the happy path; **dropping `--force` is what
+  makes it safe.**
+
+## Change history
+
+- 2026-07-06 — Initial doc: documented the `_Worker_Team_GitHub::Merge` concurrent
+  force-push clobber race (MERGED-on-GitHub-but-orphaned, silent), the `git merge-base
+  --is-ancestor` audit procedure with the benign-artifact caveat, and the fix direction
+  (drop `--force`/use `--force-with-lease` + retry/lock, not rebase alone) (dfranks)

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 22 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 26 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 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/package.json

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