toga-ai 1.0.477 → 1.0.478

package/knowledge/1.0/apps/tools/features/design-demo-admin.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-07-24
+updated: 2026-07-30
 owners: [jcardinal]
 files:
   - tools/_/app/design/github.php
@@ -19,6 +19,7 @@ files:
   - tools/composer.json
 related:
   - ../architecture.md
+  - ../../../standards/frontend.md
   - ../features/persona-gated-navigation.md
   - ../features/saml-sso-auth.md
   - ../workflows/deploy-to-elastic-beanstalk-al2023.md
@@ -92,6 +93,29 @@ on the next write of that project.json. Tab management via a per-pill "⋯" menu
 - **Reorder** — a single-file `tabs.json` commit, validated as a **permutation** of the
   existing list.
 
+### Text-storage invariant: JSON holds plain text, escape once at display
+
+`tabs.json` tab names and `project.json` `title` values are stored as **plain text**. The
+single correct escape happens at display time in `assets/js/design.js` `esc()` (and in
+`buildStub()`, which `htmlspecialchars()` the title into the generated `index.html`).
+
+`App_Design_Github::decodeEntities()` (one pass of `html_entity_decode` with
+`ENT_QUOTES | UTF-8`) enforces that invariant at two chokepoints:
+
+- **On read out of storage** — `loadTabs()`, `normalizeTabs()` (including the legacy scalar
+  `tab`), and the project read's `title`.
+- **On names/titles read off a request** — `createTab()`, `renameTab()` (both old and new
+  name), `deleteTab()`, `reorderTabs()`, `filterKnownTabs()`, `createProject()`, and
+  `upload()` titles.
+
+Both sides are required: decoding only reads would make `renameTab()` compare a decoded
+`H&H` against a stored `H&H` and fail with *"No such tab."*; decoding only writes would
+leave already-bad stored data permanently double-escaped on screen.
+
+**Self-healing:** every tab write rewrites `tabs.json` and each affected `project.json` in
+full, so pre-encoded stored values are re-persisted as plain text on the next
+rename/delete/reorder. No manual repair of the `forward` repo is needed.
+
 ### Actions & UX
 
 - **Publish a version** — uploads a self-contained HTML export as the next `vN/index.html`,
@@ -147,10 +171,27 @@ None — internal/shared design-team tool.
   `curl_close()` calls. Audit ported code for other deprecated-in-8.x calls.
 - **Contents API inlines only ≤1 MB** — read exports with the raw media type (see above).
 - **Publishing pushes to `forward`'s `_main`** and triggers EB auto-deploy; no staging.
+- **Double-escaped names (`H&H` shown literally, rename fails with "No such tab.")** —
+  caused by values that arrived **already HTML-encoded** and were then correctly escaped once
+  more at display. The render path was never wrong; no current code path produces the
+  encoding (`createTab`/`createProject` and the JS transport `window.prompt` →
+  `URLSearchParams` → `$postField` trim/`mb_substr` are clean), so encoded values entered from
+  outside — a paste from rendered HTML, or a pre-fix build. Fixed defensively with
+  `decodeEntities()` on both the read and request sides (see above). Generated project stubs
+  were affected identically, because `buildStub()`'s single correct `htmlspecialchars()` was a
+  *second* escape on a pre-encoded title; storing titles plain fixes the stubs too.
 - Never hardcode the token in tracked source — a leaked `ghp_`/PAT must be rotated.
 
 ## Change history
 
+- 2026-07-30 — Fixed HTML-entity double-escaping of tab names and project titles (a tab named
+  `H&H` rendered as `H&H`, and renaming it failed with "No such tab."). Added
+  `App_Design_Github::decodeEntities()` and applied it on every read out of storage
+  (`loadTabs`, `normalizeTabs` incl. legacy scalar `tab`, project `title`) and on every
+  name/title read off a request (`createTab`, `renameTab`, `deleteTab`, `reorderTabs`,
+  `filterKnownTabs`, `createProject`, `upload`), so all comparisons are decoded-vs-decoded and
+  storage re-persists plain text. Defensive — no current code path produced the encoding.
+  Verified by the developer; not yet committed to `tools`. (jcardinal)
 - 2026-07-24 — Moved the Design Demo Admin from `forward` into the SSO-protected `tools` app
   (`App_Design_Github` + `/design` MVC route + namespaced assets + nav entry); still commits
   to `agilantsolutions/forward` `_main` and demos stay hosted at `demo.togatech.com`. Added

