toga-ai 1.0.565 → 1.0.567

package/.claude/settings.json

@@ -13,7 +13,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Bash|Read|Grep|Glob|Edit|Write|MultiEdit|NotebookEdit|Task|WebFetch|WebSearch",
+        "matcher": "Bash|Read|Grep|Glob|Edit|Write|MultiEdit|NotebookEdit|Task|Agent|WebFetch|WebSearch",
         "hooks": [
           {
             "type": "command",

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

@@ -27,6 +27,7 @@
 | [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 |
 | [DB-free unit testing for _underscore model interceptors](features/model-interceptor-unit-testing.md) | `_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored PhpOffice tests existed). | _underscore/Test/bootstrap.php, _underscore/Test/Prudential/ServiceRequestTest.php, test/@Bala/tests/netsuite_salesorder_payload_tests.php |
 | [_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, _underscore/Model.php, _underscore/Model/Rate/Subscription.php |
+| [_Model::save() parent FK cascade — stored-SQL-field recompute deadlocks](features/model-save-parent-cascade-stored-field-deadlock.md) | `_Model::save()` runs a **generic parent foreign-key cascade**: inserting (or saving) a child row that carries an FK to a parent causes `_Model` to **re-load an | _underscore/Model.php, _underscore/Model/Client/PurchaseOrder.php, _underscore/Model/Client/AdvanceShippingNotice.php |
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php, _underscore/Model/Rate/Subscription.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 |
 | [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | `_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models** (every client on the dbchanges2 `netsuite` module). | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Model.php, dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-07-27
+updated: 2026-08-13
 owners: ["jcardinal", "rgirish", "mhammontree"]
 files:
   - _underscore/_underscore.php
@@ -38,6 +38,7 @@ business logic never moves into Surface config.
 Storage fields (`FIELD_STORAGE`) must be written by assigning then `save()` — historically a
 `__get` refetch on the write path silently dropped the assigned value (fixed 2026-07); still avoid
 *reading* a storage field between assign and save (it refetches and discards the unsaved value).
+`_Model::save()` **cascades to FK parents** — saving a child re-saves its parent to refresh the parent's stored SQL fields (`FIELDOPT_SQL_STORED`). A stored field that aggregates the parent's own children (e.g. a correlated-subquery total) therefore re-emits a parent+children lock on **every** child insert and will **deadlock (MySQL 1213)** under concurrent same-parent inserts; opt a model out with `$_model_skipParentCascadeOnSave` when no touched parent's stored field can go stale.
 
 ## Entry point & boot sequence
 
@@ -401,4 +402,5 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 - 2026-07-02 — Fixed framework-wide `FIELD_STORAGE` write-drop and folder-read bugs in `Model.php`; noted the remaining unconditional-refetch dirty-read follow-up. (mhammontree)
 - 2026-07-07 — Documented `_Query` writes-only async mode (`isAsync` → Worker `Infrastructure/Database/Query`) in the database-architecture section, linked `features/async-query-execution.md`, and noted the SQS-first `_Worker::runTask()` enqueue departure (caller does no MySQL; worker tier creates the row on pickup). (jcardinal)
 - 2026-07-16 — Documented the misleading "Unclosed '{'" parse-error gotcha (autoloader reports the outermost `class {` line / caller trace, not the true dropped-brace location; merge conflicts a common cause). First hit production 500 EO-1 via a dropped `_Email::send()` brace. (jcardinal)
+- 2026-08-13 — Documented that `_Model::save()` **cascades to FK parents** to refresh their `FIELDOPT_SQL_STORED` fields, so a parent stored field that aggregates its own children re-emits a parent+children lock on every child insert and **deadlocks (MySQL 1213)** under concurrent same-parent inserts; opt out with `$_model_skipParentCascadeOnSave`. (jcardinal)
 - 2026-07-23 — Fixed the Route.php swallow→mask gotcha: the controller-call catch now log+rethrows and catches `\Throwable` (not just `Exception`), so the true controller exception surfaces instead of the misleading line-525 "Failed to determine how to render view" fatal. Noted the deferred production `display_errors` info-leak follow-up. (jcardinal)

package/knowledge/2.0/apps/_underscore/features/calculated-sql-fields.md

@@ -6,13 +6,14 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-12
-owners: [snaredla]
+updated: 2026-08-13
+owners: [snaredla, jcardinal]
 files:
   - _underscore/Model.php
 related:
   - ../architecture.md
   - ./model-magic-field-access.md
+  - ./model-save-parent-cascade-stored-field-deadlock.md
 ---
 
 ## Summary
@@ -61,9 +62,21 @@ recalculated per query; `true` persists to a real column on save).
   expression has not been defined…"*.
 - **`FIELDOPT_SQL_STORED => true` needs a refresh after bulk migrations** — the stored value is
   written on save, so rows changed by raw SQL keep a stale value.
+- **A stored SQL field that aggregates the model's own children is a deadlock risk under the
+  `_Model::save()` parent cascade.** Because the cascade re-saves a parent (to refresh its stored
+  fields) on every child insert, a stored correlated-subquery field re-emits an UPDATE that X-locks
+  the parent and S-locks all its children on writes that change nothing it depends on — concurrent
+  same-parent child inserts then deadlock (MySQL 1213). This is exactly how `PurchaseOrder._total`
+  deadlocked the ASN path; see
+  [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md).
 
 ## Change history
 
+- 2026-08-13 — Added a gotcha: a `FIELDOPT_SQL_STORED` field that aggregates the model's own
+  children deadlocks under the `_Model::save()` parent cascade (correlated-subquery recompute
+  X-locks the parent + S-locks its children on every child insert). Cross-linked the new
+  [save-cascade stored-field deadlock](./model-save-parent-cascade-stored-field-deadlock.md) doc,
+  where `PurchaseOrder._total` on the ASN path is the worked example. (jcardinal)
 - 2026-08-12 — Documented the enforced `FIELD_SQL` contract after `_serialNumbers` was queried as a
   camelCase violation: `_Model` **throws** both when the field lacks the `_` prefix
   (`_underscore/Model.php` ~L130) and when a static method of the exact same name is missing

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-11
+updated: 2026-08-12
 owners: ["dfranks", "jcardinal", "mhammontree", "ajean", "bala"]
 files:
   - _underscore/Error.php
@@ -438,20 +438,41 @@ app that has not been wired up yet.
 in `_underscore` and `library` in the **same** release, and the `/errors` console work needs
 **both** `library` and `tools` deployed before it is visible.
 
-## ⚠ OPEN DEFECT (2026-08-06) — error capture is DEAD on sandbox-dev/beta: `Logs.Issue` is missing `clickupPriority`
+## ✅ RESOLVED (2026-08-12) — error capture was DEAD on sandbox-dev: `Logs.Issue` was missing SEVEN columns (originally filed as one)
 
-**Anyone debugging on that environment is flying blind.** The capture INSERT fails with **MySQL 1054
-(unknown column)** because `Logs.Issue` there has `clickupAssigneeId` and `createsClickupTask` but
-**not `clickupPriority`**. Consequences:
+**Filed 2026-08-06 as a single missing column (`clickupPriority`); it was actually SEVEN.** On
+**2026-08-12**, debugging a `/v2/surfaces/meta` 500 that returned `EO-1` with a null `error.id` and
+wrote nothing to `Logs.Event`, a live `information_schema` diff of dev-sandbox `Logs.Issue` (**23
+columns**) against `_Model_Core_Logs_Issue` (**30 columns**) found **seven** missing columns:
+`clickupPriority` (migration `dbchanges2/Logs/2026-08-03a`) **plus the entire `2026-08-05a` lifecycle
+migration** — `status`, `dtAutoResolved`, `baselineGapSeconds`, `baselineSampleCount`,
+`dtBaselineAnchor`, `baselineAnchorOccurrences`. `_Model::save()` builds its INSERT from **all 30
+declared fields**, so the first absent column throws **MySQL 1054 (unknown column)** and the whole
+capture aborts. **Anyone debugging on that environment was flying blind.** While broken:
 
 - **No error is persisted at all** — no `Logs.Issue` row, no `Logs.Event` row, no ClickUp task.
-- The only trace is inline in the API response as **`identifiers.captureFailure`**. If you are
-  looking in the database or ClickUp for an error you just triggered and finding nothing, look at the
-  response body for `captureFailure` before concluding the error didn't happen.
-
-**Cause:** `_underscore` commit `4ebe12fe` *"Improve error fingerprinting, add ClickUp priority
-tracking"* shipped the code that writes the column **without its schema migration reaching that
-environment.** Fix is a one-column `dbchanges2` migration in the `Logs` folder.
+- The only trace is inline in the API response as **`identifiers.captureFailure`** — and that is
+  **debug-mode-gated**, so on a deployed non-prod box with debug off the caller sees `identifiers: []`
+  and has *nothing*. (This blind spot is now closed — see the controller hardening below.)
+
+**Cause:** both `dbchanges2/Logs/2026-08-03a` and `2026-08-05a` exist in the repo but **never ran on
+dev-sandbox** — the runner tracks applied files per environment (see `Logs/2026-07-29a`), and these two
+were skipped there. The originally-filed "one missing column, needs a one-column migration" was correct
+about the mechanism but **undercounted the drift** — reading the 2026-08-06 note alone would have left
+six columns still missing.
+
+**Resolution (2026-08-12):** **re-applied the two existing migrations (`2026-08-03a`, then `2026-08-05a`)
+to dev-sandbox** — no new migration was written; capture came back to life immediately (`Logs.Issue`/
+`Logs.Event` rows written, `error.id` populated). **Still verify the same drift on beta and every other
+non-prod env** before trusting their capture.
+
+**Controller hardening (api2, 2026-08-12):** `api2/Controller/Index.php` now surfaces
+`identifiers.captureFailure` on **every environment except production** (`_Environment::$name !==
+'production'`), even with debug mode off — in both the `execute()` catch and the DB-bootstrap catch. The
+exception `message`/`trace` stay debug-only (they carry `_Database::register()` frame-arg credentials);
+`captureFailure` names only *why the recorder failed* and cannot leak them. A dead capture layer now
+announces itself instead of returning empty `identifiers`, so this class of `Logs` schema drift can never
+again be silent on a non-prod box.
 
 **The general lesson (this is the pipeline's structural weak point):** error capture is the one
 subsystem whose own failure cannot be reported through itself. A schema drift here does not degrade
@@ -631,6 +652,17 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-12 — **Corrected the 2026-08-06 open defect and marked it RESOLVED.** The sandbox-dev
+  `Logs.Issue` drift was **seven** missing columns, not one: `clickupPriority` (`2026-08-03a`) **plus the
+  whole `2026-08-05a` lifecycle migration** (`status`, `dtAutoResolved`, `baselineGapSeconds`,
+  `baselineSampleCount`, `dtBaselineAnchor`, `baselineAnchorOccurrences`) — found by an
+  `information_schema` diff (live 23 cols vs. model 30 cols) while debugging a `/v2/surfaces/meta` 500
+  that returned `EO-1` with a null `error.id` and wrote no `Logs.Event`. Both migrations existed but had
+  **never run on dev-sandbox** (the runner tracks applied files per environment); **re-applying the two
+  existing files** restored capture — no new migration. Also **hardened `api2/Controller/Index.php`** to
+  surface `identifiers.captureFailure` on every non-production environment even with debug off
+  (`message`/`trace` stay debug-only, as they carry DB creds), so a dead capture layer can no longer be
+  invisible on a non-prod box. (jcardinal)
 - 2026-08-11 — Sharpened the `error.id` lookup recipe from a production incident investigation
   (Compass, api2 500s): **`status = 'RESOLVED'` with `dtAutoResolved` set and `isManaged = 0` is a
   cron auto-close after a quiet window, not a fix** — it is indistinguishable from a real fix on

package/knowledge/2.0/apps/_underscore/features/model-save-parent-cascade-stored-field-deadlock.md

@@ -0,0 +1,121 @@
+---
+title: _Model::save() parent FK cascade — stored-SQL-field recompute deadlocks
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-13
+owners: [jcardinal]
+files:
+  - _underscore/Model.php
+  - _underscore/Model/Client/PurchaseOrder.php
+  - _underscore/Model/Client/AdvanceShippingNotice.php
+related:
+  - ./calculated-sql-fields.md
+  - ./model-save-vs-query-atomic-update.md
+  - ../../api2/features/v2-deadlock-retry.md
+  - ../../../../clients/compass-usa/features/asn-to-item-fulfillment.md
+---
+
+## Summary
+
+`_Model::save()` runs a **generic parent foreign-key cascade**: inserting (or saving) a child row
+that carries an FK to a parent causes `_Model` to **re-load and re-save that parent** so the
+parent's stored SQL fields (`FIELDOPT_SQL_STORED => true`) are refreshed. When a parent's stored
+field is a **correlated subquery** over the parent's own children, that re-save emits an UPDATE
+that **X-locks the parent row and S-locks every child row** — even though the child insert never
+changed any value the stored field depends on. Under concurrent inserts of children for the **same
+parent**, this is a textbook **MySQL 1213 deadlock**. This is the definitive diagnosis for the api2
+ASN-path deadlocks (see *Root case study*), and a reusable framework gotcha: **a stored SQL field
+whose expression aggregates the model's children turns every child insert into a full parent-plus-
+children lock.**
+
+## How it works
+
+- The cascade lives in `_Model::save()` (`Model.php` ~L360-390). Saving a model with a populated FK
+  to a parent re-loads that parent and calls `save()` on it, whose purpose is to recompute and
+  persist the parent's `FIELDOPT_SQL_STORED` columns.
+- `_Model_Client_PurchaseOrder` declares `_total` as a **stored** SQL field
+  (`Model/Client/PurchaseOrder.php:36`, `FIELDOPT_SQL_STORED => true`). Its expression is a
+  correlated subquery:
+
+  ```sql
+  UPDATE PurchaseOrders
+  SET dtUpdated = NOW(),
+      _total = (
+        SELECT SUM(PurchaseOrderItems.quantity * PurchaseOrderItems.cost)
+        FROM PurchaseOrderItems
+        WHERE purchaseOrderId = PurchaseOrders.id
+      )
+  WHERE id = <poId>
+  ```
+
+- Inserting an `AdvanceShippingNotices` row (FK `purchaseOrderId`) therefore re-saves its
+  PurchaseOrder, re-emitting that statement. The subquery reads **all** `PurchaseOrderItems` for the
+  PO (S-locks) while the outer UPDATE X-locks the PO row. Two concurrent same-PO ASNs acquire these
+  locks in opposing orders → **1213**. The ASN insert never touches `PurchaseOrderItems.quantity`
+  or `.cost`, so the recompute is **pure collateral** — the deadlocking statement is not written by
+  any PO or ASN code, it is emitted by the framework cascade.
+
+## Root case study — Compass Office Depot cXML ASN feed
+
+- 100% of the api2 1213 deadlocks were the identical `_total` UPDATE above, on
+  `POST /v2/advance-shipping-notices`, all from the Office Depot cXML feed
+  (`sourceIp 34.232.23.158`). Evidence: `Logs_Compass.Api` on the prod-logs cluster.
+- Deadlocks cluster **per-PO** (one PO hit 5-7x within minutes) and are **bursty** (31 on
+  2026-08-13 vs a 2-4/day baseline) — the fingerprint of Office Depot **re-transmitting the same
+  ASN** for days, producing concurrent same-PO ASN inserts.
+
+## Mitigation — `$_model_skipParentCascadeOnSave` opt-out (source fix, "B2")
+
+A protected flag on `_Model`, `$_model_skipParentCascadeOnSave` (default **false** → no behavior
+change for any existing model). When `true`, `_Model::save()` **skips the parent FK cascade**.
+`_Model_Client_AdvanceShippingNotice` opts in from its constructor
+(`$this->_model_skipParentCascadeOnSave = true`), so no ASN insert re-saves its PurchaseOrder and
+the deadlocking statement is removed from the ASN path entirely.
+
+**Why this is safe for ASN, for every client (reviewed):** among the ASN's four parents
+(PurchaseOrder, Vendor, Address, ShippingMethod) only `PurchaseOrder._total` is a stored SQL field,
+and it depends **solely** on `PurchaseOrderItems.quantity`/`cost` — values an ASN never touches. So
+skipping the cascade cannot make any stored field stale. The opt-out is placed on the **base client
+ASN model** (all clients) deliberately, because the premise is schema-level, not Compass-specific.
+**Accepted caveat:** the PO's `dtUpdated` is no longer bumped on ASN receipt.
+
+## Gotchas / known issues
+
+- **A stored SQL field that aggregates the model's own children makes every child insert a
+  parent+children lock.** Before marking a field `FIELDOPT_SQL_STORED => true` on a high-fan-in
+  parent, consider that every child write will re-emit its recompute under the parent cascade.
+- **The deadlocking UPDATE is invisible in child/parent code.** Grepping PO or ASN code for the
+  `_total` UPDATE finds nothing — it is generated by the cascade in `Model.php`. Diagnose from the
+  DB error log statement, not the application code path.
+- **Skipping the cascade is only correct when no touched parent has a stored field that could go
+  stale from this child's write.** `$_model_skipParentCascadeOnSave` is a per-model opt-out, not a
+  global switch — verify the parents' stored fields before opting a model in.
+
+## Decisions
+
+- **Making `_total` non-stored (the cleaner fix) is BLOCKED cross-repo.** The `worker` repo's
+  toga2-supply transmit crons SELECT `PurchaseOrders._total` as a **raw physical column** (e.g.
+  `crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php`, plus the `quad` /
+  `compasscanada` equivalents and `DOA/open_purchase_order_reminder.php`). If the column were kept
+  but no longer maintained, those crons would read stale values. Making `_total` non-stored requires
+  first migrating every such consumer to compute the total inline. Until then, the opt-out flag is
+  the source fix.
+- **Deploy blast radius.** 4 of 5 changed files live in `_underscore`, which is pulled into every
+  2.0 app at deploy — so this is platform-wide. All changes are additive / default-safe; **no
+  SQL/schema change**. As of 2026-08-13 the code is **in the working tree only** — not committed or
+  deployed — pending sandbox validation and regression tests.
+
+## Change history
+- 2026-08-13 — Diagnosed the api2 `_total` deadlocks (100% identical UPDATE on Office Depot cXML
+  ASN inserts) to the `_Model::save()` parent FK cascade re-saving `PurchaseOrder` to refresh its
+  **stored** `_total` correlated-subquery field, which X-locks the PO and S-locks all its items on a
+  write that changes neither. Added the `$_model_skipParentCascadeOnSave` opt-out (default false),
+  opted the base client ASN model in, and recorded that making `_total` non-stored is blocked by
+  `worker` crons reading it as a physical column. Code in working tree, pending sandbox validation.
+  (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/_underscore/features/model-save-vs-query-atomic-update.md

@@ -6,14 +6,15 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: ["dfranks", "mhammontree"]
+updated: 2026-08-13
+owners: ["dfranks", "mhammontree", "jcardinal"]
 files:
   - _underscore/Model.php
   - _underscore/Query.php
   - _underscore/Model/Rate/Subscription.php
 related:
   - ./model-magic-field-access.md
+  - ./model-save-parent-cascade-stored-field-deadlock.md
   - ../../worker2/features/netsuite-opportunity-sync.md
   - ../../../../clients/rate/features/subscription-cancellation.md
 ---
@@ -108,9 +109,18 @@ retry loops, and compensating transactions all need the reload.
   affected-rows count. Use raw `_Query` + `getAffectedRows()`.
 - A no-diff `save()` emits **no** UPDATE, so "the write must have run because save() returned" is not a
   safe assumption.
+- **`save()` also cascades to parents.** Saving a model with a populated FK re-saves its parent to
+  refresh the parent's stored SQL fields — a hidden extra UPDATE that can deadlock under concurrency.
+  See [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md)
+  and the `$_model_skipParentCascadeOnSave` opt-out.
 
 ## Change history
 
+- 2026-08-13 — Noted that `save()` **cascades to parents** (re-saves an FK parent to refresh its
+  stored SQL fields) — a hidden extra UPDATE that can deadlock under concurrent same-parent child
+  inserts; cross-linked the new
+  [save-cascade stored-field deadlock](./model-save-parent-cascade-stored-field-deadlock.md) doc and
+  its `$_model_skipParentCascadeOnSave` opt-out. (jcardinal)
 - 2026-08-04 — TRUE-80282: documented that **`initial` is never resynced after a save**
   (`Model.php:244` diffs on `initial !== value`; `initial` set only at load/initialize,
   `Model.php:702`), so a **second `save()` on the same instance omits the column entirely** — every

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

@@ -20,6 +20,7 @@
 | [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, api2/Component/Api/V2/Response/Oauth/Oauth.php, api2/Controller/Index.php, toga2-supply/src/globalTypes.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/api/toga.ts, _underscore/Model/Client/TrackingNumber.php |
+| [V2 request deadlock-retry — route-scoped in-process replay](features/v2-deadlock-retry.md) | api2's front controller can **detect a MySQL deadlock (1213) / lock-wait timeout (1205) and replay the whole request in-process**, so a transient lock collision | api2/Controller/Index.php, _underscore/Database.php, _underscore/Query.php |
 | [V2 REST query contract (params, where grammar, encoding, ACL behavior)](features/v2-rest-query-contract.md) | What an **HTTP client** has to get right to query the Toga v2 REST API: which query params are recognized, the exact `where` grammar, how the query string is (n | api2/Component/Api/V2/V2.php |
 | [V2 reverse hasMany collections must be named in the fetch fields whitelist](features/v2-reverse-hasmany-fields-whitelist.md) | In the V2 JSON engine, a **reverse hasMany** relationship — the collection of child records that foreign-key back to a parent (e.g. | api2/Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. | api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php, api2/.platform/hooks/prebuild/git.sh, api2/.ebextensions/git.php, api2/.ebextensions/git.sandbox-dev.json |

package/knowledge/2.0/apps/api2/features/v2-api-error-codes.md

@@ -176,6 +176,15 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
       a null payload, not an error — every consumer must null-guard, and "the page rendered empty"
       is a plausible symptom of a 500 you never saw.
 
+14. **A `4xx` validation (`EV-*`) response still leaks the raw failing SQL + DB name (pre-existing,
+    UNFIXED as of 2026-08-13).** Distinct from the 2026-07-30 fix that gated the 500 `message`/`trace`
+    behind `isDebugMode()`: on a DB error surfaced as a **validation** response, the `EV-10` body
+    returned to the **external** caller still contains the raw failing SQL statement **and the DB
+    name** (observed in Office Depot's 400 body on the ASN deadlock path). Worth scrubbing
+    independently. This is also **why deadlock detection was built on the MySQL errno** (1213/1205),
+    not on matching the response text — see
+    [V2 deadlock-retry](./v2-deadlock-retry.md).
+
 ## BREAKING (2026-07-30): `error` is now an object, not a bare string
 
 The V2 envelope's `error` changed from a bare string (`"EO-1"`) to an **object**:
@@ -261,6 +270,12 @@ Full mechanics:
 
 ## Change history
 
+- 2026-08-13 — Added diagnosis note 14: a **validation (`EV-10`) response still leaks the raw failing
+  SQL statement + DB name** to the external caller (seen in Office Depot's 400 body on the ASN
+  deadlock path) — distinct from and NOT covered by the 2026-07-30 500 `message`/`trace` gating;
+  pre-existing and unfixed, worth scrubbing. Noted it is why the new
+  [V2 deadlock-retry](./v2-deadlock-retry.md) detection keys on the MySQL errno rather than response
+  text. (jcardinal)
 - 2026-08-11 — Added **`EO-2`** to the map as a **catch-all mislabel**: `Controller/Index.php`'s
   `catch (Throwable $dbBootstrapError)` (~L364) wraps the entire dispatch, so any escaped Throwable
   is reported as *"A required database could not be reached while initializing the request"* — the

package/knowledge/2.0/apps/api2/features/v2-deadlock-retry.md

@@ -0,0 +1,92 @@
+---
+title: V2 request deadlock-retry — route-scoped in-process replay
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: draft
+updated: 2026-08-13
+owners: [jcardinal]
+files:
+  - api2/Controller/Index.php
+  - _underscore/Database.php
+  - _underscore/Query.php
+related:
+  - ../../_underscore/features/model-save-parent-cascade-stored-field-deadlock.md
+  - ../architecture.md
+  - ./v2-api-error-codes.md
+---
+
+## Summary
+
+api2's front controller can **detect a MySQL deadlock (1213) / lock-wait timeout (1205) and replay
+the whole request in-process**, so a transient lock collision self-recovers instead of returning an
+HTTP 400 to the caller. The replay is **route-scoped by an allowlist**
+(`DEADLOCK_RETRIABLE_ROUTES`) — currently only `/v2/advance-shipping-notices` — because whole-
+request in-process replay is **only safe for routes with no non-rollbackable external side effect**.
+This is the safety-net half of the ASN deadlock fix; the source-level fix (stop the collateral
+parent re-save) is in
+[_underscore's save-cascade doc](../../_underscore/features/model-save-parent-cascade-stored-field-deadlock.md).
+
+> Status (2026-08-13): **in the working tree only** — not committed or deployed. Pending sandbox
+> validation + regression tests.
+
+## How it works
+
+**Detection primitive (`_underscore`, reusable).** `_Database` gains
+`public static ?int $lastErrorNumber`, the consts `ERRNO_DEADLOCK` (1213) and
+`ERRNO_LOCK_WAIT_TIMEOUT` (1205), plus `clearLastError()` and `wasDeadlock()`. `_Query` records the
+driver errno **at its throw site**, and the recording is **sticky**: a later unrelated error does
+**not** overwrite an already-recorded deadlock. That stickiness is what lets a deadlock caught
+inside a model-save `try/catch` still be visible to the outer controller and trigger a retry.
+
+**Retry loop (`api2/Controller/Index.php`).** The v2 dispatch is wrapped in a bounded loop
+(`MAX_DEADLOCK_ATTEMPTS = 3`). On an unsuccessful response where `_Database::wasDeadlock()` is true
+and the route is in `DEADLOCK_RETRIABLE_ROUTES`, the controller:
+
+1. rolls back all open transactions;
+2. wipes `_Database::$_transactionStarts` so every connection re-begins via the umbrella
+   lazy-transaction path on replay;
+3. resets the query + model caches;
+4. applies a **jittered backoff**;
+5. replays the **entire** request.
+
+## Key design constraint (durable) — replay-safety allowlist
+
+Whole-request in-process replay is **only safe** for a route that has:
+
+- **no non-rollbackable external side effect** before/around the deadlock — no NetSuite SOAP, no
+  email, no S3, no third-party HTTP; and
+- **no destructive superglobal mutation** before the point of failure.
+
+The V2 ASN request was verified side-effect-free end-to-end (all writes are local DB or in-process
+`internalApiRequest`), which is why it is the only allowlisted route. Other routes are **not**
+replay-safe and must stay off the list:
+
+- the **OAuth** path destructively mutates `$_POST`;
+- **`/purchase-orders`** fires email + SQS;
+- **`/units`** hits NetSuite.
+
+**Before adding any route to `DEADLOCK_RETRIABLE_ROUTES`, prove the whole request is replayable** —
+idempotent or transaction-scoped, with no irreversible side effect and no consumed/mutated
+superglobal. Default is to leave a route off the list.
+
+## Gotchas / known issues
+
+- Detection is built on the **MySQL errno** (1213/1205), not on matching the response text —
+  deliberately, because the raw error text is not a reliable signal (and, separately, api2's
+  validation error body still leaks the failing SQL + DB name; see
+  [V2 API error codes](./v2-api-error-codes.md)).
+- Retry is bounded (`MAX_DEADLOCK_ATTEMPTS = 3`) with jittered backoff — it is a collision damper,
+  not a substitute for removing the deadlock at its source.
+
+## Change history
+- 2026-08-13 — Added deadlock/lock-wait detection to `_Database`/`_Query` (`$lastErrorNumber`,
+  `wasDeadlock()`, sticky errno recording) and a bounded, route-scoped in-process replay loop in
+  `Controller/Index.php`, gated to `/v2/advance-shipping-notices` only. Documented why whole-request
+  replay is allowlisted (no non-rollbackable external side effect; no destructive superglobal
+  mutation) — OAuth mutates `$_POST`, `/purchase-orders` fires email/SQS, `/units` hits NetSuite, so
+  they are excluded. Working tree only, pending sandbox validation. (jcardinal)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -18,9 +18,9 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 55 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 56 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 48 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 22 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 23 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 6 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/knowledge/clients/compass-usa/features/asn-to-item-fulfillment.md

@@ -22,6 +22,8 @@ files:
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
   - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
+  - ../../../2.0/apps/_underscore/features/model-save-parent-cascade-stored-field-deadlock.md
+  - ../../../2.0/apps/api2/features/v2-deadlock-retry.md
 ---
 
 ## Summary
@@ -161,6 +163,17 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
   number) straight into queries. These are now passed through `_Database::escape()`.
 - Separate latent bug in the 1.0 worker: the Strategic Systems cron's no-serials branch
   builds `$itemLevelTrackingNumbers` but never attaches it to the ASN payload.
+- **MySQL 1213 deadlocks on this path are a framework cascade, not ASN code (diagnosed
+  2026-08-13).** Office Depot re-transmits the same ASN for days, so one PO receives many
+  concurrent same-PO ASN inserts. Each `AdvanceShippingNotices` insert (FK `purchaseOrderId`) trips
+  the generic `_Model::save()` parent cascade, which re-saves the PurchaseOrder to refresh its
+  **stored** `_total` correlated-subquery field — X-locking the PO row and S-locking all its
+  `PurchaseOrderItems` on a write that changes neither. Concurrent same-PO ASNs then deadlock. 100%
+  of the observed 1213s were this one `_total` UPDATE. Two mitigations (working tree, pending
+  validation): the base client ASN model opts out of the parent cascade
+  (`$_model_skipParentCascadeOnSave`), and api2 retries the ASN route on a detected deadlock. Full
+  mechanic:
+  [save-cascade stored-field deadlock](../../../2.0/apps/_underscore/features/model-save-parent-cascade-stored-field-deadlock.md).
 - **Cross-line tracking contamination from bad SOI↔POI bridge rows (root cause, fixed
   forward 2026-06-11):** `postPost` resolves which IFI(s) a tracking number attaches to by
   joining `AdvanceShippingNoticeItems → SalesOrderItems_PurchaseOrderItems → SalesOrderItems`.
@@ -208,6 +221,11 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
 
 ## Change history
 Dated one-liners, newest first.
+- 2026-08-13 — Diagnosed the recurring MySQL 1213 deadlocks on `POST /v2/advance-shipping-notices`
+  (Office Depot cXML feed): 100% were the `_total` UPDATE emitted by the `_Model::save()` parent
+  cascade re-saving the PurchaseOrder on each ASN insert, deadlocking under concurrent same-PO ASN
+  re-transmissions. Recorded as a gotcha with the two working-tree mitigations (ASN model cascade
+  opt-out + api2 route-scoped deadlock retry). (jcardinal)
 - 2026-07-02 — Repaired SA133377 (SO 107609, line 1 MD7F4LL/A-S): the customer IF (IFI 276821)
   had no serial and the wrong tracking (`522944658493` — the first of two tracking-only vendor
   ASNs on PO 103641 that reconciled onto the direct-ASN IF 70635) instead of `873840444805`

package/knowledge/sessions/2026-08-12-api2-error-capture-schema-drift-jcardinal.md

@@ -0,0 +1,87 @@
+---
+type: session
+slug: api2-error-capture-schema-drift
+title: Fix invisible api2 500s (sandbox-dev Logs.Issue schema drift killed error capture); harden the recorder and the kickoff KB-priming gate
+author: jcardinal
+repos: [api2, _underscore, dbchanges2]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-08-12
+updated: 2026-08-12
+---
+
+# Session: api2-error-capture-schema-drift
+**Date:** 2026-08-12
+**Project/Repo:** api2, _underscore, dbchanges2 (2.0) + harness (`~/toga-tech` skills/hooks)
+**Task:** A `/v2/surfaces/meta` 500 on dev.sandbox returned `EO-1` with a null `error.id` and wrote
+nothing to `Logs.Event` — undebuggable. Find why nothing is recorded and make errors visible.
+
+---
+
+## What was wrong (root cause)
+
+api2's `Controller/Index.php` catches `Throwable` from `V2.php::execute()` and calls
+`_Error::captureException()` to record the error and mint an `error.id`. `captureException()` does
+`$issue->save()`, and `_Model::save()` builds its INSERT from **all 30 fields declared on
+`_Model_Core_Logs_Issue`**. Live **dev-sandbox `Logs.Issue` had only 23 columns** — the first missing
+one throws **MySQL 1054** and the whole capture aborts (returns `null`): no `Logs.Issue` row, no
+`Logs.Event` row, null `error.id`.
+
+Seven columns were missing (an `information_schema` diff, not the migration files — the files lag):
+- `clickupPriority` — `dbchanges2/Logs/2026-08-03a`
+- `status`, `dtAutoResolved`, `baselineGapSeconds`, `baselineSampleCount`, `dtBaselineAnchor`,
+  `baselineAnchorOccurrences` — the whole `dbchanges2/Logs/2026-08-05a` lifecycle migration
+
+Both migrations existed but had **never run on dev-sandbox** (the runner tracks applied files per
+environment — see `Logs/2026-07-29a`). The KB had this filed (2026-08-06) as **one** missing column;
+it was actually seven.
+
+**Second, compounding blind spot:** capture's only failure signal is
+`identifiers.captureFailure`, which the controller emitted **only in debug mode**. The deployed
+sandbox box runs with debug off, so the caller got `identifiers: []` — no hint at all.
+
+## What was done
+
+1. **Schema (fix that unblocked it):** re-applied the two existing migrations (`2026-08-03a` then
+   `2026-08-05a`) to dev-sandbox. No new migration. Capture came back immediately — confirmed fixed by
+   the developer. **Still verify beta and other non-prod envs for the same drift.**
+2. **Observability hardening (`api2/Controller/Index.php`):** surface `identifiers.captureFailure` on
+   **every environment except production** (`_Environment::$name !== 'production'`, new constant
+   `PRODUCTION_ENVIRONMENT_NAME`), even with debug off — in both the `execute()` catch and the
+   DB-bootstrap catch. `message`/`trace` stay **debug-only** (they carry `_Database::register()`
+   frame-arg DB credentials); `captureFailure` names only *why the recorder failed*, so it cannot leak
+   them. A dead capture layer now announces itself instead of returning empty `identifiers`.
+   *(Working tree only — not committed; a project repo, so the developer deploys it.)*
+3. **KB doc corrected:** `_underscore/features/error-reporting-issue-event.md` — the 2026-08-06 open
+   defect updated from one column to seven and marked RESOLVED, with the controller-hardening note.
+
+## Harness change (kickoff KB-priming enforcement)
+
+Prompted by a process failure this session: after `/kickoff`'s interview + preflight, the KB
+`context-primer` was spawned **in the background** while repo code was read **in parallel** — the team
+knowledge base was treated as a side-channel instead of the first source. Fixed so it cannot recur:
+
+- **`scripts/hooks/kickoff-gate.js`** is now **two-stage**: preflight no longer releases the gate — it
+  advances `armed → primer`. In `primer`, all repo `Read/Grep/Glob/Edit/Write` and every non-primer
+  agent stay **blocked** until the **`context-primer` subagent is spawned in the foreground**
+  (`run_in_background: false`); that spawn releases the gate. Reading `repo-path-<repo>` memories and
+  `AskUserQuestion` stay allowed.
+- **`.claude/settings.json`** — added `Agent` to the gate's `PreToolUse` matcher so it fires on
+  `Agent`-tool spawns.
+- **`skills/kickoff/SKILL.md`** — Step 4 rewritten to mandate KB-first, foreground, wait-for-it
+  subagent priming *before any other research* (even files named in the `/kickoff` sentence); the
+  top gate prose now describes the two stages.
+
+## Gotchas worth remembering
+- `_Model::save()` INSERTs **every declared field** — one missing `Logs` column silently kills ALL
+  capture on that environment (the recorder can't report its own failure). Any column added to a
+  `Logs` table must land its migration in **every** environment.
+- Read the **live** `Logs` schema (`information_schema` / `toga_describe_table`), not the `dbchanges2`
+  migration files — the files lag the deployed schema.
+- To debug an api2 500 you can't see: the `error.id` (`<Issue.reference>-<Event.eventNumber>`) →
+  `Logs.Issue.trace` by the reference (part before the dash) is the real stack; the response omits it.
+
+## Related
+- [[error-reporting-issue-event]] (the capture pipeline this session repaired + documented)
+- [[surface-meta-option]] (the endpoint whose 500 surfaced the blind spot)

package/package.json

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

package/scripts/hooks/kickoff-gate.js

@@ -2,32 +2,44 @@
 'use strict';
 
 /*
- * kickoff-gate.js — DETERMINISTIC enforcement of the /kickoff priming gate.
+ * kickoff-gate.js — DETERMINISTIC, TWO-STAGE enforcement of the /kickoff priming gate.
  *
- * Why this exists: the kickoff SKILL.md states a "hard gate" — when /kickoff is
- * invoked you MUST complete priming (Steps 0–6) BEFORE touching the task with any
- * Read/Grep/Glob/Edit/Write/Task call. Prose alone did not stop the model from
- * jumping straight to investigation when /kickoff was followed by a long, specific
- * task description. This hook makes the gate mechanical, not advisory.
+ * Why this exists: the kickoff SKILL.md states a "hard gate" — when /kickoff is invoked
+ * you MUST prime BEFORE touching the task. Prose alone did not stop the model from
+ * jumping to investigation when /kickoff was followed by a detailed task description.
+ * A first version of this hook released the gate the instant `kickoff-preflight` ran —
+ * but preflight only resolves the load-set; it does NOT read the team knowledge base.
+ * The model could (and did) run preflight, then read repo code BEFORE the team KB was
+ * primed, treating the knowledge base as a side-channel instead of the first source.
  *
- * It registers for TWO events from a single file:
+ * The team knowledge base is the whole point of kickoff — it is the distilled, shared
+ * gold the team maintains, and it must be primed FIRST, via the `context-primer`
+ * subagent, before ANY other research. This hook now enforces that in TWO stages:
  *
- *   UserPromptSubmit  → if the submitted prompt invokes /kickoff, ARM the gate:
- *                       write a session-scoped lock and inject a forceful reminder.
+ *   Stage 1  ARMED   (set by /kickoff)  — allow ONLY the read-only priming steps
+ *                    (version check, team-repo probe, manifest, interview) and
+ *                    `kickoff-preflight`. Everything else is blocked. Running
+ *                    `kickoff-preflight` ADVANCES the gate to stage 2 — it no longer
+ *                    releases it.
  *
- *   PreToolUse        → while the gate is armed for THIS session, ALLOW only the
- *                       read-only priming steps (the priming Bash commands + the
- *                       interview via AskUserQuestion/Skill, which don't match the
- *                       PreToolUse matcher) and BLOCK every task tool
- *                       (Read/Grep/Glob/Edit/Write/MultiEdit/NotebookEdit/Task/
- *                       WebFetch/WebSearch and any non-priming Bash). The lock
- *                       AUTO-CLEARS the moment `knowledge.js kickoff-preflight`
- *                       runs — the definitive priming step that precedes Step 4's
- *                       first Read. So the model literally cannot investigate or
- *                       edit the task until it has actually primed.
+ *   Stage 2  PRIMER  (set by preflight) — the load-set is known but the team KB is not
+ *                    yet primed. Block all repo research (Read/Grep/Glob of code, Edit,
+ *                    Write, and every non-primer agent) until the `context-primer`
+ *                    subagent is spawned IN THE FOREGROUND (run_in_background: false),
+ *                    so the model actually waits for the briefing. Spawning it releases
+ *                    the gate. Reading repo-path MEMORY files and asking the developer
+ *                    remain allowed (they are part of priming).
  *
- * Fail-open: any internal/parse error allows the tool (a crashing gate must never
- * brick every session). The SKILL.md prose remains the backup.
+ * Net effect: after the interview, the model literally cannot read a single repo file,
+ * grep the code, or spawn any other agent until it has primed from the team KB via the
+ * context-primer subagent. KB-first, via subagent, without exception.
+ *
+ * Registered for UserPromptSubmit (arm) + PreToolUse (enforce). A defensive
+ * PostToolUse branch is a no-op — release is spawn-time in PreToolUse, so the gate can
+ * never get stuck waiting on an event that did not fire.
+ *
+ * Fail-open: any internal/parse error allows the tool (a crashing gate must never brick
+ * every session). The SKILL.md prose remains the backup.
  *
  * Escape hatch: set KICKOFF_GATE_DISABLED=1 to disable enforcement entirely.
  */
@@ -61,10 +73,11 @@ function readLock() {
   try { return JSON.parse(fs.readFileSync(lockPath(), 'utf8')); } catch (e) { return null; }
 }
 
-function writeLock(sessionId) {
+// phase: 'armed' (priming not started) → 'primer' (preflight ran, team KB not yet primed).
+function writeLock(sessionId, phase) {
   try {
     fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
-    fs.writeFileSync(lockPath(), JSON.stringify({ session: sessionId || null, ts: Date.now() }) + '\n');
+    fs.writeFileSync(lockPath(), JSON.stringify({ session: sessionId || null, ts: Date.now(), phase: phase || 'armed' }) + '\n');
   } catch (e) { /* non-fatal */ }
 }
 
@@ -84,7 +97,7 @@ function invokesKickoff(prompt) {
 }
 
 /* Bash commands that ARE the read-only priming steps (Steps 0–3). Everything else
- * is task work and stays blocked until preflight clears the gate. */
+ * is task work and stays blocked. */
 function isPrimingBash(command) {
   if (typeof command !== 'string') return false;
   return /knowledge\.js|kickoff-preflight|toga-ai\.version|npm\s+view\s+toga-ai|npx\s+toga-ai|registry\.json|rev-parse/i.test(command);
@@ -94,58 +107,107 @@ function isPreflightBash(command) {
   return typeof command === 'string' && /kickoff-preflight/i.test(command);
 }
 
-/* Tools that constitute touching the task — blocked while the gate is armed. */
+/* A Read of a repo-path (or any) MEMORY file is part of priming (Step 3 resolves each
+ * repo's local path from a repo-path-<repo> memory). Allowed even in the primer stage;
+ * everything else under Read is repo research and stays blocked until the KB is primed. */
+function isMemoryReadPath(p) {
+  if (typeof p !== 'string' || !p) return false;
+  const norm = p.replace(/\\/g, '/');
+  return /\.claude\/projects\/.+\/memory\//i.test(norm);
+}
+
+/* The subagent that primes the team knowledge base. It — and only it — may run in the
+ * primer stage. */
+const PRIMER_SUBAGENT = 'context-primer';
+
+/* Tools that constitute touching the task — blocked while the gate is armed. Both the
+ * classic `Task` tool and this harness's `Agent` tool are included. */
 const BLOCKED_TOOLS = new Set([
   'Read', 'Grep', 'Glob', 'Edit', 'Write', 'MultiEdit',
   'NotebookEdit', 'Task', 'Agent', 'WebFetch', 'WebSearch',
 ]);
 
-function blockMessage() {
+function armedMessage() {
   return [
-    '🛑 KICKOFF GATE — priming is not complete.',
+    '🛑 KICKOFF GATE (stage 1 of 2) — priming has not started.',
     '',
-    '/kickoff was invoked this session. You MUST finish priming BEFORE touching the task',
-    'with any Read/Grep/Glob/Edit/Write/Task call — no matter how detailed the request after',
-    '/kickoff looks. That trailing text is the Step 2 task description, NOT permission to start.',
+    '/kickoff was invoked this session. Finish the read-only priming steps BEFORE any',
+    'Read/Grep/Glob/Edit/Write/Task — no matter how detailed the request after /kickoff',
+    'looks. That trailing text is the Step 2 task description, NOT permission to start.',
     '',
-    'Do this now, in order (these are allowed while the gate is armed):',
+    'Allowed now, in order:',
     '  • Step 0  version check (cat .claude/toga-ai.version ; npm view toga-ai version)',
     '  • Step 1  resolve the team repo (probe for knowledge/registry.json)',
     '  • Step 2  interview the developer (framework / layer / repo(s) / client / task)',
-    '  • Step 3  node "<TEAM_REPO>/knowledge.js" kickoff-preflight ...   ← this AUTO-CLEARS the gate',
-    '  • Step 4+ THEN read the knowledge docs and start the task',
+    '  • Step 3  node "<TEAM_REPO>/knowledge.js" kickoff-preflight ...',
     '',
-    'The gate releases automatically the instant kickoff-preflight runs.',
+    'Running kickoff-preflight ADVANCES the gate to stage 2 (team-KB priming). It no',
+    'longer releases the gate — priming the knowledge base does.',
     '(Emergency override only: set KICKOFF_GATE_DISABLED=1.)',
   ].join('\n');
 }
 
+function primerMessage() {
+  return [
+    '🛑 KICKOFF GATE (stage 2 of 2) — the TEAM KNOWLEDGE BASE has not been primed yet.',
+    '',
+    'kickoff-preflight resolved the load-set, but the team KB is the FIRST source you must',
+    'prime from — before ANY other research. Do NOT read repo code, grep/glob the source,',
+    'edit, or spawn any other agent yet — not even files named in the /kickoff sentence.',
+    '',
+    'Do this now (Step 4): spawn the context-primer subagent to read the resolved knowledge',
+    'docs and return the briefing —',
+    '    Agent tool · subagent_type: "context-primer" · run_in_background: false',
+    '    pass it: TEAM_REPO, the full kickoff-preflight JSON, and the task description.',
+    'Wait for its briefing. THEN read repo code and start the work.',
+    '',
+    'Allowed meanwhile: reading repo-path-<repo> memory files, AskUserQuestion (to ask for',
+    'a repo path), and knowledge.js priming commands.',
+    '(Emergency override only: set KICKOFF_GATE_DISABLED=1.)',
+  ].join('\n');
+}
+
+function foregroundMessage() {
+  return [
+    '🛑 KICKOFF GATE (stage 2 of 2) — spawn the context-primer in the FOREGROUND.',
+    '',
+    'Pass run_in_background: false so team-KB priming actually COMPLETES before you',
+    'continue. A backgrounded primer lets you race ahead and read repo code before the',
+    'knowledge-base briefing lands — the exact failure this gate exists to prevent.',
+  ].join('\n');
+}
+
 function main() {
   if (process.env.KICKOFF_GATE_DISABLED === '1') process.exit(0);
 
   const data = readPayload();
 
   // ---- UserPromptSubmit: arm the gate when /kickoff is invoked ----
-  // Identify by the presence of a prompt and absence of a tool call.
   const isPromptEvent =
     data.hook_event_name === 'UserPromptSubmit' ||
     (typeof data.prompt === 'string' && !data.tool_name);
 
   if (isPromptEvent) {
     if (invokesKickoff(data.prompt)) {
-      writeLock(data.session_id);
+      writeLock(data.session_id, 'armed');
       // stdout from UserPromptSubmit is injected into the model's context.
       console.log(
-        '<system-reminder>KICKOFF GATE ARMED. Before ANY other tool call, complete priming ' +
-        'Steps 0–6 of the kickoff skill — version check, resolve team repo, interview, then ' +
-        'run `knowledge.js kickoff-preflight` (which releases the gate), THEN read docs and work. ' +
-        'The trailing task description is Step 2 input, not permission to start. ' +
-        'A hook will block Read/Grep/Edit/Write/Task until preflight runs.</system-reminder>'
+        '<system-reminder>KICKOFF GATE ARMED (two stages). Stage 1: complete read-only ' +
+        'priming (version check, resolve team repo, interview) then run `knowledge.js ' +
+        'kickoff-preflight`. Stage 2: preflight does NOT release the gate — you must FIRST ' +
+        'prime the team knowledge base via the `context-primer` subagent (foreground, ' +
+        'run_in_background: false) BEFORE any repo Read/Grep/Glob/Edit/Write or other agent. ' +
+        'The trailing task description is Step 2 input, not permission to start.</system-reminder>'
       );
     }
     process.exit(0);
   }
 
+  // ---- PostToolUse: no-op. Release is spawn-time in PreToolUse, so the gate can never
+  //      hang waiting on a completion event. Present defensively so a PostToolUse wiring
+  //      never falls through to the PreToolUse enforcement below. ----
+  if (data.hook_event_name === 'PostToolUse') process.exit(0);
+
   // ---- PreToolUse: enforce while armed for THIS session ----
   const lock = readLock();
   if (!lock) process.exit(0);
@@ -158,22 +220,54 @@ function main() {
   if (data.session_id && lock.session && !sameSession) process.exit(0);
 
   const tool = data.tool_name || '';
-  const command = (data.tool_input && data.tool_input.command) || '';
+  const toolInput = data.tool_input || {};
+  const command = toolInput.command || '';
+  const phase = lock.phase || 'armed';
 
-  if (tool === 'Bash') {
-    if (isPreflightBash(command)) { clearLock(); process.exit(0); } // priming reached — release
-    if (isPrimingBash(command)) process.exit(0);                    // other read-only priming step
-    console.log(blockMessage());
-    process.exit(2);
+  // ================= STAGE 1: ARMED — only priming Steps 0–3 =================
+  if (phase === 'armed') {
+    if (tool === 'Bash') {
+      // preflight ADVANCES to stage 2 (does NOT release) — the team KB is still unprimed.
+      if (isPreflightBash(command)) { writeLock(lock.session, 'primer'); process.exit(0); }
+      if (isPrimingBash(command)) process.exit(0); // other read-only priming step
+      console.log(armedMessage());
+      process.exit(2);
+    }
+    if (BLOCKED_TOOLS.has(tool)) { console.log(armedMessage()); process.exit(2); }
+    process.exit(0); // AskUserQuestion, Skill, TodoWrite, … — part of the interview
   }
 
-  if (BLOCKED_TOOLS.has(tool)) {
-    console.log(blockMessage());
-    process.exit(2);
+  // ============ STAGE 2: PRIMER — team KB must be primed via subagent first ============
+  if (phase === 'primer') {
+    if (tool === 'Agent' || tool === 'Task') {
+      if (toolInput.subagent_type === PRIMER_SUBAGENT) {
+        // Must be foreground so the model waits for the briefing before doing anything else.
+        // (The classic `Task` tool runs synchronously; only the async `Agent` tool needs the
+        // explicit run_in_background: false.)
+        if (tool === 'Agent' && toolInput.run_in_background !== false) {
+          console.log(foregroundMessage());
+          process.exit(2);
+        }
+        clearLock(); // team-KB priming is underway in the foreground — release the gate
+        process.exit(0);
+      }
+      console.log(primerMessage()); // any other agent must wait until the KB is primed
+      process.exit(2);
+    }
+    if (tool === 'Read') {
+      if (isMemoryReadPath(toolInput.file_path || toolInput.path)) process.exit(0); // repo-path lookup
+      console.log(primerMessage());
+      process.exit(2);
+    }
+    if (tool === 'Bash') {
+      if (isPrimingBash(command)) process.exit(0);
+      console.log(primerMessage());
+      process.exit(2);
+    }
+    if (BLOCKED_TOOLS.has(tool)) { console.log(primerMessage()); process.exit(2); } // Grep/Glob/Edit/Write/…
+    process.exit(0); // AskUserQuestion (ask for a repo path), Skill, … — allowed
   }
 
-  // Anything else (AskUserQuestion, Skill, TodoWrite, ExitPlanMode, …) is part of
-  // priming/interview — allow.
   process.exit(0);
 }
 

package/skills/kickoff/SKILL.md

@@ -23,15 +23,24 @@ description: Start-of-session context loader for TOGA Technology projects. Run t
 > Only after Step 5's "primed and ready" summary (and Step 6's plan, for non-trivial work)
 > may you touch the task itself.
 >
-> **This gate is mechanically enforced — it is not just prose.** A hook
+> **This gate is mechanically enforced in TWO stages — it is not just prose.** A hook
 > (`hooks/toga/kickoff-gate.js`, wired on `UserPromptSubmit` + `PreToolUse`) arms the
 > instant `/kickoff` is invoked and will **hard-block** `Read`, `Grep`, `Glob`, `Edit`,
-> `Write`, `Task`, and any non-priming `Bash` until you actually prime. The only calls it
-> permits while armed are the read-only priming steps (the version check, team-repo probe,
-> `knowledge.js manifest`, the developer interview) and `knowledge.js kickoff-preflight` —
-> **running preflight (Step 3) is what releases the gate.** So the correct response to a
-> block message is never to fight it: run Steps 0–3, and the moment preflight executes you
-> are free to read docs and work. (Emergency override only: `KICKOFF_GATE_DISABLED=1`.)
+> `Write`, `Task`/`Agent`, and any non-priming `Bash` until you actually prime.
+>
+> - **Stage 1 (armed):** only the read-only priming steps (version check, team-repo probe,
+>   `knowledge.js manifest`, the developer interview) and `knowledge.js kickoff-preflight`
+>   are permitted. Running **preflight (Step 3) does NOT release the gate — it advances it to
+>   stage 2.**
+> - **Stage 2 (primer):** the load-set is resolved but the **team knowledge base is not yet
+>   primed.** Everything stays blocked until you spawn the **`context-primer` subagent in the
+>   foreground** (Step 4) — priming the team KB via that subagent is **what releases the gate.**
+>   Reading `repo-path-<repo>` memories and asking the developer stay allowed.
+>
+> So the correct response to a block message is never to fight it: run Steps 0–3, then
+> **prime the team KB via the foreground `context-primer` subagent (Step 4) BEFORE any other
+> research** — before you open a single repo file, even one named in the `/kickoff` sentence.
+> (Emergency override only: `KICKOFF_GATE_DISABLED=1`.)
 
 ## Session permission policy — auto-accept local file I/O, ALWAYS confirm dangerous execution
 
@@ -257,20 +266,30 @@ source — this is the one thing preflight can't know):
 
 Never ask for a repo not in `loadSet`.
 
-## Step 4 — Load the knowledge via the `context-primer` subagent (do NOT read docs inline)
-
-**This is the token-discipline core of kickoff.** Reading every architecture + feature +
-standard + client doc *into this conversation* is exactly what bloats the thread and trips
-compaction later. So you do **not** read those docs here. Instead, **delegate the heavy
-reading to the `context-primer` subagent**, which reads them in *its own* context and
-returns a small distilled briefing. Preflight (Step 3) has already released the kickoff
-gate, so spawning a subagent is now permitted.
-
-Spawn it with the `Agent` tool (`subagent_type: context-primer`) and pass:
-- `TEAM_REPO` (the resolved path),
-- the **full `kickoff-preflight` JSON** from Step 3 (it contains `reads[]`, `clientScope`,
-  `standards`, `client`, `estimate`),
-- the developer's one-line task description.
+## Step 4 — Prime the team knowledge base FIRST, via the `context-primer` subagent
+
+> 🛑 **THIS IS THE FIRST RESEARCH YOU DO — NOT OPTIONAL, NOT PARALLELIZABLE.**
+> After the interview, the team knowledge base is the **first source you prime from, before
+> ANY other research.** You may **not** read repo code, `Grep`/`Glob` the source, spawn any
+> other agent, or open a file **named in the `/kickoff` sentence** until the `context-primer`
+> subagent has **returned its briefing.** Preflight (Step 3) did **not** release the gate — it
+> advanced it to stage 2, and **spawning the foreground `context-primer` is what releases it.**
+> The team KB is the team's distilled, shared gold: skipping it, or side-channeling it (running
+> the primer in the background while you read code in parallel), is the exact failure this gate
+> exists to prevent — do neither.
+
+**This is also the token-discipline core of kickoff.** Reading every architecture + feature +
+standard + client doc *into this conversation* bloats the thread and trips compaction later. So
+you do **not** read those docs here — you **delegate the heavy reading to the `context-primer`
+subagent**, which reads them in *its own* context and returns a small distilled briefing.
+
+Spawn it with the `Agent` tool and **wait for it**:
+- `subagent_type: context-primer`,
+- **`run_in_background: false`** — foreground, so you MUST wait for the briefing before doing
+  anything else; a backgrounded primer running while you read code is precisely the violation,
+- pass it: `TEAM_REPO` (the resolved path), the **full `kickoff-preflight` JSON** from Step 3
+  (`reads[]`, `clientScope`, `standards`, `client`, `estimate`), and the developer's one-line
+  task description.
 
 The primer returns a `## Primer` block (critical rules, task-relevant knowledge + gotchas,
 client variations, gaps) plus a `## Doc map`. **Keep only that briefing as your context for