toga-ai 1.0.965 → 1.0.967

package/.claude/settings.json

@@ -172,6 +172,16 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/memory-scope-guard.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "SessionStart": [

package/knowledge/1.0/apps/test/features/2-0-deployment-client-sql.md

@@ -6,8 +6,8 @@ project: Test
 client: shared
 type: feature
 status: active
-updated: 2026-09-22
-owners: [jcardinal]
+updated: 2026-10-07
+owners: [jcardinal, mhammontree]
 files:
   - test/team/2.0 deployment/generate_client_sql.php
   - test/team/2.0 deployment/INPUT.sql
@@ -31,6 +31,12 @@ Use [Tools Multi-Client SQL](../../tools/features/multi-client-sql.md) instead (
 2. Reads one static list file; switch lists by commenting between `Clients_Db.txt` / `Logs_Clients_Db.txt` / `NetSuite_Clients_Db.txt` in the script.
 3. Per DB: banner comment, `` USE `<db>`; ``, then the SQL. Prints the combined script with a header and DB count.
 
+## The three list files (verified prod 2026-10-07)
+
+- **`Clients_Db.txt` — 35 entries, and all 35 match the live tenant databases exactly. It is NOT stale.** The 11 extra `Core.Clients` rows have no database (see [per-client DB connections](../../../../2.0/apps/_underscore/features/per-client-database-connections.md)); adding them would point the fan-out at databases that do not exist.
+- **`NetSuite_Clients_Db.txt` — 22 clients, an exact duplicate** of the clients whose `dbchanges2/Client_<Name>/_modules.txt` names `netsuite`. Same list kept twice; `_modules.txt` is the better source because it sits next to the client it describes.
+- Retiring these files means retiring `generate_client_sql.php` (it reads all three, including a commented-out `Logs_Clients_Db.txt`) — not just deleting text files. Production already uses tools `/developers/multi-client-sql`.
+
 ## Gotchas
 
 - Lists are static — a stale/missing DB is silently skipped. The Tools tool reads them live.
@@ -42,4 +48,6 @@ Use [Tools Multi-Client SQL](../../tools/features/multi-client-sql.md) instead (
 
 ## Change history
 
+- 2026-10-07 — Verified the list files: `Clients_Db.txt` is accurate (35/35); `NetSuite_Clients_Db.txt` duplicates dbchanges2 `_modules.txt`. (mhammontree)
+
 - 2026-09-22 — Marked superseded by Tools Multi-Client SQL; corrected input file (`INPUT.sql`) and list-switching. (jcardinal)

package/knowledge/1.0/apps/tools/features/multi-client-sql.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-09-24
-owners: [jcardinal]
+updated: 2026-10-07
+owners: [jcardinal, mhammontree]
 files:
   - tools/_/app/developers/multiclientsql.php
   - tools/mvc/developers/multi-client-sql/get.php
@@ -38,8 +38,19 @@ Replaces `test/team/2.0 deployment/generate_client_sql.php`. Development Team pe
 5. Every list returns a `skipped` array, shown on the page ("Skipped N (database not built — no DatabaseHosts row): …").
 6. Every DB/folder name is checked against `^[A-Za-z0-9_]{1,64}$` before it goes into GraphQL or a `USE` line. Page writes via `textContent`/`.value` only.
 
+## Reusing it from another tools page
+
+- `token()` is already `public static` and reads `GITHUB_TOKEN` from `getenv()` + `$_SERVER` + `$_ENV`. That token already has read access to `agilantsolutions/dbchanges2` in production — a second page needs **no new PAT and no new EB property**.
+- `graphql(string $fields, string $step)` is `private static` and carries the whole transport (curl, host pinned to `api.github.com`, bearer token, 30s timeout, one retry on a dropped connection, GraphQL error handling, and never logging the request because it holds the Authorization header). Making it `public static` is a one-keyword change with no behavior change — do that rather than re-implementing curl.
+- `GITHUB_BRANCH` is a const `_main` baked into expressions inside private methods. A page needing another branch builds its own field strings and borrows only the transport — do **not** thread a `$branch` parameter through the shipped class.
+- `DB_NAME_PATTERN` is `^[A-Za-z0-9_]{1,64}$` and **rejects dbchanges2 filenames** (`2026-06-03- BLANK_CLIENT_DATABASE.sql` has dashes, spaces, a dot). A page listing files needs its own filename pattern.
+- `treeFolders()` keeps only `type === 'tree'` — folders only, never files.
+- The `_modules.txt` parse (lowercase, trim, skip blank lines) already tolerates the trailing blank lines in `Client_Spglobal/_modules.txt`.
+
 ## Gotchas
 
+- Nested module folders are not handled: `_modules/Ai/Bdr/` makes the module list show `Ai` with zero member clients. Pre-existing live limitation, not a regression.
+
 - `Databases` is a MySQL reserved word: `FROM Databases` / `JOIN Databases AS X` fails with error 1064. Backtick it (`` `Databases` ``) or qualify it (`Core.Databases`).
 - dbchanges2 has **no** `_production` branch; its deployed branch is `_main`.
 - A missing `[database_...]` config section is not catchable in 1.0 — `App_Error` renders its HTML error page and exits. The tool pre-checks `config['database_toga2core']` and throws a user-safe message. Local `config.dev-*.ini` files may lack that section.
@@ -52,5 +63,7 @@ Replaces `test/team/2.0 deployment/generate_client_sql.php`. Development Team pe
 
 ## Change history
 
+- 2026-10-07 — Added the reuse map for other tools pages (`token()`, `graphql()`, the branch const and name patterns) and the nested `_modules/Ai/Bdr` limitation. (mhammontree)
+
 - 2026-09-22 — Created; shipped and verified in production. (jcardinal)
 - 2026-09-24 — Lists filtered by `Core.DatabaseHosts` for `ENVIRONMENT`; `skipped` list shown; verified prod 35 of 46. (jcardinal)

package/knowledge/1.0/apps/tools/features/saml-sso-auth.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-10-02
+updated: 2026-10-07
 owners: [jcardinal, ajean, mhammontree]
 files:
   - tools/_/app/auth.php
@@ -88,6 +88,7 @@ The platform's rotating key/value parameter store, on the **2.0 PROD Core DB** (
 - **Failure path also fataled → fixed (2026-06-30).** `tools_ssoFail()` called `http_response_code(401)` to render the "Authentication failed" page, which itself fataled with "headers already sent" and the error handler escalated it to an uncaught `ErrorException` → a bare **500** instead of the intended 401 page. Root cause: `App_FrameworkIndex::render()` turns on the preloader and runs `App_Page::flushCapture()` (`ob_end_flush + flush`, `library/app/page.php:213`) **before** `body()/App_MVC::loadFile()` runs the mvc page. Fixed with the same `if (!headers_sent()) { http_response_code(401); }` guard (matches `App_MVC::routeTo`'s own check).
 - **`App_Sso::initiate()` hard-requires a non-empty `apiSecretAccessToken`** (`library/app/sso.php:64-65`, `empty()` guard → `InvalidArgumentException`; the token encrypts the RelayState). An empty/absent token surfaces as a redirect to **`/login?error=1` ("Sign in failed. Please try again.")** — the initiate leg catches the exception (`sso/initiate/get.php:30-34`) and routes to `/login?error=1`. This fails **before** the IdP round-trip, so it never reaches the consumer's **"Authentication failed"** (`tools_ssoFail`) page. **The two error UIs tell you which leg failed:** `/login?error=1` = initiate (RelayState encryption / token), "Authentication failed" = consumer (decrypt). This was the 2026-06-30 regression — removing the config token per the (wrong) earlier note made initiate throw.
 - **Both legs depend on `db_toga2core` + a populated `Core.Parameters` token.** If `[database_toga2core]` is not configured, `currentApiSecret()`/`handoffKeys()` runs `App_Database::query` against an unregistered alias and **throws**. Because initiate only catches `InvalidArgumentException`/`RuntimeException`, that surfaces as a **500** — not the login banner. **Diagnostic:** a 500 at initiate = missing `db_toga2core`; `/login?error=1` = empty/absent `API_SECRET_ACCESS_TOKEN`.
+- **Local dev-bypass login fails with a bare "Sign in failed." — the cause is usually a missing config section, not SSO.** `tools/mvc/login/post.php` routed an invalid/empty email **and** a not-found user to `/login?error=1` with no logging, so three different causes looked identical. Each failure branch now writes one `error_log` line naming which branch fired (the not-found branch points at `[database_true]`). Root cause in practice: `config.dev-<name>.ini` is missing **`[database_true]`** and/or **`[database_toga2core]`**. Those two sections are commonly absent from local `config.dev-*.ini` files; without `[database_toga2core]` the Multi-Client SQL and Central IDs pages also fail. Copy them from a config that has both.
 - **No app-side replay defense.** The handoff token carries no nonce/timestamp the app verifies. Recommend the gateway embed `iat` + `jti`.
 
 ## Related
@@ -99,4 +100,6 @@ The platform's rotating key/value parameter store, on the **2.0 PROD Core DB** (
 - [TOGa Desk staff SSO (same pattern)](../../togadesk/features/staff-sso-login.md)
 
 ## Change history
+
+- 2026-10-07 — Dev-bypass login now logs which failure branch fired; documented the missing `[database_true]` / `[database_toga2core]` local-config cause. (mhammontree)
 - 2026-10-02 — Clarified sign-in is one click on an SSO button; no auto-detect of a Microsoft session (mhammontree)

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-09-23
+updated: 2026-10-07
 owners: ["jcardinal", "rgirish", "mhammontree", "ajean"]
 files:
   - _underscore/_underscore.php
@@ -177,22 +177,32 @@ string** has a single leading capital, rest lower-case (e.g. `Towfoundation`):
 | Tenant logs | `Logs_<Tenant>` | Per-client activity/audit logs. |
 | Framework logs | `Logs` | Generic 2.0 logs not tied to any client. |
 
-**Resolving a tenant string from a client name:** query `Core.Clients`. The
-`clientIdentifier` field **is** the exact suffix used in `Client_`, `Archive_`, and
-`Logs_` database names; the `name` field is the human-readable label. Look up by either
-to find the other:
+**Resolving a tenant's real database names:** query `Core.Clients`, then follow the id
+columns into `Core.Databases` — **never build the name as `'Client_' . $clientIdentifier`.**
 
 ```sql
 SELECT
-    name,
-    clientIdentifier
-FROM Clients
+    c.name,
+    c.clientIdentifier,
+    cd.name AS clientDatabase,
+    ld.name AS logDatabase,
+    ad.name AS archiveDatabase
+FROM Clients AS c
+    LEFT JOIN `Databases` AS cd ON cd.id = c.clientDatabaseId
+    LEFT JOIN `Databases` AS ld ON ld.id = c.logDatabaseId
+    LEFT JOIN `Databases` AS ad ON ad.id = c.archiveDatabaseId
 WHERE
-    name LIKE '%<keyword>%'
+    c.name LIKE '%<keyword>%'
 ```
 
-A client whose `clientIdentifier` is `Towfoundation` therefore lives in
-`Client_Towfoundation`, `Archive_Towfoundation`, and `Logs_Towfoundation`.
+`clientIdentifier` usually matches the suffix (`Towfoundation` → `Client_Towfoundation`,
+`Archive_Towfoundation`, `Logs_Towfoundation`), but that is a **convention, not a rule**.
+Verified in prod: `Compass_Usa` → `Client_Compass` / `Logs_Compass` / `Archive_Compass`, and
+`Compass_Canada` → `Client_CompassCanada` / `Logs_CompassCanada` / `Archive_CompassCanada`.
+There is no `Client_Compass_Usa`. A string-built name passes local testing and breaks in
+production for exactly those clients. Precedent that does it right:
+`App_Developers_MultiClientSql::coreLists()` in 1.0 `tools`. See
+[per-client database connections](features/per-client-database-connections.md).
 
 #### Non-production environments
 
@@ -428,3 +438,7 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
   message/trace to the client if `display_errors` is on unconditionally. Confirm `display_errors` is
   disabled in production and that the framework's error surface returns a sanitized envelope (not a raw
   stack trace) to API consumers. Not yet done — tracked as a follow-up.
+
+## Change history
+
+- 2026-10-07 — Corrected tenant DB-name resolution: resolve `Core.Clients` id columns into `Core.Databases`; `clientIdentifier` is not the suffix (Compass). (mhammontree)

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-10-06
+updated: 2026-10-07
 owners: ["dfranks", "jcardinal", "mhammontree", "apeterson", "kyalamarthi", "bala"]
 files:
   - _underscore/Database.php
@@ -59,7 +59,7 @@ When `_underscore` serves a request for a client it opens **three distinct per-c
 
 ## Gotchas
 
-- **`Core.Clients` has rows for clients whose DBs were never built** (prod 2026-09-24: 46 rows, 35 built). "DB exists" = a `Core.DatabaseHosts` row (`databaseId` + `environmentId` [+ `regionId`]) for the current `Environments.slug` — the same rows `registerClientDatabases()` resolves. Any fan-out over all clients must filter `EXISTS` on `DatabaseHosts` for the env, not `Core.Clients` alone; `isActive`-style flags are wrong (inactive clients still have DBs). Host-row count varies (e.g. `Archive_Nychh` has 1, others 4) — still built. Example: [Tools Multi-Client SQL](../../../../1.0/apps/tools/features/multi-client-sql.md).
+- **`Core.Clients` has rows for clients whose DBs were never built** (prod 2026-09-24: 46 rows, 35 built). "DB exists" = a `Core.DatabaseHosts` row (`databaseId` + `environmentId` [+ `regionId`]) for the current `Environments.slug` — the same rows `registerClientDatabases()` resolves. Any fan-out over all clients must filter `EXISTS` on `DatabaseHosts` for the env, not `Core.Clients` alone; `isActive`-style flags are wrong (inactive clients still have DBs). Host-row count varies (e.g. `Archive_Nychh` has 1, others 4) — still built. The 11 registered-but-never-provisioned clients (prod 2026-10-07): **Agilant, Athena, Cloudcsp, Companycom, Eclinicalworks, Ims, Newegg, Officedepot, Staples, Synnex, Walmart** — each has a `Core.Databases` row naming `Client_<Name>`, but no schema. Do **not** add them to any fan-out list. Also on the prod client cluster: a stray `Client_Compass_20260831_120000` schema (looks like an Aug-31 manual backup copy) — confirm with the owner before dropping. Example: [Tools Multi-Client SQL](../../../../1.0/apps/tools/features/multi-client-sql.md).
 - **⚠ NEVER read `LAST_INSERT_ID()` (or any other per-connection session value) through `_Query`.** `_Query` defaults `_isReadHostEnabled = true` (`Query.php:8`) and routes SELECTs to `CONNECTION_READ` (`Query.php:273-276`). `LAST_INSERT_ID()` is scoped to the connection that did the INSERT, so a read-host SELECT returns **0** — silently wrong, and now an FK violation wherever the id is used as a foreign key. Use `mysqli_insert_id` on the write/transaction connection and reject `<= 0`. It is not biting today only because most client registrations leave `writeHost`/`readHost` null, and `Database.php:488` then points READ and WRITE at the **same** `mysqli` handle (so raw `mysqli_query` and `new _Query(...)` share one connection and one transaction). Configuring a real read host for any client would break every such call at once. Worked example: [Compass PEOPLE-file user lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
 - **Locks and just-committed rows: force the writer and skip the cache.** A `_Query` SELECT goes to the read host and may be served from the query cache. For `GET_LOCK`/`RELEASE_LOCK` (session-scoped — must be on the writer) or reading a row another job just committed, call `$query->setisReadHostEnabled(false)` and `_Database::useQueryCache(false)`. Worked example: NYCDOE `Sftp/Import` per-checksum lock in [2.0 ASN SFTP Ingestion](../../../../clients/nycdoe/features/asn-sftp-ingestion-2-0.md).
 - **`_Database::transactionCommit()` / `transactionRollback()` with NO database argument leave each alias's "started" flag `true`.** A later `transactionStart()` in the same PHP process then never begins a transaction — writes autocommit and a rollback undoes nothing. Prod worker jobs and api2 requests are safe (one job/request = fresh process state); it bites long-lived processes and test harnesses. Reset with `\_Database::$_transactionStarts = []` before `transactionStart()` (see `runAsWorkerJob` in [worker2 Codeception tests](../../worker2/features/codeception-integration-tests.md)).
@@ -94,6 +94,7 @@ Methodology lesson — why the wrong conclusion was reached: the model-class com
 - [Re-pointing a DB alias mid-request](./database-alias-repointing.md)
 
 ## Change history
+- 2026-10-07 — Named the 11 registered-but-unprovisioned prod clients and the stray `Client_Compass_20260831_120000` backup schema. (mhammontree)
 - 2026-10-06 — Writer+no-cache reads for locks/just-committed rows; no-arg commit/rollback leaves the transaction-started flag set (mhammontree)
 - 2026-09-23 — Added the read-host routing trap: `_Query` sends SELECTs to `CONNECTION_READ`, so `LAST_INSERT_ID()` read through `_Query` can return 0; noted that null `writeHost`/`readHost` currently collapses both to one handle, and that raw `mysqli_query` needs a manual `resetQueryCache()`. (mhammontree)
 - 2026-09-24 — Added gotcha: filter client fan-outs by `DatabaseHosts` for the environment; `Core.Clients` includes never-built clients. (jcardinal)

package/knowledge/2.0/apps/dbchanges2/workflows/client-onboarding.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-09-16
+updated: 2026-10-07
 owners: ["mhammontree"]
 files:
   - Client/
@@ -51,6 +51,21 @@ Order matters — each step assumes the prior one ran.
 - **api2 / _underscore** — the API the client calls; verify here.
 - **Bastion** — production deploy path (upload SQL, source per cluster).
 
+## Planned onboarding tool — settled design (TRUE-79864)
+
+Platform-level and host-independent. Decided 2026-10-07; **host moved to Desk 2.0 (`toga25-desk`)**, which already plans an "Add Client" button. The 1.0 `tools` hosting plan is dead (no `App_Devops_*` classes, no 1.0 MVC page, no persona nav entry, and `App_Developers_MultiClientSql` is a 1.0 class Desk cannot reach). Builds on the 2026-06-22 Jeff design spec (ticket TRUE-79702) at `2.0-new-client-onboarding-consolidation.md` — read that file for the spec; it is not copied here.
+
+- **Generates SQL and guides. It never executes SQL and never writes to a repository.** Because it never writes, the "two onboardings at once" branch-lock problem does not exist.
+- **Output is split by cluster:** (A) `CREATE DATABASE` Client_/Logs_/Archive_; (B) the apply order for `Client_<Id>` — newest-dated blank, then loose `Client/*.sql` in filename order, then the chosen modules' files, **file names and order only, not the SQL text**; (C) the `Logs_Client/` blank for `Logs_<Id>`; (D) Core registration inserts (secret-free, committable); (E) `Apis` + `Apis_Roles` (secrets, shown once, never committed).
+- **`Logs_<Name>` is IN scope** even though the 2026-06-22 spec deferred it: the API logs there and checks the auth rate limit against it, so deferring it leaves a client that registers fine and then cannot authenticate.
+- **Branch is picked from a drop-down**, excluding the repo default branch (`_main`) and any protected branch — onboarding always runs against a ticket branch. Read the default branch name from the API; never hardcode it.
+- **Modules: selection only** (spec step 5 — read `_modules/`, tick what the client uses, fold its files into the apply order, write the client's `_modules.txt` line). Module **consolidation** (spec step 4) is OUT; it is a write. **Blank consolidation is also OUT** — `Client/HISTORIC` shows ~15 rewrites over ~2 years, so it is periodic maintenance on its own clock, not part of onboarding.
+- **The `Apis` secret is generated in the browser** with `crypto.getRandomValues` and the INSERT is built client-side, so plaintext never reaches the server or a log. (`crypto.randomUUID` and `crypto.subtle` are undefined on a non-secure origin; `getRandomValues` is not.)
+- **Run history: two new prod `Core` tables** — `ClientOnboardings` (client, branch, commit SHA, blank filename, loose-file count, ticket ref, who, status, email domains, modules, the ordered file list as TEXT) and `ClientOnboardingEnvironments` (FK to `Core.Environments.id`, isApplied, dtApplied, appliedByEmail). `Core.Environments` exists in prod with 27 rows (production = id 1). Two constraints: **no FK to the user** (`Client_True` is on the client cluster, `Core` on the core cluster), and **never store the `Apis` secret**.
+- **The internal API-key row is named `TOGA Technology`, not `Agilant`** — the old company name is not used for new work. The existing generator still emits `Agilant`.
+- **The one real correctness risk is a stale local checkout.** If the developer's checkout is ahead of the branch the tool reads, the tool lists *fewer* files than exist and the new client silently misses migrations, with no error. Mitigation: print the branch, the commit SHA, the file count, each file's blob SHA, and one verify command.
+- **Open question:** Desk is React talking to api2, so the GitHub read must move server-side into api2 or worker2 — a long read inside a web request hits a timeout problem.
+
 ## Gotchas
 
 - **🚨 The blank can be WRONG, not just behind — an open example (2026-08-28).** `Client/2026-06-03- BLANK_CLIENT_DATABASE.sql` creates `TransferOrderItems` (`CREATE` at ~line 9462) **without `dtCreated`/`dtUpdated`**, but `_Model_Client_TransferOrderItem` declares them as `FIELD_DATETIME_CREATED`/`FIELD_DATETIME_UPDATED`, so `_Model` puts them in **every SELECT it builds**. Every tenant provisioned from this blank has a table the model cannot read — nothing in a request has to ask for the columns. `Client/2026-08-28b - TransferOrderItemsTimestamps.sql` repairs existing tenants; **the blank itself is still unfixed**, so the next onboarding reproduces it. When a model-vs-blank mismatch is found, fix **both**: a catch-up `Client/` file for live tenants *and* the blank.
@@ -69,3 +84,7 @@ Order matters — each step assumes the prior one ran.
 - [TOGa 2.0 client onboarding SQL generator](../../../1.0/apps/test/features/toga2-client-onboarding-sql.md)
 - [TOGa 2.0 Client Onboarding Wizard](../../../1.0/apps/test/features/toga2-onboarding-wizard.md)
 - [Tickets API](../../api2/features/tickets-api.md)
+
+## Change history
+
+- 2026-10-07 — Recorded the settled design for the onboarding tool (TRUE-79864) and the decision to host it in Desk 2.0, not 1.0 tools. (mhammontree)

package/knowledge/2.0/standards/backend-php.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-10-06
+updated: 2026-10-07
 owners: [jcardinal, mhammontree, dfranks, bala, ajean]
 files: []
 related:
@@ -666,6 +666,9 @@ can follow. Do not type the child alone.
 
 * Use comments to explain the "why" behind the code, not the "how".
 * Inline comments should be used sparingly.
+* Keep a file docblock short: what the file is, plus the one or two traps that bite the next
+  editor. Design history, scope decisions, reuse notes and rejected approaches go to the
+  knowledge base at `/capture`, not into the file — they bury the code and go stale.
 
 #### **DocBlocks**
 
@@ -1023,3 +1026,7 @@ Existing static-key paths (ZoomInfo, VipSupport, `_Cloud` CLI) are grandfathered
 is deferred, not sanctioned for new work. Never record access-key values anywhere but the ini.
 
 See: 2.0/apps/worker2/features/cross-account-aws-access.md
+
+## Change history
+
+- 2026-10-07 — Added the short-file-docblock rule (design history belongs in the knowledge base). (mhammontree)

package/knowledge/CONVENTIONS.md

@@ -174,6 +174,9 @@ Every fact has exactly one home — never duplicate it into a second place.
   they're copied elsewhere. Kickoff/capture may be told to *read* one; never to *paste* it in.
 - **Everything a person must know lives in the team KB** — decisions, rules, gotchas,
   architecture. Not a generated file, not a stale wiki page.
+- **Never only in local Claude memory.** Memory is private to one machine: it holds talking
+  style, local paths, and personal habits only. A team rule goes here (or the platform apps'
+  docs) and memory keeps at most `Lives in: <where>` — see `rules/common/memory-scope.md`.
 - **App docs lifecycle (pre-MVP → launch → post-launch):**
   1. **Before MVP**, an in-development app's knowledge lives in the app repo's own `docs/`.
      The KB carries only a `registry.json` entry + a small `architecture.md` **stub**

package/knowledge/INDEX.md

@@ -45,7 +45,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togatech** (TOGA Technology Website) — 8 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
 - **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
 - **forward** (Forwarder) — 3 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
-- **claude** (Claude Harness) — 8 doc(s) → [standalone/apps/claude/INDEX.md](standalone/apps/claude/INDEX.md)
+- **claude** (Claude Harness) — 9 doc(s) → [standalone/apps/claude/INDEX.md](standalone/apps/claude/INDEX.md)
 - **powerbi** (Power BI) — 0 doc(s) → [standalone/apps/powerbi/INDEX.md](standalone/apps/powerbi/INDEX.md)
 
 ## Clients

package/knowledge/standalone/apps/claude/INDEX.md

@@ -2,6 +2,7 @@
 
 | Doc | Summary |
 |-----|---------|
+| [Memory Scope Guard — Keep Team Rules Out of Local Claude Memory](features/memory-scope-guard.md) | Rule + PostToolUse warn hook + `/capture` sweep that keep team build rules in the KB, not in one developer's private Claude memory. |
 | [Review-Enforcement Hooks — Mandatory sql-reviewer / php-reviewer Routing on Write](features/review-enforcement-hooks.md) | PostToolUse hooks that force a specialist review (`sql-reviewer` / `php-reviewer`) after SQL/PHP writes; open before turning either into a pre-write gate. |
 | [Harness Distribution — How a knowledge.js Fix Reaches Teammates](workflows/harness-distribution.md) | How a `knowledge.js` fix reaches teammates — two copies exist, only the git clone matters; `npx toga-ai` pulls it. |
 | [Knowledge Base Publish / Push Pipeline](workflows/knowledge-publish-pipeline.md) | How `/capture` and `/session-save` push knowledge docs to `agilantsolutions/claude` `_main` — the git sequence, retry, and the `47fbdc4` PUSH_FAILED fix. |

package/knowledge/standalone/apps/claude/features/memory-scope-guard.md

@@ -0,0 +1,54 @@
+---
+title: Memory Scope Guard — Keep Team Rules Out of Local Claude Memory
+framework: "standalone"
+repo: claude
+project: Claude Harness
+client: shared
+type: feature
+status: active
+updated: 2026-10-06
+owners: ["jcardinal"]
+files:
+  - claude/rules/common/memory-scope.md
+  - claude/scripts/hooks/memory-scope-guard.js
+  - claude/skills/capture/SKILL.md
+  - claude/.claude/settings.json
+related:
+  - standalone/apps/claude/features/review-enforcement-hooks.md
+---
+
+Rule + PostToolUse warn hook + `/capture` sweep that keep team build rules in the KB, not in one developer's private Claude memory. Open when the guard fires or a rule "only one dev knows".
+
+## Summary
+
+Local Claude memory (`~/.claude/projects/<project>/memory/*.md`, index `MEMORY.md`) is private to one machine. A scripted-API rule and ~80 build rules once lived only there, invisible to teammates. Three parts stop that:
+
+1. **Rule** `rules/common/memory-scope.md` (always-on, installed to `.claude/rules/toga/common/`): memory holds only personal things — talking style, local paths, personal habits (`type: user`). Any rule about how we build goes to the KB (platform-app rules: the architecture docs of every platform app — `toga25-desk`, `toga25-iq`, `toga2-template`) in the same change; memory keeps at most `Lives in: <where>`.
+2. **Hook** `scripts/hooks/memory-scope-guard.js` — warns, never blocks.
+3. **`/capture` Step 2b** — sweeps this session's memory notes, moves team rules into the KB, shrinks each note to its `Lives in:` pointer.
+
+`communication.md`'s per-person profile still lives in memory — the rule names it as personal.
+
+## How the hook works
+
+- Wired in the template `.claude/settings.json` → `PostToolUse`, matcher `Write|Edit|MultiEdit`.
+- Fires only when the target path is inside `.claude/projects/<x>/memory/` or `.claude/memory/` (either slash style) and ends `.md`.
+- Reads the note from disk (falls back to the written text) and warns when **one sentence or clause states a build rule**: a directive word (never, always, must, do not, don't, should, required) **and** a build term (SQL, dbchanges2, api2, _underscore, interceptor, ACL, RecordFields, Surface — capitalised only, blox, migration, endpoint, scripted, worker2, NetSuite, schema, component). Any `type:` except `user`.
+- Ignored text: `**Why:**` lines (they quote the reason), `(...)` asides, `[[note-name]]` links.
+- Never warns on: `type: user`; any note with a `Lives in:` line; names `user-*`, `repo-path-*`, `habit-*`, `*-profile`, or with `path|location|dir|folder` in the name. Lookup notes (paths, URLs, profiles, registries) and status/reminder notes stay quiet because they rarely pair a directive with a build term.
+- `MEMORY.md`: only added lines that are not `- [name](file.md)` pointers and name a build term.
+- Output: JSON `hookSpecificOutput.additionalContext` (the PostToolUse channel that reaches the model). Once per file per session (state in OS temp, `toga-memory-scope-<session>.json`). Always exit 0, fail-open.
+- Off switch: `TOGA_MEMORY_SCOPE_GUARD_DISABLED=1`.
+
+## Gotchas
+
+- Heuristic, not exact. It misses a rule worded without a directive word ("lock it into the app docs"). A personal habit saved as `type: feedback` that says "always ... SQL" will warn — save habits as `type: user` or name them `habit-*`.
+- Tuned 2026-10-06 against one developer's 140 notes: the first version fired on 14 (lookups and status notes); the current one fires on 0.
+- Plain stdout from a PostToolUse hook is not reliably shown to the model; this hook uses `additionalContext` on purpose.
+
+## Change history
+- 2026-10-06 — Created: memory-scope rule, guard hook, `/capture` Step 2b sweep; heuristic tuned to "directive + build term" to cut false positives (jcardinal)
+
+## Related
+
+- [Review-Enforcement Hooks](review-enforcement-hooks.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.965",
+  "version": "1.0.967",
   "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/rules/common/communication.md

@@ -142,3 +142,6 @@ How to keep it:
   the developer's known style and habits before you write a word.
 - **This profile is private and per-person. Never put it in the team knowledge base** — it lives
   only in that developer's local memory, on their machine.
+- **A personal habit is not a team rule.** "Run php -l for me" is a habit (memory, `type: user`).
+  "Record hooks go in api2 interceptors" is how we build (team KB). See
+  [memory-scope.md](memory-scope.md).

package/rules/common/memory-scope.md

@@ -0,0 +1,46 @@
+# Memory Scope — what goes in local memory vs the team KB
+
+A developer's local Claude memory (`~/.claude/projects/<project>/memory/*.md`, index
+`MEMORY.md`) is private to one machine. Teammates never see it. So it holds **only personal
+things**. Team rules go where the team can read them.
+
+## Local memory — personal only
+
+1. How this developer likes to be talked to (`user-communication-profile`).
+2. Their local machine paths (`repo-path-<repo>`, `team-repo-path`).
+3. Their personal work habits ("run php -l for me", "don't commit unless I say so").
+
+Save habit and profile notes as `type: user` (or name them `user-*`).
+
+## Team KB — every rule about HOW we build
+
+Anything about how we build goes into the team KB in the **same change** — never only into
+memory. That includes:
+
+- architecture and where code lives,
+- API shape (api2 endpoints, interceptors, scripted vs table APIs),
+- SQL and `dbchanges2`,
+- ACL and roles,
+- data model (Records, RecordFields, Surface/settings),
+- UI and design process, reuse (blox),
+- sync and integration behavior (NetSuite, worker2),
+- the harness itself (skills, hooks, rules).
+
+**Platform apps** (`toga25-desk`, `toga25-iq`, `toga2-template`): an app-build rule goes into
+the architecture docs of **every** platform app, not just the one you are in.
+
+## The rules
+
+1. **When a developer states a team rule, write it to the KB / app docs first.** Then, if
+   useful, keep a one-line pointer in memory.
+2. **Memory may keep at most a pointer** for a team rule:
+   `Lives in: <KB doc path or app doc § section>`. No copy of the rule body.
+3. **Unsure?** Ask: "would a teammate building the same thing need this?" Yes → KB.
+4. **At `/capture`**, move any team rule found in this session's memory notes into the KB and
+   shrink the note to its `Lives in:` pointer.
+
+## How this is enforced
+
+`scripts/hooks/memory-scope-guard.js` runs after every Write/Edit into a memory folder. If the
+note looks like a team rule, it warns (never blocks). Silence it with
+`TOGA_MEMORY_SCOPE_GUARD_DISABLED=1`.

package/scripts/hooks/memory-scope-guard.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * memory-scope-guard.js — WARN when a team rule is being written into a developer's
+ * LOCAL Claude memory instead of the team knowledge base.
+ *
+ * Why this exists: local memory (~/.claude/projects/<project>/memory/*.md, index
+ * MEMORY.md) is private to one machine. Teammates never see it. A scripted-API rule and
+ * ~80 build rules once lived only in one developer's memory. The rule
+ * (rules/common/memory-scope.md) says memory holds ONLY personal things — talking style,
+ * local paths, personal habits. Team rules go to the KB (or a platform app's docs), and
+ * memory keeps at most a one-line "Lives in:" pointer.
+ *
+ * How it works: registered on PostToolUse for Write|Edit|MultiEdit. It fires only when
+ * the target sits inside a Claude memory folder (`.claude/projects/<x>/memory/` or
+ * `.claude/memory/`, either slash style). It reads the note as written to disk and warns
+ * when the note STATES A BUILD RULE: one sentence holds both a directive word (never /
+ * always / must / do not / should / required) and a build term (SQL, api2, ACL, ...).
+ * Lookup notes (paths, URLs, profiles, registries) and status/reminder notes rarely pair
+ * the two, so they stay quiet. "Why:" lines are ignored (they quote the reason).
+ * Skipped: `type: user`; any note with a "Lives in:" pointer line; notes named user-*,
+ * repo-path-*, habit-*, *-profile, or with path/location/dir/folder in the name.
+ * MEMORY.md (the index) is checked only for added lines that are not "- [name](file.md)"
+ * pointers and that name build terms.
+ * The warning goes through the PostToolUse additionalContext channel. Once per file per
+ * session (state file in the OS temp dir, keyed on session id).
+ *
+ * It never blocks. It always exits 0 and fails open on any error.
+ *
+ * Escape hatch: set TOGA_MEMORY_SCOPE_GUARD_DISABLED=1 to silence the warning.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const RULE_DOC = 'rules/common/memory-scope.md';
+const MEMORY_INDEX_NAME = 'memory.md';
+const MAX_SEEN_PATHS = 500;
+
+const MEMORY_DIR_RE = /(^|\/)\.claude\/(projects\/[^/]+\/)?memory\//i;
+const PERSONAL_NAME_RE = /^(user-.*|repo-path-.*|habit-.*|.*-profile)$/i;
+const LOCATION_NAME_RE = /(^|-)(path|paths|location|dir|folder)(-|$)/i;
+const DIRECTIVE_RE = /\b(never|always|must(?: not)?|do not|don't|should(?: not)?|required)\b/i;
+const WHY_LINE_RE = /^\s*\**why\**\s*:/i;
+// Sentence or clause: split on . ! ? ; and line breaks.
+const SENTENCE_SPLIT_RE = /(?<=[.!?;])\s+|\r?\n/;
+// Asides in (...) describe, they do not set rules — e.g. "(so don't break it)".
+const PARENTHETICAL_RE = /\([^()]*\)/g;
+// [[note-name]] links name other notes; their words are not this note's rule.
+const WIKI_LINK_RE = /\[\[[^\]]*\]\]/g;
+const LIVES_IN_RE = /^\s*\**lives in\**\s*:/im;
+const INDEX_POINTER_RE = /^\s*-\s*\[[^\]]+\]\([^)]+\)/;
+const BUILD_TERMS_RE = new RegExp(
+  '\\b(' + [
+    'SQL', 'dbchanges2', 'api2', '_underscore', 'interceptors?', 'ACL', 'RecordFields',
+    'blox', 'migrations?', 'endpoints?', 'scripted', 'worker2', 'NetSuite',
+    'schema', 'components?',
+  ].join('|') + ')\\b',
+  'i'
+);
+// "surface" is also a common verb; only the capitalised platform layer name counts.
+const SURFACE_TERM_RE = /\b(Surface)\b/;
+
+function findBuildTerm(text) {
+  return text.match(BUILD_TERMS_RE) || text.match(SURFACE_TERM_RE);
+}
+
+function readPayload() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  let data = {};
+  if (raw && raw.trim()) {
+    try { data = JSON.parse(raw); } catch (e) { data = {}; }
+  }
+  if (!data.tool_name && process.env.CLAUDE_TOOL_NAME) data.tool_name = process.env.CLAUDE_TOOL_NAME;
+  if (!data.tool_input && process.env.CLAUDE_TOOL_INPUT) {
+    try { data.tool_input = JSON.parse(process.env.CLAUDE_TOOL_INPUT); } catch (e) { /* ignore */ }
+  }
+  if (!data.session_id) data.session_id = process.env.CLAUDE_SESSION_ID || process.env.CLAUDE_CODE_SESSION_ID;
+  return data;
+}
+
+/* Text this tool call added: Write content, Edit new_string, MultiEdit edits[].new_string. */
+function collectNewText(input) {
+  const parts = [];
+  if (typeof input.content === 'string') parts.push(input.content);
+  if (typeof input.new_string === 'string') parts.push(input.new_string);
+  if (Array.isArray(input.edits)) {
+    for (const e of input.edits) if (e && typeof e.new_string === 'string') parts.push(e.new_string);
+  }
+  return parts.join('\n');
+}
+
+/* Split a note into { front, body }. `front` is the raw frontmatter text ('' if none). */
+function splitFrontmatter(text) {
+  const m = text.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  return m ? { front: m[1], body: m[2] } : { front: '', body: text };
+}
+
+/* `type:` may sit at the top level or nested under `metadata:`. */
+function frontmatterValue(front, key) {
+  const m = front.match(new RegExp('^\\s*' + key + '\\s*:\\s*["\']?([^"\'\\r\\n]*)', 'im'));
+  return m ? m[1].trim() : '';
+}
+
+/* First sentence that states a rule about build work: a directive word (never / always /
+ * must / do not ...) AND a build term in the same sentence. Returns { directive, term,
+ * sentence } or null. Lookups (paths, profiles, registries) and status/reminder notes
+ * rarely pair the two, so they stay quiet. "Why:" lines quote the reason, not the rule. */
+function findRuleSentence(body) {
+  const lines = body.split(/\r?\n/).filter((l) => !WHY_LINE_RE.test(l));
+  const text = lines.join('\n').replace(WIKI_LINK_RE, ' ').replace(PARENTHETICAL_RE, ' ');
+  for (const sentence of text.split(SENTENCE_SPLIT_RE)) {
+    const directive = sentence.match(DIRECTIVE_RE);
+    if (!directive) continue;
+    const term = findBuildTerm(sentence);
+    if (term) return { directive: directive[1], term: term[1], sentence: sentence.trim() };
+  }
+  return null;
+}
+
+/* Returns a short reason string when the note looks like a team rule, else ''. */
+function teamRuleReason(fileText, fileBase) {
+  const { front, body } = splitFrontmatter(fileText);
+  const name = frontmatterValue(front, 'name') || fileBase;
+  if (PERSONAL_NAME_RE.test(name) || PERSONAL_NAME_RE.test(fileBase)) return '';
+  if (LOCATION_NAME_RE.test(name) || LOCATION_NAME_RE.test(fileBase)) return '';
+
+  const type = frontmatterValue(front, 'type').toLowerCase();
+  if (type === 'user') return '';
+  if (LIVES_IN_RE.test(body)) return '';
+
+  const hit = findRuleSentence(body);
+  if (!hit) return '';
+  return '`type: ' + (type || 'none') + '` note states a build rule ("' + hit.directive +
+    '" + "' + hit.term + '")';
+}
+
+/* MEMORY.md: warn only for added lines that are not index pointers and name build terms. */
+function indexRuleReason(newText) {
+  for (const line of newText.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith('#') || INDEX_POINTER_RE.test(t)) continue;
+    const term = findBuildTerm(t);
+    if (term) return 'MEMORY.md line that reads like a rule, not a pointer ("' + term[1] + '")';
+  }
+  return '';
+}
+
+function sessionKey(data) {
+  const sid = (data && data.session_id) || String(process.ppid || process.pid);
+  return String(sid).replace(/[^A-Za-z0-9_-]/g, '').slice(0, 64) || 'x';
+}
+
+/* True the first time this path is seen this session; records it. */
+function firstTimeThisSession(data, normPath) {
+  const sf = path.join(os.tmpdir(), 'toga-memory-scope-' + sessionKey(data) + '.json');
+  let seen = [];
+  try { seen = JSON.parse(fs.readFileSync(sf, 'utf8')) || []; } catch (e) { seen = []; }
+  if (!Array.isArray(seen)) seen = [];
+  if (seen.includes(normPath)) return false;
+  seen.push(normPath);
+  try { fs.writeFileSync(sf, JSON.stringify(seen.slice(-MAX_SEEN_PATHS))); } catch (e) { /* non-fatal */ }
+  return true;
+}
+
+function warning(filePath, reason) {
+  return [
+    '<system-reminder>',
+    'MEMORY SCOPE: ' + path.basename(filePath) + ' looks like a TEAM RULE (' + reason + '),',
+    'but local memory is private to this machine — teammates never see it.',
+    'Put the rule in the team KB (or, for a platform app, its architecture docs in every',
+    'platform app: toga25-desk, toga25-iq, toga2-template) in this same change.',
+    'Keep only a one-line pointer in memory, e.g. "Lives in: <KB doc or app doc § section>".',
+    'If this really is personal (talking style, local path, personal habit), ignore this.',
+    'Rule: ' + RULE_DOC + '.',
+    '</system-reminder>',
+  ].join('\n');
+}
+
+function main() {
+  if (process.env.TOGA_MEMORY_SCOPE_GUARD_DISABLED === '1') return;
+
+  const data = readPayload();
+  if (!/^(Write|Edit|MultiEdit)$/.test(data.tool_name || '')) return;
+
+  const input = data.tool_input || {};
+  const filePath = typeof input.file_path === 'string' ? input.file_path : '';
+  if (!filePath) return;
+
+  const norm = filePath.replace(/\\/g, '/');
+  if (!MEMORY_DIR_RE.test(norm) || !/\.md$/i.test(norm)) return;
+
+  const base = path.basename(norm);
+  let reason;
+  if (base.toLowerCase() === MEMORY_INDEX_NAME) {
+    reason = indexRuleReason(collectNewText(input));
+  } else {
+    let text = '';
+    try { text = fs.readFileSync(path.resolve(data.cwd || process.cwd(), filePath), 'utf8'); } catch (e) {
+      text = collectNewText(input); // file unreadable — judge what was written
+    }
+    reason = teamRuleReason(text, base.replace(/\.md$/i, ''));
+  }
+  if (!reason) return;
+
+  if (!firstTimeThisSession(data, norm.toLowerCase())) return;
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: warning(filePath, reason),
+    },
+  }));
+}
+
+try { main(); } catch (e) { /* fail-open: a warning hook must never brick a session */ }
+process.exitCode = 0; // always 0; exitCode (not exit()) lets stdout flush on Windows pipes