package/knowledge/1.0/standards/frontend.md

@@ -0,0 +1,75 @@
+---
+title: Front-End Standards
+framework: "1.0"
+project: Library
+client: shared
+type: standard
+status: active
+updated: 2026-07-30
+owners: [jcardinal]
+files: []
+related:
+  - ./backend-php.md
+  - ./framework-rules.md
+  - ../apps/tools/features/design-demo-admin.md
+  - ../apps/tools/features/talos-kb-documents-admin.md
+---
+
+# Front-End Standards (1.0 Legacy — `Browser_` / server-rendered UI)
+
+> **Scope.** Server-rendered UI and browser assets for the legacy **1.0** framework
+> (`Browser_` classes, `mvc/` get/post handlers, `assets/js`, `assets/css`). 1.0 is in
+> maintenance mode and historically inconsistent — match the file you are editing, and
+> prefer the cleaner pattern for new code. Do not retrofit 2.0 front-end conventions.
+
+## Output escaping: storage holds plain text, escape exactly once at display
+
+**Rule.** Persisted values — database columns, JSON manifests, config — hold **plain,
+unescaped text**. HTML escaping happens **exactly once**, at the moment the value is
+written into an HTML context (`htmlspecialchars($v, ENT_QUOTES, 'UTF-8')` server-side, or
+the view's `esc()` helper client-side).
+
+**Never** escape on the way *in* to storage. An escaped value in storage is a latent bug:
+the display layer escapes it a second time, and the user sees `H&H` instead of `H&H`.
+
+### Why it recurs
+
+The failure mode is a **round trip**, not a bad escape function:
+
+1. A value is rendered into an edit form / prompt already escaped for HTML.
+2. The user submits that form unchanged.
+3. The escaped string is stored verbatim — storage now holds `H&H`.
+4. Display escapes correctly once more → `H&H` on screen.
+
+Each round trip adds a level. Equality comparisons then fail too, because a freshly typed
+`H&H` no longer matches the stored `H&H` — which surfaces as a confusing
+"record not found" rather than as a display bug.
+
+### Required practice
+
+- Pre-fill form inputs and JS prompts with the **plain** value; let the templating layer
+  do the one escape it owns.
+- When a store may already contain encoded data, **decode on both sides** of the boundary:
+  a single `html_entity_decode($v, ENT_QUOTES, 'UTF-8')` on every read out of storage
+  **and** on every value read off a request. Decoding only one side leaves either broken
+  comparisons or undisplayable legacy rows.
+- Prefer stores that **rewrite records in full** on update, so the decode-on-write is
+  self-healing and no manual data repair is needed.
+- Escape for the **right context**: `htmlspecialchars` for HTML text/attributes,
+  `json_encode` (with `JSON_HEX_*` for inline `<script>`) for JavaScript. Never
+  hand-build JSON or rely on `htmlspecialchars` inside a JS context.
+
+### Precedents in the codebase
+
+- `tools/mvc/talos/vocabulary/post.php:74-80` — inline comment recording the rule after
+  form inputs pre-filled with `htmlspecialchars()` output accumulated encoding.
+- `tools/_/app/design/github.php` — `App_Design_Github::decodeEntities()` applied to tab
+  names and project titles on both the storage-read and request-read sides.
+
+## Change history
+
+- 2026-07-30 — Created. Establishes the escape-once/plain-text-storage invariant after a
+  second independent occurrence in `tools` (Design Demo Admin, following the Talos
+  vocabulary tool). (jcardinal)
+</content>
+</invoke>

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

@@ -194,6 +194,23 @@ All non-production environments are **all-in-one**: a single cluster per environ
 holds `Core`, `Client_<Tenant>`, `Archive_<Tenant>`, and `Logs_<Tenant>` together
 (no family split). Region/reader routing still applies per cluster.
 
+> **⚠ Consequence — never write a query that spans two database families.** Because
+> production splits the families across the four dedicated clusters above, a single SQL
+> statement that joins or sub-selects across them (e.g. `Client_Towfoundation` ↔ `Core`,
+> or `Client_<Tenant>` ↔ `Archive_<Tenant>`) **cannot resolve in production** — the foreign
+> schema is not on that server. And because **every non-production environment is all-in-one,
+> such a query runs perfectly in local/dev/QA/stage**, so the failure surfaces only after
+> release. Treat a successful non-prod run as **no evidence** that a query is cluster-safe.
+> Cross-family data must be assembled in **PHP across two connections** (`_Database` named
+> connections, one per family), never in one statement. Note the corollary that platform
+> databases `Core`, `Forecast`, and `Team` **do** share `prod-core`, so those are same-cluster
+> — but a cross-*database* query is still discouraged, and in `dbchanges2` it is forbidden
+> outright.
+>
+> For **`dbchanges2` migrations this is a hard, mechanically-enforced rule**: a `.sql` file may
+> only reference tables in the one database its folder targets. See
+> [dbchanges2 → Database isolation](../dbchanges2/architecture.md).
+
 | Environment (aliases) | Host |
 |---|---|
 | `dev-sandbox` / `sandbox-dev` / developer sandbox | `dev.sandbox.database.togahub.com` |

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

@@ -39,6 +39,10 @@ in a folder, then `b`, `c`, …). One folder per database; place client changes
 `Client_<Name>` folder. Never edit an already-run migration — add a new dated file instead. The
 `Client/` **blank must carry the baseline DATA seed** (roles, full ACL, reference/lookup tables,
 UI config) — **not just schema**; a schema-only blank produces non-functional clients.
