toga-ai 1.0.826 → 1.0.828

package/.claude/settings.json

@@ -71,6 +71,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/sql-file-location.js\"",
+            "timeout": 3000
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write|MultiEdit",
         "hooks": [

package/agents/backend-lead.md

@@ -22,7 +22,27 @@ You are the maker; you never sign off your own work.
 - **Never** join two DB families (`Core` + `Client_<Tenant>`) in one query — assemble in
   PHP across two connections.
 - **api2** — every response uses the envelope `{success, data, errors}`.
-- **Queues** — background work dispatched via `_Queue`, never instantiated directly.
+- **Queues** — a worker is an `abstract class _Worker_<Name>` with `public static` entry
+  methods (no `extends _Worker`, no `run()`). Dispatch **only** via
+  `_Worker::runTask('Category/Sub/File/Method', $params)` — never call the entry method
+  directly; there is **no** `_Queue` class. Params are spread as named args, so a param name
+  is the job contract — renaming one breaks in-flight jobs; give defaults.
+- **Schema** — no standalone `.sql` file ever goes in an app repo. All schema/seed changes go in
+  `dbchanges2` (2.0) or `dbchanges` (1.0); app repos hold only SQL strings inside PHP.
+- **Shared core** — solve it in the app before touching `library` / `_underscore`. Before changing
+  a shared core method signature, **grep every repo for callers** (worker crons call via the
+  autoloader, no `require`).
+- **Exceptions route (2.0)** — `_Exception_Validation` = 400, `_Exception_Business` = 500 + Issue,
+  plain `Exception` = 500 + Issue. **Never `throw new _Exception(...)`** (5-arg constructor →
+  `ArgumentCountError`).
+- **Import/sync/cron loops fail loud** — never catch-and-continue / log-and-skip a record; a mid-loop
+  failure throws and aborts, leaving the checkpoint unmoved.
+- **`LIMIT 1` / `fetchRow()` on a non-unique key** needs a deterministic `ORDER BY … , id`.
+- **Overrides** — a `_Model_<Client>_*` override must not add a param type the parent lacks (fatal at
+  class load; `php -l` misses it). Commit a write with `_Database::transactionCommit()` — a lazy
+  transaction that never commits is silently rolled back.
+- **1.0 runtime is PHP 7.2** — no typed properties (use `@var`), positional args (not named), and any
+  PHP warning `exit()`s the request (guard with `isset()`/`getVarIfSet()`, not `try/catch`).
 - **Coding style** — typed params + return types; guard clauses; no bare `catch`; no `@`
   suppression; named constants over magic numbers; functions with 4+ params take an array.
 

package/agents/cso.md

@@ -1,6 +1,6 @@
 ---
 name: cso
-description: TOGA Chief Security Officer — audits changes and gives an independent security verdict on proposed approaches before code ships. Wraps ecc:security-reviewer with TOGA-specific concerns (credential handling, multi-tenant client data isolation, SQL injection through the App_Db/_Db layer, queue/worker input validation, auth, OWASP) and the repo's secret-scan rule.
+description: TOGA Chief Security Officer — audits changes and gives an independent security verdict on proposed approaches before code ships. Wraps ecc:security-reviewer with TOGA-specific concerns (credential handling, multi-tenant client data isolation, SQL injection via the escaping layer `_Database::escape` / `App_Database::sqlEscape`, queue/worker input validation, auth, OWASP) and the repo's secret-scan rule.
 model: opus
 tools: Read, Grep, Glob, Bash, Agent
 ---
@@ -33,14 +33,29 @@ report; own the synthesis.
 1. **Credentials** — no secret is ever written as a value anywhere (code, config, knowledge
    doc, this report). Credentials are documented by *location* only. Run
    `node knowledge.js validate` if knowledge files are touched; its secret-scan must pass.
+   **Config absence must throw, never fall back to a baked-in value** — a hardcoded-credential
+   "production fallback" is a committed secret (the live FedEx key incident). A committed
+   secret (a value in git, a `.npmrc` registry token) is compromised → rotate it.
 2. **Multi-tenant isolation** — no cross-tenant data access; every query is scoped to the
    correct `Client_<Name>` database; a tenant identifier coming from untrusted input is
-   validated/authorized before it selects a database or filters rows.
-3. **SQL injection** — all queries parameterized through `App_Db` / `_Db`; no string-built
-   SQL, no untrusted input concatenated into a statement.
-4. **Worker / queue payloads** — `_Queue` payloads are validated on the worker side; nothing
-   trusts unvalidated input; payloads carry IDs (re-fetched server-side), not full rows that
-   could be tampered with in transit.
+   validated/authorized before it selects a database or filters rows. **Never join two DB
+   families in one query** (`Core` + `Client_<Tenant>`) — separate prod clusters; this is the
+   physical form of tenant isolation. On the front end, **field-limit every request** so an
+   FK-expansion can't pull a bcrypt hash / LDAP DN into the client.
+2b. **Web-root exposure (1.0)** — a front controller guarded only by `RewriteCond !-f` is **not**
+   access control; config/secret files under the web root are served verbatim on a direct GET.
+   Require explicit `FilesMatch` deny blocks and secrets kept outside the root.
+3. **SQL injection** — there are **no prepared statements** in either framework; escaping/casting
+   **is** the control. Every interpolated value is cast (`(int)`) or escaped (`_Database::escape()`
+   in 2.0, `App_Database::sqlEscape()` in 1.0), or the query is built by the model layer
+   (`_Model` / `App_Model`). Flag: any raw untrusted value concatenated unescaped; any reference to a
+   non-existent `_Db` / `App_Db` class; `_Database::protect()` / `sqlProtect()` used as if it were
+   escaping (it **strips** characters — lossy filtering, data corruption); and any **identifier**
+   (table/column/`ORDER BY`/`LIMIT`) taken from input rather than a hardcoded allowlist (escaping does
+   not protect identifiers).
+4. **Worker / queue payloads** — worker jobs (dispatched via `_Worker::runTask`) validate input on the
+   worker side; nothing trusts unvalidated input; payloads carry IDs (re-fetched server-side), not full
+   rows that could be tampered with in transit.
 5. **Auth / authorization** — every new endpoint checks authentication *and* that the caller
    is permitted to act on that tenant's resource.
 
@@ -70,7 +85,7 @@ Findings
 
 (if none in a band, omit it; if no findings at all, say "No findings.")
 
-TOGA overlay: credentials ✓/✗ · tenant isolation ✓/✗ · App_Db/_Db params ✓/✗ ·
+TOGA overlay: credentials ✓/✗ · tenant isolation ✓/✗ · SQL escaping (no `_Db`/prepared) ✓/✗ ·
 queue validation ✓/✗ · auth ✓/✗
 
 Verdict: SAFE TO SHIP | FIX REQUIRED | BLOCK — <one line>

package/agents/cto.md

@@ -49,13 +49,21 @@ Confirm the leading choice respects TOGA's hard constraints. Flag any violation
 blocker, not a footnote:
 
 - **Naming** — new classes carry the right framework prefix (`App_` or `_`).
-- **DB layer** — all access through `App_Db` / `_Db`; no raw PDO in business logic.
-- **Queue/workers** — background work dispatched via `_Queue`, never instantiated directly.
+- **DB layer** — access through `_Model` / `_Database` / `_Query` (2.0) or `App_Model` /
+  `App_Database` (1.0). There is **no** `_Db` / `App_Db` class and **no** prepared statements;
+  injection control is `_Database::escape()` / `(int)` cast (2.0) or `App_Database::sqlEscape()` (1.0).
+- **Queue/workers** — a worker is an `abstract class _Worker_<Name>` with `public static` entry
+  methods; dispatch **only** via `_Worker::runTask('Category/Sub/File/Method', $params)`. There is
+  **no** `_Queue` class, and entry methods are never called directly.
 - **API envelope** — responses conform to `{success, data, errors}`.
 - **Multi-tenant isolation** — work is scoped to the correct `Client_<Name>` database; no
-  design that lets one tenant's request touch another's data.
+  design that lets one tenant's request touch another's data. **Never join two DB families
+  (`Core` + `Client_<Tenant>`) in one query** — they are on separate prod clusters; assemble in PHP.
 - **Shared core** — does it change `library` / `_underscore`? If so, what depends on it and
   what breaks? Prefer app-level solutions over core edits unless core is the right home.
+- **Standard vs custom** — if the design adds a custom field, flag that the standard-vs-custom
+  discussion must happen first. Schema/contract/core/migration choices are hard to reverse — that is
+  exactly what this gate exists to catch before code.
 
 ## Step 3 — Verdict
 

package/agents/database-architect.md

@@ -20,13 +20,44 @@ write the change.
 - **dbchanges2 (2.0 schema):**
   - Daily files use **today's** date, suffix `YYYY-MM-DD<letter>` — never future-date
     (future dates are reserved launch-later files).
-  - `ALTER ADD COLUMN` appends at the end — always use `AFTER` to honor field order.
-  - UUIDs must be fresh **random v4** — never patterned, incremented, or `UUID()`.
-    `RecordFields` need `isIdentifier`.
+  - **One file per realm per turn** — consolidate same-database changes into one dated file;
+    different realms (folders) always split. A `.sql` file references only the ONE database its
+    folder targets, unqualified (the cluster-isolation hook hard-blocks a cross-database ref).
+  - **Column order:** `id`, `uuid`, then `dtCreated` immediately after `uuid`, then `dtUpdated`
+    immediately after `dtCreated`, then business columns. `ALTER ADD COLUMN` appends at the end —
+    always use `AFTER` to honor this order.
+  - UUIDs must be fresh **random v4** — never patterned, incremented, or `UUID()` (even in bulk;
+    bulk uses the inline `RANDOM_BYTES()` v4 expression). `RecordFields` need `isIdentifier`.
+  - **`Core.Records` / `Core.RecordFields` are the ONLY tables with team-maintained `id`s — ASK
+    the developer for the next value; never let `AUTO_INCREMENT` assign it.** The next free id
+    **differs per environment**, so a change that creates a new Core row and references it from
+    client rows may need a per-environment literal — say so in a header comment. Reference these
+    ids as hardcoded literals (including foreign keys), with a comment naming the field.
+  - **A fan-out `Client/` file must never reference a `customRecordFieldId` or a client-specific
+    label** — `CustomRecordFields` ids are per-client `AUTO_INCREMENT`, so the same number names a
+    different field in every tenant. Put anything touching a custom field in that client's own
+    `Client_<Name>/` file.
   - ENUM / `FIELD_LIST` values are `CAPITAL_SNAKE_CASE`; slugs stay lowercase-hyphen.
+  - **Guard every registration/seed insert with `NOT EXISTS` (or `INSERT IGNORE`)** so a re-run or
+    a parallel migration can't double-register (a double interceptor fires twice). Exception: for the
+    Surface reserved-id blocks use a **plain `INSERT`, never `INSERT IGNORE`** — a PK collision there
+    must halt, not silently mis-wire.
   - Seed baseline lookups into every `Client_*` DB with a re-runnable, guarded UNION-ALL
     anti-join INSERT (natural-key guard, INNER JOIN the FK).
+  - **Staging temp table must pin `COLLATE`** to the column it joins against (connection default is
+    often `utf8mb4_general_ci`, tenant tables `utf8mb4_unicode_ci` → error 1267). Stage **large**
+    loads via a temp table with a flat multi-row `VALUES`, not a long `UNION ALL` chain (parser
+    thread-stack overrun). A self-referencing `DELETE`/`INSERT…SELECT` guard must wrap its subquery
+    in a derived table (error 1093 / guard flips mid-statement).
+  - The blank `Client` DB must carry the **baseline data seed** (roles, full ACL, lookups, UI
+    config), not schema-only — a schema-only blank cannot authorize.
+  - New 2.0 tables: `InnoDB`, `utf8mb4` / `utf8mb4_0900_ai_ci`, and **table + field comments are
+    required** (`id`/`uuid`/FK have mandated comment formats; don't begin with "The").
   - Standardize machine keys on `slug` (deprecating `code`).
+- **A committed migration records INTENT, not deployed state.** There is no automated executor and
+  operators hand-transpose Core ids at run time without always writing them back. Never infer what an
+  environment contains by reading `dbchanges2` — establish current state with read-only `SELECT`s
+  against the target's read replicas before authoring anything whose correctness depends on it.
 - **Custom vs standard field** — before adding any custom field, force the
   standard-vs-custom discussion with the developer first.
 

package/agents/framework-pattern-checker.md

@@ -40,12 +40,13 @@ Read the framework standards file. Pull out: required naming, required parent cl
 
 **Framework 2.0 (_underscore) checklist:**
 - Worker class starts with `_Worker_` — CRITICAL if not
-- Worker extends `_Worker` — CRITICAL if not
-- Worker has `public function run(): void` — CRITICAL if missing
-- No direct `$worker->run()` call in other files — CRITICAL (use `_Queue::dispatch()`)
+- Worker is `abstract class` with `public static` entry methods — CRITICAL if it `extends _Worker` or defines a `run()` method (that shape never dispatches)
+- Worker entry method **parameter names are the public contract** — they are spread as named args at dispatch; renaming one breaks every in-flight job. Give a default where a sensible one exists — WARNING if a new required param has no default
+- No direct call of a worker entry method from other files — CRITICAL (dispatch via `_Worker::runTask('Category/Sub/File/Method', $params)`; there is **no** `_Queue::dispatch()`)
 - Controller starts with `_Controller_` — CRITICAL if not
 - api2 actions return `{success, data, errors}` envelope — CRITICAL if not
-- DB access via `_Db::` only — WARNING if raw PDO in controllers/workers
+- DB access via `_Model` / `_Database` / `_Query` — WARNING if it names a non-existent `_Db` class or reaches for PDO/prepared statements (neither exists)
+- A `_Model_<Client>_*` override must **not** add a parameter type the parent lacks — CRITICAL (param types are contravariant, fatal at class load; `php -l` does **not** catch it)
 
 ## Step 4 — Check knowledge base for repo-specific rules
 
@@ -66,8 +67,9 @@ Framework: <1.0 (App_) | 2.0 (_underscore)>
 
 CRITICAL (will cause runtime failures):
 - Line 1: Class `OrderProcessor` must start with `_Worker_` → rename to `_Worker_OrderProcessor`
-- Line 8: Missing `run()` method — _Worker subclasses must implement run(): void
+- Line 3: Worker declared `class ... extends _Worker` with a `run()` method — must be an `abstract class` with `public static` entry methods, or it never dispatches
+- Line 20: Worker entry method called directly → dispatch via `_Worker::runTask('Orders/Process', $params)`
 
 WARNING:
-- Line 45: Raw `new _Db()` — use `_Db::select()` static method
+- Line 45: References a non-existent `_Db` class — use `_Model` / `_Database` / `_Query`
 ```

package/agents/frontend-lead.md

@@ -27,6 +27,30 @@ reviewer checks your work, not you.
   TableView flags set — never listing-only.
 - **Desk is local-dev only.** Never plan or mention deploying it to qa-alpha or any env.
 
+## Platform rules (2.0 React — from `2.0/standards/frontend.md`)
+
+- **Three state homes, no overlap:** React Query = all server/async state; Zustand = a minimal
+  identity/session slice (user, tenant, theme); `localStorage` = losable pure-UI prefs only. Server
+  data never lives in Zustand.
+- **Reset on tenant/auth change.** On login/logout/tenant switch, clear the React Query cache **and**
+  tenant-scoped `localStorage` — one tenant's data must never bleed into another's session.
+- **URL is the source of truth for table view state** (page, sort, filters, columns). Any param that
+  changes which rows the server returns must **reset the page to 1 in the same `setSearchParams`
+  updater** (one shared helper, row-click excluded) — miss it and "search returns nothing".
+- **Consume blox correctly:** pin an **exact** published version (never a caret); **dedupe** `react`,
+  `react-dom`, and every peer blox provides hooks/context for (`react-hook-form`, `@tanstack/*`);
+  define the full host `--*` token set (blox ships zero token values); import `./api/api` (create → set
+  axios instance) **before** the router mounts; provider nesting is QueryClient → Auth → Toaster → theme
+  → router.
+- **Field-limit every request** and send an explicit **`recordsPerPage`** — an unpaginated V2 list GET
+  silently truncates at 25 with no error and no guaranteed order.
+- **Type-check with `tsc -p tsconfig.app.json` (or `tsc -b`), never bare `tsc --noEmit`** — the root
+  config is references-only and always exits 0 (a false green).
+- **Tests:** the tenant×role×feature matrix goes in Cypress **component** tests, not e2e; **stub the
+  Surface bundles** (never hit a real backend — it can write real data); every new test is **seen to
+  fail** before it passes. Green FE tests do **not** enable a feature — that is a role-scoped
+  `SurfaceOverrides IS_VISIBLE` row in `dbchanges2`.
+
 ## Steps
 
 1. **Read** the design source and the components you'll reuse. Search the KB for the area.

package/agents/knowledge-writer.md

@@ -30,7 +30,7 @@ Always read `.claude/knowledge/CONVENTIONS.md`. It is the contract — frontmatt
 Check `.claude/knowledge/registry.json` for canonical `project` and `framework`. Required fields:
 ```yaml
 title: <human-readable title>
-framework: "<1.0 | 2.0>"
+framework: "<1.0 | 2.0 | standalone>"
 repo: <repo-name from registry>
 project: <project-name from registry>
 client: <client-slug | "shared">
@@ -55,6 +55,11 @@ Search first: `node .claude/knowledge.js search --repo=<repo> --q=<keywords>`
 
 Structure: YAML frontmatter → one-paragraph overview → main content → code examples (correct framework prefix).
 
+**On an UPDATE, append to `## Change history`, don't silently overwrite.** Every standard/architecture
+doc ends with a dated, attributed change-history list. Add a new line —
+`- YYYY-MM-DD — <what changed and why>. (<git-username>)` — and bump `updated:` in the frontmatter.
+Prefer a small UPDATE to an existing doc over a new near-duplicate.
+
 ## Step 6 — Validate and re-index
 
 Always run after writing:

package/agents/php-reviewer.md

@@ -46,10 +46,23 @@ After ECC's findings, run these TOGA-specific checks:
 - Public methods in `camelCase`
 
 **Framework 2.0 (_underscore):**
-- Workers extend `_Worker` and implement `run()`
-- Workers dispatched via `_Queue::dispatch()`, never instantiated directly
+- Workers are `abstract class _Worker_<Name>` with `public static` entry methods — they do **not** extend `_Worker` and have **no** `run()` method
+- Workers dispatched **only** via `_Worker::runTask('Category/Sub/File/Method', $params)` — never call an entry method directly, and there is **no** `_Queue::dispatch()` (`_Queue` does not exist)
 - `api2` actions return `{success: bool, data: mixed, errors: array}` envelope
-- DB access via `_Db::` methods only in business logic
+- DB access via `_Model` / `_Database` / `_Query` — there is **no** `_Db` class. SQL-injection control is the model layer, else `_Database::escape()` / `(int)` cast; **no prepared statements exist** in either framework (verified 2026-07-30)
+
+**Both frameworks — high-signal checks:**
+- **`LIMIT 1` / `fetchRow()` on a non-unique key needs a deterministic `ORDER BY … , id`** — an unordered single-row read returns an arbitrary row (a real 6-day approval bug).
+- **Import/sync/cron loops must fail loud** — no catch-and-continue / log-and-skip a record; a mid-loop failure throws and aborts so the checkpoint/cursor stays put. (Per-entity request/response code is the *only* place a catch-and-return is correct.)
+- **A `_Model_<Client>_*` override must not add a parameter type the parent lacks** — param types are contravariant, fatal at class load, and `php -l` does **not** catch it.
+
+**Framework 2.0 — exceptions route, they aren't style:**
+- `_Exception_Validation` = 400 (bad client input, no Issue) · `_Exception_Business` = 500 + `Logs.Issue` (business user can act) · plain `Exception` = 500 + Issue (code defect). **Never `throw new _Exception(...)`** — its constructor needs 5 args and raises `ArgumentCountError` before your exception exists. Never "upgrade" a client-input rejection to `_Exception_Business` just to log it.
+
+**Framework 1.0 (App_) — runtime is PHP 7.2, and warnings kill the request:**
+- **No typed properties** (`private ?string $x` is a fatal); use an untyped property + `@var` docblock. Param/return types are fine.
+- **Positional args only** — do **not** use PHP 8 named arguments (that is the 2.0 convention).
+- **Any PHP warning `exit()`s the request** (`App_Error::handleError` → `exit`) — a `try/catch` can't contain it; guard optional data with `isset()`/`getVarIfSet()` first. `App_Page::getVar()` **throws** on a missing field; use `getVarIfSet()` for optional fields.
 
 ## Step 5 — Merge and output
 
@@ -62,8 +75,8 @@ ECC analysis: deep PSR-12, security, type system | TOGA overlay: framework patte
 
 | File:Line | Severity | Category | Issue | Fix |
 |-----------|----------|----------|-------|-----|
-| Foo.php:67 | CRITICAL | TOGA-PATTERN | Worker instantiated with `new _Worker_Notify` | Use `_Queue::dispatch('_Worker_Notify', $payload)` |
-| Foo.php:34 | CRITICAL | SQL-INJECTION | $_POST['id'] concatenated into query | PDO prepared statement |
+| Foo.php:67 | CRITICAL | TOGA-PATTERN | Worker entry method called directly | Dispatch via `_Worker::runTask('Platform/Cache/Clean', ['graceSeconds' => 120])` |
+| Foo.php:34 | CRITICAL | SQL-INJECTION | `$_POST['id']` concatenated into query | Cast `(int) $_POST['id']`, or `_Database::escape()` for a string, or use the `_Model` layer (no prepared statements) |
 | Foo.php:89 | WARNING | PSR-12 | Missing return type on public method | Add `: array` return type |
 
 **Summary:** 2 critical (1 TOGA-pattern, 1 security), 1 warning

package/agents/planner.md

@@ -41,8 +41,10 @@ Known patterns for this feature type:
 [paste any matching feature doc content]
 
 TOGA-SPECIFIC CONSTRAINTS:
-- Workers dispatched via _Queue::dispatch(), never instantiated directly
-- DB access via _Db:: / App_Db:: only (no raw PDO in business logic)
+- A worker is an abstract class _Worker_<Name> with public static entry methods (no extends _Worker, no run()); dispatch only via _Worker::runTask('Category/Sub/File/Method', $params). There is no _Queue class.
+- DB access via _Model / _Database / _Query (2.0) or App_Model / App_Database (1.0). There is no _Db / App_Db class and no prepared statements — injection control is _Database::escape() / (int) cast, or App_Database::sqlEscape().
+- Never join two DB families (Core + Client_<Tenant>) in one query — assemble in PHP across two connections. Schema changes go in dbchanges2 (2.0) / dbchanges (1.0), never in an app repo.
+- Solve it in the app before touching shared core (library / _underscore); grep all repos for callers before changing a shared core signature.
 - API responses must follow {success, data, errors} envelope (api2)
 - New classes must follow framework naming prefix (App_ or _)
 - No local repo paths in any committed file
@@ -74,12 +76,12 @@ Repo: <repo> | Framework: <fw> | Architecture loaded: ✓ | ECC planning: ✓
 Goal: [what is testable after this phase]
 
 **Create:**
-- `src/Workers/BatchOrderWorker.php` — extends _Worker, implements run()
-  Follow pattern from: _underscore/src/Workers/FulfillmentWorker.php
+- `Worker/Order/Batch.php` — `abstract class _Worker_Order_Batch` with a `public static` entry method (no `extends _Worker`, no `run()`)
+  Follow pattern from an existing worker2 `Worker/*/*.php` class
 
 **Modify:**
 - `src/Controllers/OrderController.php` — add dispatchBatch() after createOrder() (~line 87)
-  Use: `_Queue::dispatch('_Worker_BatchOrder', ['order_ids' => $ids])`
+  Use: `_Worker::runTask('Order/Batch/Process', ['orderIds' => $ids])`
 
 **Verify:** [concrete test steps]
 

package/agents/qa-engineer.md

@@ -25,6 +25,16 @@ worked. You did not write the code — that separation is the point.
   a test pass. A failing test is information.
 - **Critical path** (auth, payments, sync, anything hard to undo) — prove it with a real
   run and real evidence, not just `php -l`.
+- **Non-prod lies to you — a green pre-prod run is often no evidence.** Know these traps:
+  - **Cross-DB-family SQL and `dbchanges2` migrations** run fine locally/on beta (every non-prod is
+    all-in-one) and fail only in production (families are on separate clusters). Also `COLLATE` /
+    `sql_mode` / `thread_stack` vary per machine — a local pass isn't proof of portability.
+  - **Queued email** sends **inline** outside production (`test_mode` on in every non-prod), so a
+    queue-path bug passes on alpha/beta while prod stays broken. Verify queue changes in prod or a
+    serialize→drain harness.
+  - **Green front-end tests do NOT mean a client has the feature** — the fixture only simulates the
+    grant; real enablement is a role-scoped `SurfaceOverrides IS_VISIBLE` row in `dbchanges2`. Never
+    close an enablement ticket on a passing FE suite.
 
 ## Steps
 

package/agents/sql-reviewer.md

@@ -105,6 +105,16 @@ Maker ≠ checker: do not let the agent that wrote the SQL review it.
 - Long-running/background DB work inline in a request instead of dispatched via `_Worker::runTask()` → **WARNING**.
 - Reliance on stale cached reads immediately after a write without `_Database::useQueryCache(false)` → **WARNING**.
 
+### 3g. Cross-cluster, determinism & platform ids (2.0 + shared)
+- **Never join or sub-select across two DB families in one query** (`Core` + `Client_<Tenant>`, `Client_` + `Archive_`, `Client_` + `Logs_`, etc.) → **CRITICAL**. In production these families are on **separate clusters**, so the query cannot resolve there — it works locally only. Assemble across families in PHP over two `_Database` connections, referencing the other side by id/uuid/slug. (A local/beta pass is **no** evidence it is cluster-safe.)
+- **`LIMIT 1` / `fetchRow()` on a non-unique key needs a deterministic `ORDER BY` ending in a unique column** (`ORDER BY isActive DESC, id DESC`) → **WARNING**. An unordered `LIMIT 1` returns an arbitrary row; the same bug hides in `fetchRow()` with no `LIMIT 1` to grep for. **Order, don't filter**, when "no row" is worse than "a stale row".
+- **Escaping protects values, not identifiers.** A table/column name, sort direction, or `LIMIT` taken from input must come from a **hardcoded allowlist** — `ORDER BY " . _Database::escape($_GET['sort'])` is still injectable → **CRITICAL**.
+- **`Core.Records` / `Core.RecordFields` are the only tables with team-maintained `id`s.** A `recordId`/`recordFieldId` referenced from SQL should be a **hardcoded literal with a comment naming the field** — flag a cross-family `JOIN` to `Core` used only to resolve one of these ids.
+- **2.0 leading column order:** `id`, `uuid`, then `dtCreated` immediately after `uuid`, then `dtUpdated` immediately after `dtCreated`, then business columns → **WARNING** if out of order. On `ALTER TABLE ADD COLUMN` timestamps, require `AFTER` (a bare `ADD COLUMN` appends to the end).
+- **`Logs` cluster tables are SINGULAR** (`Issue`, `Event`, not `Issues`) — the one exception to the plural-table rule. Every other database is plural.
+- **Validate `FIELD_LIST` (ENUM) values in PHP before the query** — `FIELD_LIST` does no validation and turns a falsy/unknown value into SQL `NULL` silently → **WARNING**.
+- **1.0 only:** if a change removes `sqlProtect()` from a `LIKE` comparison, `LIKE` must become `=` in the same edit (the strip was the only thing stopping a `%` in user data acting as a wildcard) → **WARNING**.
+
 ## Output format
 
 ```

package/agents/system-architect.md

@@ -32,6 +32,9 @@ Decide and state explicitly:
   `{success, data, errors}` on the way out.
 - **Reuse** — which existing components/data layers to reuse before making new ones
   (blox components, TableView columns, Surface/settings, existing models).
+- **Data-drive the UI** — labels, colors, icons, options come from Surface/settings and
+  `labelRecordFieldId`, not hardcoded. If the design needs a **custom field**, flag that the
+  standard-vs-custom discussion must happen with the developer before it is added.
 - **Multi-tenant** — which `Client_<Tenant>` scope; confirm no cross-cluster query
   (never join two DB families in one statement — assemble in PHP across two connections).
 

package/knowledge/clients/nychh/features/netsuite-transfer-order-import.md

@@ -6,7 +6,7 @@ project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-14
+updated: 2026-09-16
 owners: [jcardinal, bala, rgirish]
 files:
   - library/app/api/toga2.php
@@ -15,11 +15,11 @@ files:
   - worker/crons/toga2/netsuite/sync_togasupply_hh.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/diagnose_hh_stuck_transfer_order.php
+  - worker/crons/toga2/netsuite/probe_import_single_order_hh.php
+  - worker/crons/toga2/netsuite/relink_transfer_order_pos_hh.php
   - dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql
   - dbchanges2/Client/2026-08-28a - TransferOrderItemsTimestampColumns.sql
-  - dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestampColumnsReposition.sql
-  - dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql
-  - dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql
+  - dbchanges2/Client_Nychh/2026-09-16a - TransferOrderBridgeAcl.sql
 related:
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../1.0/apps/library/features/toga2-api-client-and-bridge.md
@@ -92,6 +92,80 @@ sales-order linker. See the shared
 [SO↔PO bridge direction](../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md)
 doc for the bridge naming convention.
 
+### ⚠ The bridge links were never being created — three stacked causes, fixed + prod-verified 2026-09-16
+
+The PO↔TO bridge links (header **and** line) were silently never forming for NYCHH. Three
+independent faults, peeled in order; the last was the real blocker:
+
+1. **Linking only ever ran from the `PURCHASE_ORDERS` section, which never runs for NYCHH.** The
+   links depended on the PO section, so a transfer-order import created none. **Fix:** a new **public**
+   `App_Api_Toga2::linkTransferOrderPurchaseOrders()` now runs on **every** transfer-order
+   import/retry from inside `syncTransferOrderFromNetsuite()`. It is **idempotent** — re-running an
+   import repairs any missing link. In `TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG` mode it finds
+   the customer PO by the NetSuite **PO #** (`otherRefNum`, split on `' + '`) under the
+   `clientConfiguration['importCustomerPurchaseOrdersOnVendor']` vendor (the synthetic **Agilant**
+   vendor), then calls `linkPurchaseOrderToTransferOrder` for the header
+   (`PurchaseOrders_TransferOrders`) and line (`PurchaseOrderItems_TransferOrderItems`) links.
+2. **`linkPurchaseOrderToTransferOrder` read the TO line items from the wrong place, so line links
+   never formed.** It read `$transferOrder->transferOrderItems`, but **api2 NEVER inlines that
+   collection at any depth** (`transfer-orders` has no `InherentRecordChildren` row — same root cause
+   as the idempotency bug), so it was always empty. **Fix:** read TO items via
+   `getTransferOrderItemsByUuid` (the reliable direct `GET /transfer-order-items` query). Also lowered
+   the TO existence GET to `depth=1` and added `recordsPerPage=1000` to the PO-items GET.
+3. **ROOT CAUSE — an ACL gap, not code.** The NYCHH **API** role had **no write ACL** on the two
+   bridge records **325** (`PurchaseOrders_TransferOrders`) and **329**
+   (`PurchaseOrderItems_TransferOrderItems`), so the link POST failed api2 **EZ-3 / WZ-2** ("no
+   fields in which you are authorized to write"). The working **sales-order** bridge (record **276**,
+   `PurchaseOrders_SalesOrders`) already had the grant, which is why SO links worked and TO links did
+   not. **Also key: on CREATE, api2 `isPermitted()` DENIES a record permission that has no
+   `AclLogicGroups` chain — a bare `AclRecordPermissions` row is inert** (the standard four-table
+   chain rule — see [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)).
+
+**Fix migration:** `dbchanges2/Client_Nychh/2026-09-16a - TransferOrderBridgeAcl.sql` seeds the full
+four-table chain (`AclRecordExpressions` `'all'` → `AclRecordPermissions` full CRUD → `AclLogicGroups`
+AND → `AclLogicGroupExpressions`) **plus** `AclFieldPermissions isWritable = 1`, for roles **Base**
+and **API**, on records **325** and **329**, mirroring the working record 276. Guarded/re-runnable,
+roles resolved by name, fresh random v4 uuids, `Core` ids hardcoded (no `Client_*`→`Core` JOIN — the
+cross-cluster rule). The only writable fields a bridge POST touches are the row `uuid` + the two FK
+columns. **Data facts:** Core bridge record ids **276**=`PurchaseOrders_SalesOrders`,
+**325**=`PurchaseOrders_TransferOrders`, **329**=`PurchaseOrderItems_TransferOrderItems`; Core
+`RecordFields` **2210**=uuid/**2211**=purchaseOrderId/**2212**=transferOrderId (rec 325),
+**2226**=uuid/**2227**=purchaseOrderItemId/**2228**=transferOrderItemId (rec 329); `Client_Nychh`
+roles **1**=Base, **2**=Developer, **3**=API, **4**=Public. Reviews: `cto` AGREE (four-table chain),
+`sql-reviewer` SAFE TO MERGE.
+
+**ACL failures are now LOUD in the linker.** Both bridge existence checks **THROW** when their GET
+returns no `meta->totalRecordCount` (an ACL **read** gap) instead of silently skipping the create;
+the create POST already throws on a write-fail (EZ-3/WZ-2). So any future ACL gap stops the run
+rather than quietly producing zero links.
+
+**Verified in prod:** link `PurchaseOrderItems.id = 589` ↔ `TransferOrderItems.id = 7155` created for
+PO **EIT0012548** ↔ TO **284624** (NetSuite SO **7326440**).
+
+### PO discovery for a NYCHH transfer order — `otherRefNum` + Agilant vendor, NEVER `createdPo`
+
+For NYCHH the SO **line-level `createdPo` is NULL**; the PurchaseOrder is the **customer PO**
+(`otherRefNum`, the NetSuite "PO #" field) imported against the synthetic **Agilant** vendor. So PO
+discovery from a transfer order must use `otherRefNum` + the Agilant vendor — never `createdPo`.
+NetSuite proof: SO **7326440** `tranid` 284624, `otherrefnum` EIT0012548; its lines' `createdpo` are
+all null; in NetSuite it links only to an invoice + item fulfillment (there is **no** PurchaseOrder
+record on the SO itself).
+
+### Operator tools for this path (manual CLI, NOT scheduled)
+
+- **`worker/crons/toga2/netsuite/probe_import_single_order_hh.php`** — imports/relinks **one**
+  NetSuite order by internal id for NYCHH. Builds lookups by requiring `common_sync_togasupply.php`
+  with all `IS_ENABLED_INTEGRATION_*` false, fetches via `fetchSalesOrderByIdFull`, routes via
+  `isTransferOrder`, runs `syncTransferOrderFromNetsuite`, then prints diagnostics (`[diag]` PO
+  lookup, `[trace]` header-link POST response) and verifies header + line links. No cursor writes /
+  no process lock.
+- **`worker/crons/toga2/netsuite/relink_transfer_order_pos_hh.php`** — backfills links for **all**
+  existing `Client_Nychh` transfer orders. Pages every `TransferOrders` row, fetches each NetSuite
+  order for its PO #, runs only the link step (`App_Api_Toga2::linkTransferOrderPurchaseOrders` — no
+  re-import), idempotent, per-order `try/catch` that logs + collects failures (a sanctioned
+  operator-tool exception to fail-loud), with a live progress bar + counts + end summary. Optional
+  first arg = limit.
+
 ## Transfer-order origin/destination location resolution
 
 `TransferOrders.originLocationId` is **NOT NULL**, so a missing origin fails the V2 insert with
@@ -384,6 +458,25 @@ item receipts replays about two years unless it is rewound forward first.
 
 ## Change history
 
+- 2026-09-16 - **RESOLVED: the PO↔TO bridge links were never being created** (fixed end-to-end,
+  prod-verified: PO EIT0012548 ↔ TO 284624 / SO 7326440, link `PurchaseOrderItems.id=589` ↔
+  `TransferOrderItems.id=7155`). Three stacked causes: (1) linking only ran from the `PURCHASE_ORDERS`
+  section, which never runs for NYCHH → new **public** `linkTransferOrderPurchaseOrders()` now runs on
+  every TO import/retry, idempotent, finds the customer PO by `otherRefNum` (split on `' + '`) on the
+  Agilant vendor (`clientConfiguration['importCustomerPurchaseOrdersOnVendor']`); (2)
+  `linkPurchaseOrderToTransferOrder` read TO items from `$transferOrder->transferOrderItems`, which
+  api2 NEVER inlines → now reads via `getTransferOrderItemsByUuid` (also lowered the TO GET to depth 1,
+  added `recordsPerPage=1000` to the PO-items GET); (3) **ROOT CAUSE** — the NYCHH API role had no
+  write ACL on bridge records **325** (`PurchaseOrders_TransferOrders`) / **329**
+  (`PurchaseOrderItems_TransferOrderItems`), so the POST failed **EZ-3/WZ-2**; the working SO bridge
+  (rec 276) had it. Fix migration `dbchanges2/Client_Nychh/2026-09-16a - TransferOrderBridgeAcl.sql`
+  seeds the full four-table chain + `AclFieldPermissions` for roles Base + API on 325/329, mirroring
+  276 (guarded, roles by name, random v4 uuids, Core ids hardcoded). Also made ACL failures loud in
+  the linker (both existence GETs THROW on no `totalRecordCount`). Recorded the NYCHH PO data model:
+  `createdPo` is NULL, the PO is the customer PO (`otherRefNum`) on the Agilant vendor. Added two
+  manual operator tools (`probe_import_single_order_hh.php`, `relink_transfer_order_pos_hh.php`).
+  `cto` AGREE, `sql-reviewer` SAFE TO MERGE. **Deploy: library + worker together (via a WORKER
+  deploy — the worker box runs its own `/var/www/library` clone).** (jcardinal)
 - 2026-09-14 - **RESOLVED: the INVENTORY_ADJUSTMENTS destination wedge.** Root cause (prod): TO 277871
   (SO 7102750) has customer **3997 "1896 Laurel Hill Management, LLC"** — not a NYCHH customer and with
   **no `Client_Nychh.Locations` row**, so the destination never resolved and the NOT NULL insert 1048'd

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.826",
+  "version": "1.0.828",
   "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/block-destructive.js

@@ -1,7 +1,25 @@
 'use strict';
-const input = (() => { try { return JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}'); } catch { return {}; } })();
+const fs = require('fs');
+
+/* Read the tool payload from stdin (how this harness delivers it) first, then
+ * fall back to the CLAUDE_TOOL_INPUT env var. Reading env only silently misses
+ * every call when the harness pipes JSON on stdin. */
+function readToolInput() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  if (raw && raw.trim()) {
+    try {
+      const d = JSON.parse(raw);
+      if (d && d.tool_input) return d.tool_input;
+    } catch (e) { /* fall through */ }
+  }
+  try { return JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}'); } catch (e) { return {}; }
+}
+
+const input = readToolInput();
 const command = typeof input.command === 'string' ? input.command : '';
 if (/rm\s+-rf|DROP\s+TABLE|DROP\s+DATABASE/i.test(command)) {
-  console.log('BLOCKED: Destructive command detected. If intentional, run it manually outside Claude Code.');
+  // exit 2 surfaces the reason from STDERR; stdout shows an opaque "No stderr output".
+  process.stderr.write('BLOCKED: destructive command detected (rm -rf / DROP TABLE / DROP DATABASE). If intentional, run it manually outside Claude Code.\n');
   process.exit(2);
 }

package/scripts/hooks/remind-frontend-review.js

@@ -18,7 +18,12 @@
 
 if (process.env.TOGA_FRONTEND_REVIEW_DISABLED === '1') process.exit(0);
 
+const fs = require('fs');
+// Read the tool payload from stdin first (this harness delivers it there), then env.
 const input = (() => {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) {}
+  if (raw && raw.trim()) { try { const d = JSON.parse(raw); if (d && d.tool_input) return d.tool_input; } catch (e) {} }
   try { return JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}'); } catch { return {}; }
 })();
 

package/scripts/hooks/remind-php-lint.js

@@ -2,7 +2,22 @@
 const os = require('os');
 const fs = require('fs');
 const path = require('path');
-const scopeFile = path.join(os.tmpdir(), 'toga-scope-' + (process.ppid || process.pid) + '.count');
+
+/* Key the scope file on the CC session id — MUST match scope-counter.js, which
+ * writes the same file. It previously keyed on process.ppid while scope-counter
+ * keyed on session_id, so this hook read a different (empty) file and never fired. */
+function sessionKey() {
+  let sid = '';
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    if (raw && raw.trim()) sid = JSON.parse(raw).session_id || '';
+  } catch (e) { /* no stdin */ }
+  sid = sid || process.env.CLAUDE_SESSION_ID || process.env.CLAUDE_CODE_SESSION_ID ||
+    String(process.ppid || process.pid);
+  return sid.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 64) || 'x';
+}
+
+const scopeFile = path.join(os.tmpdir(), 'toga-scope-' + sessionKey() + '.count');
 try {
   const count = parseInt(fs.readFileSync(scopeFile, 'utf8').trim(), 10) || 0;
   if (count > 0) {

package/scripts/hooks/remind-php-review.js

@@ -1,5 +1,12 @@
 'use strict';
-const input = (() => { try { return JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}'); } catch { return {}; } })();
+const fs = require('fs');
+// Read the tool payload from stdin first (this harness delivers it there), then env.
+const input = (() => {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) {}
+  if (raw && raw.trim()) { try { const d = JSON.parse(raw); if (d && d.tool_input) return d.tool_input; } catch (e) {} }
+  try { return JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}'); } catch { return {}; }
+})();
 const filePath = typeof input.file_path === 'string' ? input.file_path : '';
 if (/\.php$/i.test(filePath)) {
   console.log('PHP file edited. Consider running /code-review, or use the php-reviewer agent for security and framework pattern checks.');

package/scripts/hooks/remind-sql-review.js

@@ -11,7 +11,12 @@
  * into a deployment that a SQL review would have caught.
  */
 
+const fs = require('fs');
+// Read the tool payload from stdin first (this harness delivers it there), then env.
 const input = (() => {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) {}
+  if (raw && raw.trim()) { try { const d = JSON.parse(raw); if (d && d.tool_input) return d.tool_input; } catch (e) {} }
   try { return JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}'); } catch { return {}; }
 })();
 

package/scripts/hooks/sql-file-location.js

@@ -0,0 +1,71 @@
+'use strict';
+const fs = require('fs');
+
+/*
+ * sql-file-location.js — DENY creating a standalone `.sql` file anywhere but the
+ * migration repos.
+ *
+ * WHY: the team standard is absolute — schema/seed SQL lives ONLY in `dbchanges2`
+ * (2.0) or `dbchanges` (1.0). Application/core repos (`worker2`, `api2`,
+ * `_underscore`, `worker`, `library`, …) contain SQL only as query strings inside
+ * PHP — never a standalone `.sql` migration file. A `.sql` created in an app repo
+ * is invisible to the migration executor and never runs.
+ * See 2.0/standards/framework-rules.md + 1.0/standards/framework-rules.md
+ * → "Schema migrations — always in dbchanges(2)".
+ *
+ * A `.sql` under a `dbchanges2/` or `dbchanges/` path (including its `HISTORIC/`)
+ * is allowed. Vendored/third-party trees are skipped to avoid false positives.
+ *
+ * PreToolUse (Write|Edit|MultiEdit). Deny = stderr + exit 2.
+ * Escape hatch (false positives ONLY): TOGA_SQL_LOCATION_DISABLED=1
+ * Fail-open on any internal error.
+ */
+
+function readToolInput() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  if (raw && raw.trim()) {
+    try {
+      const d = JSON.parse(raw);
+      if (d && d.tool_input) return d.tool_input;
+    } catch (e) { /* fall through */ }
+  }
+  try { return JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}'); } catch (e) { return {}; }
+}
+
+function main() {
+  if (process.env.TOGA_SQL_LOCATION_DISABLED === '1') return;
+
+  const input = readToolInput();
+  const filePath = typeof input.file_path === 'string' ? input.file_path : '';
+  if (!/\.sql$/i.test(filePath)) return;
+
+  const norm = filePath.replace(/\\/g, '/').toLowerCase();
+
+  // Allowed home: the migration repos (and their HISTORIC archive).
+  if (/(^|\/)dbchanges2?\//.test(norm)) return;
+
+  // Skip vendored / generated trees — not our code to police.
+  if (/(^|\/)(vendor|node_modules|\.git)\//.test(norm)) return;
+
+  const out = [
+    'BLOCKED: a standalone `.sql` file may only live in a migration repo.',
+    '',
+    '  File: ' + filePath,
+    '',
+    'Team standard: all schema/seed SQL goes in `dbchanges2` (2.0) or `dbchanges` (1.0).',
+    'Application and core repos (worker2, api2, _underscore, worker, library, …) hold SQL',
+    'ONLY as query strings inside PHP — never a standalone `.sql` migration file. A `.sql`',
+    'created here is invisible to the migration executor and will never run.',
+    '',
+    'FIX: create the file under the matching `dbchanges2/<folder>/` (2.0) or `dbchanges/`',
+    '(1.0) path instead, named `YYYY-MM-DD<letter> - <Description>.sql`.',
+    'See 2.0/standards/framework-rules.md → "Schema migrations — always in dbchanges2".',
+    '',
+    '(False positive? Set TOGA_SQL_LOCATION_DISABLED=1 for this one case.)',
+  ];
+  process.stderr.write(out.join('\n') + '\n');
+  process.exit(2);
+}
+
+try { main(); } catch (e) { /* fail-open */ }