package/skills/capture/SKILL.md

@@ -121,6 +121,26 @@ That is the entire main-thread analysis job: summarize, do not investigate the K
 Never write `toga25-blox`'s inventory contents into the KB — it is generated-from-code and
 lives only in the repo (see CONVENTIONS → "Where knowledge lives").
 
+## Step 2b — Sweep this session's memory notes for team rules (main thread)
+
+Local memory is private; team rules belong in the KB (see `rules/common/memory-scope.md`).
+
+1. List the memory notes added or changed **this session**: files in the project's memory
+   folder (`~/.claude/projects/<project>/memory/*.md`) whose frontmatter `originSessionId`
+   matches this session, or whose `modified` time / file time is inside this session.
+   Skip `MEMORY.md`, `type: user` notes, and `user-*` / `repo-path-*` / `*-profile` notes.
+2. For each note that holds a **team rule** (how we build: architecture, API shape,
+   SQL/dbchanges2, ACL, data model, UI/design process, reuse, sync, harness) and has no
+   `Lives in:` line, add it to the digest's `changes[]` as **Decided**, with the rule text and
+   `files:` = the code/doc area it governs. For a platform-app rule, say it must go into the
+   architecture docs of every platform app (`toga25-desk`, `toga25-iq`, `toga2-template`) and
+   write those app docs yourself in this step (they live in the app repos, not the KB).
+3. **After Step 5** (once you know where each rule landed), shrink each of those memory notes
+   to its frontmatter plus one line: `Lives in: <KB doc path or app doc § section>`. Keep the
+   `MEMORY.md` pointer line.
+
+If no memory note this session holds a team rule, skip this step.
+
 ## Step 3 — Delegate to the `session-capture` subagent
 
 Spawn the subagent via the **Agent tool** with `subagent_type: session-capture`, passing the
@@ -177,7 +197,8 @@ person across sessions" in `rules/common/communication.md`.)
      unless I say so", "investigate before asking me", "run the DB query yourself").
 2. Update their profile in **local Claude memory** — talking style in a `user`-type note named
    `user-communication-profile`; each working habit as its own memory note (with its `MEMORY.md`
-   pointer). Add any clear new signal; don't duplicate what's already there.
+   pointer). Add any clear new signal; don't duplicate what's already there. Save these as
+   `type: user`. A rule about how we build is **not** a habit — it goes to the KB (Step 2b).
 3. **Only record clear signals** — prefer what they said directly over what you infer. Keep the
    notes short. If nothing new came up, do nothing.