+**A file may only reference tables in the ONE database its folder targets** — `Core`, `Client_*`,
+`Archive_*`, `Logs*`, and `Cache` are on **separate production clusters**, so any
+`OtherDatabase.Table` reference is unrunnable in production even though it works locally
+(see *Database isolation* below; enforced by the `dbchanges2-cluster-isolation` hook).
 
 ## File naming convention (the execution contract)
 
@@ -90,6 +94,101 @@ Spglobal, Trividiahealth, True, Wje, Wmchealth, Ynhh).
 `Client/` and `Logs_Client/` also contain `BLANK_CLIENT_DATABASE` / `BLANK_CLIENT_LOGS_DATABASE`
 seed scripts used to provision a brand-new tenant DB from scratch.
 
+## Database isolation — never query across databases (HARD RULE)
+
+**A `.sql` file in `dbchanges2` may only reference tables in the ONE database its folder
+targets, and it must reference them UNQUALIFIED.** Any `OtherDatabase.Table` reference — in a
+`JOIN`, a subquery, a `SET @var = (SELECT …)`, an `INSERT … SELECT`, a `NOT EXISTS` guard, or a
+`USE` statement — is a **hard violation**.
+
+**Why:** in **production** the 2.0 databases are **not one server**. `Core`, each
+`Client_<Tenant>`, each `Archive_<Tenant>`, `Logs`/`Logs_<Tenant>`, and `Cache` live on
+**entirely separate clusters** (see `2.0/apps/_underscore/architecture.md` → *Database
+architecture*). A cross-database query has no way to resolve the foreign schema there.
+
+**Why this is a trap rather than an obvious error:** **locally and in every non-prod
+environment all of these databases sit behind a single endpoint**, so a cross-database query
+runs perfectly, the migration looks correct, review passes — and it fails only when it reaches
+production. Never treat a successful local run as evidence that a query is cluster-safe.
+**Assume every database other than the file's own target is unreachable, always.**
+
+### Not allowed
+
+This is the canonical violation — a `Client_<Tenant>` migration resolving `Core` ids to copy ACL
+rows. `AclFieldPermissions` is in the client database, `Core.RecordFields` / `Core.Records` are
+on the **core cluster**:
+
+```sql
+-- WRONG — Core.* is a different cluster; this cannot run in production
+SET @serviceAddressFieldId = (
+	SELECT rf.id FROM Core.RecordFields rf
+	JOIN Core.Records r ON r.id = rf.recordId
+	WHERE r.`route` = 'entitlements' AND rf.`field` = 'serviceAddressId' LIMIT 1
+);
+SET @saleItemFieldId = (
+	SELECT rf.id FROM Core.RecordFields rf
+	JOIN Core.Records r ON r.id = rf.recordId
+	WHERE r.`route` = 'entitlements' AND rf.`field` = 'saleItemId' LIMIT 1
+);
+
+INSERT INTO AclFieldPermissions (uuid, recordFieldId, roleId, isWritable)
+	SELECT UUID(), @serviceAddressFieldId, sibling.roleId, 0
+	FROM AclFieldPermissions sibling
+	WHERE sibling.recordFieldId = @saleItemFieldId
+		AND @serviceAddressFieldId IS NOT NULL
+		AND NOT EXISTS (
+			SELECT 1 FROM AclFieldPermissions existing
+			WHERE existing.recordFieldId = @serviceAddressFieldId AND existing.roleId = sibling.roleId
+		);
+```
+
+### Allowed — replace the foreign lookup
+
+Use whichever fits; the goal is that **every table named in the file lives in the file's own
+database**:
+
+1. **Hardcode the identifier.** The `Core` row's `uuid` is stable across environments, so
+   pre-generate/look it up **once at authoring time** and embed the literal. (Same discipline as
+   rule #6 — a v4 UUID literal, never `UUID()`.)
+
+   ```sql
+   -- CORRECT — no foreign database read; the uuid literal is resolved at authoring time
+   SET @serviceAddressFieldId = (
+   	SELECT id FROM RecordFields
+   	WHERE uuid = '<pre-resolved v4 uuid of the serviceAddressId field>' LIMIT 1
+   );
+   ```
+
+2. **Resolve by slug / natural key inside the target database.** If the client database carries
+   its own copy of the identifying column (`field`, `route`, `name`, a code), match on that
+   instead of joining out to `Core`.
+
+3. **Split the change into one file per database folder.** If work genuinely spans two
+   databases, write a `Core/` file **and** a `Client_<Name>/` (or `Client/`) file, each
+   self-contained. Order them by date/letter so the `Core` half lands first, and carry any value
+   between them as a **hardcoded literal**, not a query.
+
+### Fan-out folders: no qualifier at all
+
+In `Client/`, `Logs_Client/`, and `_modules/<module>/` the target database **name is not fixed**
+— the executor runs the same file against every tenant DB. So there is no valid database
+qualifier in these folders whatsoever: **reference every table unqualified**, including tables in
+the database being targeted.
+
+### Enforcement
+
+This is enforced mechanically, not by convention. The `PreToolUse` hook
+`.claude/hooks/toga/dbchanges2-cluster-isolation.js` inspects every `Write`/`Edit`/`MultiEdit`
+of a `.sql` file under `dbchanges2`, resolves the target database from the folder, and **refuses
+the write** if the SQL qualifies any table with a different database name (`Core`, `Client*`,
+`Logs*`, `Archive*`, `Cache`, `Team`, including backticked and `USE` forms). Comments and string
+literals are stripped first, and table **aliases** (`rf.id`, `sibling.roleId`) are never flagged.
+`HISTORIC/` folders are skipped.
+
+> **Scope:** this rule and its hook apply to **`dbchanges2` only**. The 1.0 **`dbchanges`** repo
+> is **not** subject to it. If the hook ever misfires on legitimate SQL, `DBCHANGES2_ISOLATION_DISABLED=1`
+> is an escape hatch **for false positives only** — never to land a cross-database query.
+
 ## `_modules` — reusable, opt-in change-sets
 
 Some change-sets aren't applied to every client — only to clients that use a given **module**
@@ -189,6 +288,13 @@ its own header.)
    `prePost` interceptor is registered unguarded in `Client_Rate/2026-07-15 - PreInterceptor.sql`
    (record 191, `minDepth NULL`); a second guarded registration would have double-fired it. See
    `clients/rate/features/whole-home-warranty-purchase-guard.md`.
+8. **Never reference a database other than the folder's own target.** No `Core.Table` in a
+   `Client_<Name>/` file, no `Client_X.Table` in a `Core/` file, and **no database qualifier at
+   all** in the fan-out folders (`Client/`, `Logs_Client/`, `_modules/`). These databases are on
+   **separate production clusters**; the query works locally and dies in production. Resolve
+   foreign ids with a hardcoded v4 UUID literal or an in-database slug/natural key, or split the
+   work into one file per database folder. See *Database isolation* above — enforced by the
+   `dbchanges2-cluster-isolation` hook.
 
 ## Bulk data loads — batch, and stage large sets in a temp table
 
@@ -341,6 +447,17 @@ defined in `2.0/apps/_underscore/architecture.md`, and its change files create/a
 tables that `_Model_*` classes map to.
 
 ## Change history
+- 2026-07-29 — **Added *Database isolation — never query across databases* (HARD RULE) + rule #8.**
+  A `dbchanges2` `.sql` file may only reference tables in the one database its folder targets, and
+  must reference them unqualified; fan-out folders (`Client/`, `Logs_Client/`, `_modules/`) permit
+  no database qualifier at all. Rationale: in production `Core`, `Client_<Tenant>`,
+  `Archive_<Tenant>`, `Logs`/`Logs_<Tenant>`, and `Cache` are on **entirely separate clusters**,
+  while local/non-prod collapse them behind one endpoint — so a cross-database query passes review
+  and fails only in production. Replace foreign lookups with hardcoded v4 UUID literals, in-database
+  slugs/natural keys, or one file per database folder. Enforced mechanically by the new `PreToolUse`
+  hook `dbchanges2-cluster-isolation.js`, which refuses the write. Applies to `dbchanges2` **only** —
+  the 1.0 `dbchanges` repo is exempt. Cluster topology recorded in
+  `2.0/apps/_underscore/architecture.md` → *Database architecture*. (jcardinal)
 - 2026-07-29 — Added *Self-referencing INSERT...SELECT guard — wrap the existing-set subquery in
   a derived table*: an `INSERT...SELECT` guarded per-key against its own target must wrap the
   existing-set subquery in a derived table (DISTINCT/LIMIT) so MySQL materializes it once —

package/knowledge/2.0/standards/framework-rules.md

@@ -113,6 +113,30 @@ Never create a `.sql` file inside `worker2`, `api2`, `_underscore`, or any other
 application repo. The SQL that belongs in those repos is only query strings embedded in
 PHP code — not standalone migration files.
 
+### Database isolation in `dbchanges2` — one database per file (HARD RULE)
+
+**A `dbchanges2` `.sql` file may only reference tables in the ONE database its folder targets,
+and must reference them UNQUALIFIED.** Never write `Core.Table` in a `Client_<Name>/` file,
+never `Client_X.Table` in a `Core/` file, and use **no database qualifier at all** in the
+fan-out folders (`Client/`, `Logs_Client/`, `_modules/`), where the tenant database name is not
+fixed. This covers `JOIN`s, subqueries, `SET @var = (SELECT …)`, `INSERT … SELECT`, `NOT EXISTS`
+guards, and `USE`.
+
+In **production** `Core`, `Client_<Tenant>`, `Archive_<Tenant>`, `Logs`/`Logs_<Tenant>`, and
+`Cache` are on **entirely separate clusters**, so a cross-database statement cannot resolve
+there. **Local and every non-prod environment put all of them behind one endpoint**, so the
+query runs fine, passes review, and fails only in production — never trust a local run as proof
+it is safe.
+
+Instead: hardcode a pre-resolved **v4 UUID literal**, resolve rows by a **slug / natural key that
+exists in the target database**, or **split the work into one file per database folder** (passing
+values between them as literals, not queries).
+
+Enforced mechanically by the `PreToolUse` hook
+`.claude/hooks/toga/dbchanges2-cluster-isolation.js`, which refuses the write. Full rule,
+examples, and the approved rewrites: `2.0/apps/dbchanges2/architecture.md` → *Database
+isolation*. **Applies to `dbchanges2` only — the 1.0 `dbchanges` repo is exempt.**
+
 ## Checking dependencies before touching shared code
 
 `dependsOn` in `knowledge/registry.json` means a repo extends or depends on another repo's classes. Before modifying a class in a dependency repo (e.g. `_underscore` core):

package/package.json

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