toga-ai 1.0.1014 → 1.0.1016

package/CLAUDE.md

@@ -19,7 +19,7 @@ as `/skill-name` inside Claude Code.
 | Skill | Command | When to use |
 |-------|---------|-------------|
 | **start** | `/start TRUE-1234` | **Start of every session.** ClickUp ticket id only. Reads the ticket (apps, clients, task type, pseudocode), checks branches, then primes the framework architecture, coding standards, repo knowledge, and client context. Edits are blocked until it runs. |
-| **commit** | `/commit` | Commit only the files this session changed, with the session notes in the message. Never pushes. |
+| **commit** | `/commit` | Commit only the files this session changed, with the session notes in the message, then pushes the ticket branch. |
 | **pseudocode** | `/pseudocode` | Major tickets only. Writes the agreed approach as plain text to the ticket's Pseudocode field, after approval. |
 | **finish** | `/finish` | **End of every session.** Records what was built or changed into the knowledge base, checks the ticket fields, and when the ticket is done pushes, opens the PRs, comments on the ticket, and sets it to development finished. |
 | **toga-loop** | `/toga-loop` | Orchestrate a bigger or iterative change (multi-file feature, refactor, migration, sweep, or "keep going until X") as an explore→implement→verify loop driven by subagents, with progress tracked on a state file so it survives compaction and can resume. Run after `/start`. |
@@ -251,7 +251,7 @@ ticket — edits are blocked until you run it.
 ```
 /commit
 ```
-Commits only the files this session changed, with the session notes. It never pushes.
+Commits only the files this session changed, with the session notes, then pushes the ticket branch (never force).
 
 **End of every session — run this before closing:**
 ```

package/agents/backend-lead.md

@@ -59,7 +59,7 @@ You are the maker; you never sign off your own work.
    - `sql-reviewer` on any SQL (file or inline).
    - `cso` on anything touching auth, user input, credentials, or queries.
    Fix what they find and re-run until clean.
-5. **Stop at the working tree.** Do not commit or push — report what changed and wait.
+5. **Report what changed.** Commit and push happen through `/commit` (ticket branch, never force).
 
 ## Output
 

package/agents/frontend-lead.md

@@ -59,7 +59,7 @@ reviewer checks your work, not you.
    stale bundle until a full restart; don't trust a live browser check until then.
 4. **Review (required, via the Agent tool, off your thread):** `ecc:react-reviewer` on all
    `.jsx`/`.tsx`; `ecc:typescript-reviewer` on non-React `.ts`. Fix and re-run until clean.
-5. **Stop at the working tree** — do not commit or push. Report what changed.
+5. **Report what changed.** Commit and push happen through `/commit` (ticket branch, never force).
 
 ## Output
 

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

@@ -10,7 +10,7 @@
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest`, the 2.0 outbound HTTP client — JSON encode/decode, retry, and api-logging traps; open before calling it or reading `Logs.Api`. |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment names in multiple languages via an `AssortmentTranslations` sidecar table on the metadata-driven translation layer; open when translating asso |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | Run a slow WRITE asynchronously via the Worker tier so a long request write cannot hold a stale connection and hit "MySQL server has gone away"; open before usi |
-| [FIELD_AUTOINCREMENT record numbering (Parameters counter, race-safe, NULL-only trigger)](features/autoincrement-record-numbering.md) | ORM-generated record numbers (`SA100001`, `SR131021`) via `FIELD_AUTOINCREMENT` and the per-tenant `Parameters` counter that makes them race-safe; open when add |
+| [Record numbering (platform-wide FIELD_AUTOINCREMENT: Core.Records prefix + counter, scrambled)](features/autoincrement-record-numbering.md) | ORM record numbers (`SA1000000`, `AJ1419`, `CL519`) from one platform-wide counter per record type in `Core.Records`; open when adding a numbered model/prefix, |
 | [Calculated-column filter options (`<field>FilterOptions` model static → table meta)](features/calculated-column-filter-options.md) | Lets a calculated (`FIELD_SQL`) table column supply its own filter dropdown options via a `<field>FilterOptions` model static; open when adding a data-driven co |
 | [FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract](features/calculated-sql-fields.md) | A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model` enforces by throwing at model-construction time**, not by convent |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind Fulfill & Ship: buying/persisting a carrier label (UPS/FedEx) and creating the NetSuite Item Fulfillment; open for label, reprint, retu |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-10-07
+updated: 2026-10-13
 owners: ["jcardinal", "rgirish", "mhammontree", "ajean"]
 files:
   - _underscore/_underscore.php
@@ -282,9 +282,7 @@ Columns are declared as `public` properties set to field-type constants:
 - **Calculated:** `FIELD_SQL` (see below).
 
 **Field options** (the `FIELDOPT_*` array keys that tune a field): `FIELDOPT_DEFAULT` (default
-value), `FIELDOPT_FOREIGNKEY_MODEL` (target model class), `FIELDOPT_AUTOINCREMENT_PREFIX` /
-`FIELDOPT_AUTOINCREMENT_FIRSTNUMBER` / `FIELDOPT_AUTOINCREMENT_SUFFIX` (numbering scheme, see the
-autoincrement feature), and `FIELDOPT_SQL_STORED` / `FIELDOPT_SQL_TYPE` (calculated fields, below).
+value), `FIELDOPT_FOREIGNKEY_MODEL` (target model class), and `FIELDOPT_SQL_STORED` / `FIELDOPT_SQL_TYPE` (calculated fields, below).
 
 **Foreign keys** are arrays with the target model:
 

package/knowledge/2.0/apps/_underscore/features/autoincrement-record-numbering.md

@@ -1,85 +1,72 @@
 ---
-title: "FIELD_AUTOINCREMENT record numbering (Parameters counter, race-safe, NULL-only trigger)"
+title: "Record numbering (platform-wide FIELD_AUTOINCREMENT: Core.Records prefix + counter, scrambled)"
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-10-05
-owners: ["bala", "rgirish"]
+updated: 2026-10-13
+owners: ["bala", "rgirish", "jcardinal"]
 files:
   - _underscore/Model.php
   - _underscore/Database.php
   - _underscore/Model/Client/SalesOrder.php
+  - _underscore/Model/Client/ServiceRequest.php
   - _underscore/Model/Client/TransferOrder.php
-  - _underscore/Model/Prudential/ServiceRequest.php
+  - _underscore/Model/Compass/Canada/SalesOrder.php
+  - _underscore/Model/Core/Client.php
+  - dbchanges2/Core/2026-10-13d - RecordNumbering.sql
 related:
   - ../architecture.md
+  - ../../dbchanges2/architecture.md
   - ../../api2/features/v2-deadlock-retry.md
-  - ../../api2/features/environment-variable-drives-underscore-branch.md
   - ../../worker2/features/netsuite-transferorder-outbound-push.md
   - ../../worker2/features/netsuite-salesorder-outbound-push.md
 ---
 
-ORM-generated record numbers (`SA100001`, `SR131021`) via `FIELD_AUTOINCREMENT` and the per-tenant `Parameters` counter that makes them race-safe; open when adding a prefix, debugging a duplicate-number 1062, or load-testing creates.
+ORM record numbers (`SA1000000`, `AJ1419`, `CL519`) from one platform-wide counter per record type in `Core.Records`; open when adding a numbered model/prefix, debugging a 1062 on `number`, or touching `formatRecordNumber`.
 
 ## Summary
 
-A record number is generated by the ORM, not MySQL. A model declares:
-
-```php
-public $number = [
-	self::FIELD_AUTOINCREMENT,
-	self::FIELDOPT_AUTOINCREMENT_PREFIX => 'TA',
-	self::FIELDOPT_AUTOINCREMENT_FIRSTNUMBER => 100000,
-];
-```
-
-12 models use it (SalesOrder `SA`, PurchaseOrder `P`, ServiceRequest `SR`, TransferOrder `TA`, Ticket, ItemReceipt, InventoryAdjustment, ...). For `DB_CLIENT` models the next number comes from a **counter row in the tenant's `Parameters` table**, taken on its own connection, so concurrent creates never get the same number.
-
-**Branch state (verified 2026-10-02):** counter code (TRUE-82209, `1760b58a` + caps-key follow-up `bf22215b`) is on `_underscore` `_beta`, `_sandbox-dev`, `TRUE-82209`. **Not** on `_production` or `_sandbox-client` — prod still runs the old `MAX()+1` path and the Prudential `usleep` stopgap.
+A model declares `public $number = [self::FIELD_AUTOINCREMENT];` — nothing else (the old `FIELDOPT_AUTOINCREMENT_PREFIX/FIRSTNUMBER/SUFFIX` options, the `MAX()+1` path and the per-tenant `Parameters` counter / PR `_underscore#756` are gone; PR 756 must NOT be merged). Prefix and counter live in `Core.Records`, so numbers are unique across all clients. TRUE-82715.
 
 ## How it works
 
-1. **Fires only when the field is NULL.** A supplied number always wins (NetSuite importer's `tranId`, Compass PO `mitsSalesOrder`), and bypasses the counter. A front-end that posts `number` silently disables the generator.
-2. **Counter key:** `NEXT_NUMBER_<TABLE_IN_SNAKE_CASE>_<PREFIX><SUFFIX>`, all caps — e.g. `NEXT_NUMBER_SERVICE_REQUESTS_SR`, `NEXT_NUMBER_SALES_ORDERS_SA`, `NEXT_NUMBER_PURCHASE_ORDERS_P`, `NEXT_NUMBER_SALES_ORDERS_SAC` (Compass Canada). One row per table + prefix + suffix. `value` = last number issued.
-3. **Allocate** (`_Model::allocateAutoincrementNumber()`): `UPDATE Parameters SET value = LAST_INSERT_ID(CAST(value AS UNSIGNED)+1) WHERE key=...`, read back with `getInsertId()`, then **commit at once**. Runs on `_Database::DB_CLIENT_SEQUENCE` (`'ClientSequence'`), a separate connection — the api2 request transaction commits only at request end, so taking the row lock there would serialize every create.
-4. **`DB_CLIENT_SEQUENCE` is automatic.** `_Database::register()` points it at the same DB whenever the alias is `_underscore::DB_CLIENT` (covers api2, worker2, saml, cXML, Nychh worker), and drops its connection when DB_CLIENT is re-pointed to another tenant. No app change needed.
-5. **Self-seeding.** Row missing → run the old `MAX()` SQL on the sequence connection (writer, not read host), `INSERT ... ON DUPLICATE KEY UPDATE value = GREATEST(...)`, commit between each step. No per-tenant SQL or seed script.
-6. **Collision retry in `save()`.** If the INSERT fails 1062 **and** the message contains the number this save generated (a hand-set number took it), resync the counter past `MAX()` and retry, up to `MAX_AUTOINCREMENT_ATTEMPTS = 5`. A 1062 on any other unique key (uuid) is re-thrown. Any failed counter step rolls back the sequence connection.
-7. **Unchanged:** Core-DB models and `search()` keep the old `MAX()+1` path. **No zero padding** (prefix + integer). **Gaps are possible** (rolled-back request still used its number) — same as before.
+1. **Columns:** `Core.Records.numberPrefix CHAR(2) UNIQUE`, `nextNumber BIGINT UNSIGNED`. No `RecordFields` rows on purpose → not editable through the API.
+2. **Row lookup:** `_Model` walks its class + parents against `Records.model` (stored with leading backslash, UNIQUE). Client overrides (`_Model_Compass_Canada_SalesOrder`) use the base row (SA). No row / NULL prefix / NULL counter → plain `Exception` (fail loud).
+3. **Allocate:** `UPDATE Records SET nextNumber = LAST_INSERT_ID(nextNumber + 1) WHERE id = X` on `_Database::DB_CORE_SEQUENCE` (`'CoreSequence'`), committed at once; counter = insertId − 1. CoreSequence follows `DB_CORE` when registered (api2), else falls back to the config path of the physical Core DB (worker2 prod, saml). Re-registering Core with other settings closes the CoreSequence link.
+4. **Format:** `prefix + formatRecordNumber(counter)` — no hyphen, no check digit. d = digit count of counter, c = offset within that width: `shown = 10^(d-1) + (c * 387419) % (9*10^(d-1))`. Bijection per width (multiplier coprime to 2, 3, 5) → no uniqueness check or retry loop; same digit count as the counter; length grows on its own.
+5. **Start counters** (dbchanges2 seed): SA(14), SR(35), TK(99), ET(191) at 1000000 — 7 digits so they never equal old 6-digit numbers; PU(17), TR(312), RC(78), FF(28), AJ(154), CS(222) at 1000; CL(51) at 100 + client count. `Core.Clients.number VARCHAR(16) NOT NULL UNIQUE` added + backfilled in id order (RecordFields 2740).
+6. **Hand-set number wins** (counter untouched). 1062 retry up to 5 only when the dup is the number this save generated. `forSearching` with null number skips the field (keeps `load()`'s empty-WHERE guard).
+
+**Format rules (jcardinal):** 2-letter prefix, stored in `Core.Records` not the model; letters O, I, B banned (look like 0, 1, 8), L allowed; validate in PHP (no CHECK — see [dbchanges2 rule 15](../../dbchanges2/architecture.md)). TA → TR.
 
-**Rejected alternatives (2026-10-02):**
-- Whole-request replay via `DEADLOCK_RETRIABLE_ROUTES` for every numbered route — unsafe per tenant: Adyen / Elite / Growrk `postPost` hooks have external side effects. See [V2 request retry](../../api2/features/v2-deadlock-retry.md).
-- Derive number from the AUTO_INCREMENT `id` — `number` is NOT NULL UNIQUE and hand-set numbers break it.
-- `GET_LOCK` — the lock is held to request end, so creates serialize.
+**Rejected:** plain counter (type unreadable); numeric million bands (break at 1M); client id/date in number (long, leaks); check digit; Crockford base32 (hard to read aloud); random + exists-check loop; per-type multiplier column (edits break numbers); `numberMinDigits` column (start counter sets length). Block allocation of 1,000 deferred — one write per create is fine for now.
 
 ## Gotchas
 
-- **⚠ Old path race (still live on prod until this ships):** `SELECT MAX+1` then a separate INSERT → concurrent creates pick one number → loser gets 1062 `Duplicate entry 'SR131021' for key 'ServiceRequests.number'` → HTTP 400 `EV-10`, record lost. The number in the error belongs to the **winner**. **Staggering or delaying callers does NOT fix it** — the unsafe window is wider than a second: on dev-sandbox 2026-09-30 a losing request read at `11:45:02` while the winner committed at `11:45:03`. Prod rate on the old path: **8 failed `POST /v2/service-requests` for Prudential between 2026-09-10 and 2026-09-21**. Only the counter removes it.
-- **⚠ A prefix on a SHARED model is not unique across clients** — every tenant starts at `TA100000`. Never key a cross-client id on `number`; NetSuite account 1095849 is shared, so pushes key `externalId` on uuid (`toga-so-<uuid>` / `toga-to-<uuid>`).
-- **SA / TA numbers are placeholders** — overwritten by NetSuite `tranId` on write-back (~12s). Never build a key or match on `number`. Keeping a Toga number permanently needs **two** changes: a guard in `writeBackNetSuiteId()` **and** dropping `number` from the PUT in `library/app/api/toga2.php` (~L4295) and `_underscore/Trait/Netsuite/TransferOrder.php` (tried 2026-09-02, reverted).
-- **`FIELD_AUTOINCREMENT` is special-cased in `buildSqlFieldValue()`**, so a null value does not collapse a `load()` WHERE the way a null `FIELD_CHAR` does — see [_underscore architecture](../architecture.md).
-- **Adding the option renumbers nothing**; existing rows are untouched.
-- **Error class depends on boot.** Real boot calls `mysqli_report(MYSQLI_REPORT_STRICT)` (`Error.php:217`), so a failed query returns false and `_Query` throws `_Exception_Database` (which `save()` catches). A test harness that skips this boot gets raw `mysqli_sql_exception` instead — boot the framework fully when testing.
-- **Reproducing the race needs distinct rows per call.** Each concurrent test request must use a **different contact** (employee_xid / email) **and unit serialNumber**. Reusing one makes requests queue on that row lock and the race never shows (old code "passed" 10/10). Release all calls at once with the gate-file pattern ([V2 request retry](../../api2/features/v2-deadlock-retry.md)). Prudential `POST /v2/service-requests` also needs `customer.uuid`. Network latency is irrelevant.
-- **Beta can't take big bursts:** sandbox-dev DB `max_connections = 90`; ~15+ simultaneous requests → `Too many connections` → 500 `EO-1`. Keep bursts at ~10. See [ENVIRONMENT decides the branch](../../api2/features/environment-variable-drives-underscore-branch.md).
-- **Run `php -l Model.php Database.php` after resolving merge conflicts on env branches.** The TRUE-82209 merge into `_sandbox-dev`/`_beta` dropped `public static $_aliases` / `private static $_parked` in `Database.php` and duplicated `private $_model_generatedAutoincrementFields` in `Model.php` → beta outage (`Access to undeclared static property _Database::$_aliases`). The error page also dumped `$_SERVER`.
+- **⚠ NEVER change `AUTOINCREMENT_MULTIPLIER = 387419`** — every issued number depends on it.
+- **New numbered model needs a `Core.Records` row with `numberPrefix` + `nextNumber`** or creates throw. `Model/Client/Scope.php` (Desk branch TRUE-82615, prefix `'SC-'`) has no row: on merge make it plain `FIELD_AUTOINCREMENT` + seed a Records row prefix `SC`.
+- **Local DB with an old `Clients.number` (CL1…)** → the migration's ADD COLUMN fails; fix by hand locally. Prod had no such column though `_Model_Core_Client` declared one.
+- **SA / TR numbers are placeholders** — NetSuite `tranId` overwrites them on write-back (accepted). Never key a match on `number`; pushes key `externalId` on uuid.
+- **Old `MAX()+1` race (why this exists):** concurrent creates got one number → 1062 → HTTP 400 `EV-10`, record lost (Prudential SR, TRUE-82209). Staggering callers did not fix it.
+- **Gaps are possible** (a rolled-back request still used its number).
+- **Reproducing a race needs distinct rows per call** (different contact + serial) and a gate-file release ([V2 request retry](../../api2/features/v2-deadlock-retry.md)); sandbox-dev `max_connections = 90` → keep bursts ~10.
+- **Run `php -l Model.php Database.php` after merge conflicts on env branches** — a past merge dropped `_Database::$_aliases` → beta outage.
 
 ## Verification
 
-Beta (`api.beta.togahub.com` → sandbox-dev), 2026-10-02: before fix 8/10 concurrent creates failed 1062; after fix 100/100 (10 rounds of 10), 116 distinct numbers, counter matched `MAX()`.
+2026-10-13 local (Client_Elite): single create AJ1419 for counter 1000; 10 concurrent creates distinct, counter +10, no 1062; hand-set `TEST-HAND-1` kept, counter unchanged; Compass Canada → row 14 SA. 2,000,000-counter uniqueness test passed.
 
 ## Related
 
 - [_underscore architecture](../architecture.md)
-- [V2 request retry](../../api2/features/v2-deadlock-retry.md)
+- [dbchanges2 architecture](../../dbchanges2/architecture.md)
 - [NetSuite TransferOrder outbound push](../../worker2/features/netsuite-transferorder-outbound-push.md)
 - [NetSuite SalesOrder outbound push](../../worker2/features/netsuite-salesorder-outbound-push.md)
 
 ## Change history
-- 2026-10-05 — Noted the old `MAX()+1` window exceeds one second, so staggering callers is not a workaround; added the prod failure rate still seen on `_production`/`_sandbox-client`. (bala)
-- 2026-10-02 — Replaced unlocked `MAX()+1` with a per-tenant `Parameters` counter on its own committed connection (`DB_CLIENT_SEQUENCE`), self-seeding, 1062 resync retry; removed Prudential `usleep` stopgap. On `_beta`/`_sandbox-dev` only. (rgirish)
-- 2026-09-22 — Recorded that the `MAX+1` generator is not concurrency-safe. (rgirish)
-- 2026-09-02 — `TA` / 100000 added to the shared `_Model_Client_TransferOrder`. (bala)
+- 2026-10-13 — Replaced per-tenant Parameters counter (PR 756, not merged) with platform-wide prefix + counter in `Core.Records`, scrambled format; removed FIELDOPT_AUTOINCREMENT_* options and Prudential usleep. TRUE-82715. (jcardinal)
+- 2026-10-02 — Per-tenant Parameters counter on `_beta` (superseded). (rgirish)
+- 2026-09-02 — `TA` added to shared TransferOrder (now TR). (bala)

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

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-10-06
+updated: 2026-10-13
 owners: [jcardinal, mhammontree, bala, ajean]
 files:
   - Core/
@@ -258,6 +258,7 @@ This lifecycle is automated by a local browser tool — see the [TOGa 2.0 Client
     - No prose preamble in a migration file: one short line per statement; narrative goes to the ticket.
     - Before running on prod, confirm each tenant's existing natural-key values match EXACTLY, or a mismatch inserts a duplicate instead of a no-op.
 14. **Never assume a migration has or has not run — verify (ask, or SELECT the live schema) before claiming state or editing a file.** An applied file is immutable: to undo it, RESTORE the original file to match what ran, then add a NEW dated forward-only file that drops/changes it (fresh envs run both and converge; run envs run only the new one). MySQL has no `DROP COLUMN IF EXISTS`, so restoring the add is what makes the later drop safe everywhere.
+15. **Never add MySQL `CHECK` constraints in schema changes** — they caused problems with database backups (jcardinal, 2026-10-13). Validate allowed values in PHP instead.
 
 ## Bulk data loads — batch, and stage large sets in a temp table
 
@@ -393,3 +394,7 @@ The extra `SELECT … FROM ( … ) existing` layer both dodges error 1093 and pi
 - **A `Client/` fan-out file that hardcodes a `customRecordFieldId` wires the wrong field for 29 of 30 tenants with no error** (rule #10). Custom-field ids are per-client `AUTO_INCREMENT`; keep custom-field work in the tenant's own folder.
 - **An unguarded registration/seed insert can double-register** on a fresh environment (rule #7) — guard on the semantic identity, not the description.
 - **The `dbchanges2` folder name IS the target database.** Running a `Core/` file against a client DB fails as `Table 'Client_X.<Table>' doesn't exist` (files are unqualified by design) — which names a missing table, not the real mistake. See [targeting the right database](workflows/targeting-the-right-database.md).
+
+## Change history
+
+- 2026-10-13 — Added rule 15: no MySQL `CHECK` constraints (TRUE-82715). (jcardinal)

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

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-10-12
+updated: 2026-10-13
 owners: [jcardinal, mhammontree, dfranks, bala, ajean]
 files: []
 related:
@@ -51,6 +51,8 @@ conventions.
 10. Text/Blob fields
 11. Custom fields
 
+**No `CHECK` constraints.** Never add MySQL `CHECK` constraints in schema changes; they caused problems with database backups. Validate allowed values in PHP. See [dbchanges2 rule 15](../apps/dbchanges2/architecture.md).
+
 ### UUIDs
 
 * All records inserted in the 2.0 database must be given a random UUID in the second column of each table called `uuid`
@@ -1026,5 +1028,6 @@ See: 2.0/apps/worker2/features/cross-account-aws-access.md (role model),
 
 ## Change history
 
+- 2026-10-13 — Table Design: no MySQL `CHECK` constraints; validate in PHP (TRUE-82715). (jcardinal)
 - 2026-10-12 — AWS access rule now covers 1.0 + 2.0: no IAM keys, assume WorkloadsRuntime; static-key grandfathering removed (TRUE-82705). (jcardinal)
 - 2026-10-07 — Added the short-file-docblock rule (design history belongs in the knowledge base). (mhammontree)

package/knowledge/clients/prudential/profile.md

@@ -17,7 +17,7 @@ project: _Underscore
 client: prudential
 type: profile
 status: active
-updated: 2026-10-02
+updated: 2026-10-13
 owners: ["jcardinal", "rgirish", "bala", "mhammontree"]
 files: []
 related:
@@ -120,11 +120,10 @@ The order-created cron branches on this id; the shipped/delivered crons branch o
   The 15-minute `prudential_auth_rejection_alert.php` cron now alerts on them — see
   features/service-request-auth-rejection-alert.md.
 
-- **SR number race (ServiceNow bursts → 1062 `Duplicate entry 'SR…'` → 400 `EV-10`, SR lost).** Fixed in
-  the framework by a `Parameters` counter (`NEXT_NUMBER_SERVICE_REQUESTS_SR`); the `usleep(0.5–2s)` stopgap in
-  `_Model_Prudential_ServiceRequest::prePost()` is removed. Both on `_underscore` `_beta`/`_sandbox-dev` only
-  (2026-10-02) — prod still has the race and the stopgap. Load-test with a distinct contact + serial per call and
-  `customer.uuid` set. See [FIELD_AUTOINCREMENT record numbering](../../2.0/apps/_underscore/features/autoincrement-record-numbering.md).
+- **SR number race (TRUE-82209: ServiceNow bursts → 1062 `Duplicate entry 'SR…'` → 400 `EV-10`, SR lost).** Fixed by
+  platform-wide record numbers (TRUE-82715); the `usleep` stopgap in `_Model_Prudential_ServiceRequest::prePost()`
+  is removed. Load-test with a distinct contact + serial per call and `customer.uuid` set. See
+  [Record numbering](../../2.0/apps/_underscore/features/autoincrement-record-numbering.md).
 
 ## Monitoring
 - `Monitor/Prudential/{SalesOrderGenerationBacklog,DellPurchaseOrderTransmissionBacklog,OrderShippedUpdateBacklog}`

package/knowledge/standalone/apps/claude/workflows/clickup-ticket-workflow.md

@@ -6,7 +6,7 @@ project: Claude Harness
 client: shared
 type: workflow
 status: active
-updated: 2026-10-09
+updated: 2026-10-13
 owners: ["jcardinal"]
 files:
   - claude/skills/start/SKILL.md
@@ -43,11 +43,12 @@ writes, and agents until the session has a ticket. These replaced `/kickoff`, `/
    KB, moves the status `to do` -> `in progress`, and loads PR review feedback if an open PR
    exists (rework: same branch, same PR). If ClickUp can't be read, it stops — no offline mode.
 2. **`/commit`** — commits only this session's files, ticket from the session file, then the
-   branch. Never pushes.
+   branch. Then pushes the ticket branch (`git push -u origin <TICKET>`, never force).
 3. **`/pseudocode`** — major tickets only. Writes the agreed approach to the Pseudocode field
    after the developer approves. Touches no other field.
 4. **`/finish`** — always writes the team KB first. Then one approval list for ticket fields
-   (Application, Stakeholders, Task Type, title, Has UI Changes). If the ticket is done: push each
+   (Application, Stakeholders, Task Type, title, Has UI Changes). Then it asks "Is this ticket finished?" — a yes is the permission (no extra asks): commit any
+   uncommitted session files, push each
    repo with work, open or update a PR per repo, post a PM comment, set status
    `development finished`. The PM comment is plain bullets for a non-technical PM: "What
    changed" always; "Manual steps", "Still open", "Ticket fields changed by Claude" only when
@@ -177,6 +178,8 @@ All tested 2026-10-08:
 - 2026-10-09 — TRUE-82605: `/start` names the session `<TICKET>: <short title>` (set-title +
   SessionStart `sessionTitle`; `/rename` to paste). (jcardinal)
 
+- 2026-10-13 — `/commit` now pushes the ticket branch; `/finish`'s "finished" yes covers commit,
+  push, and PR with no extra asks; Claude may switch to the ticket branch in normal work. (jcardinal, TRUE-82715)
 ## Related
 
 - [Ticket-branch creation safety](./ticket-branch-creation-safety.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.1014",
+  "version": "1.0.1016",
   "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/git-workflow.md

@@ -9,37 +9,25 @@ Start every session with `/start TRUE-1234` (the ClickUp ticket id only). The `s
 blocks edits, writes, and agents until a session has a ticket. The ticket drives the branch name,
 the commit prefix, the PR title, and the ticket updates at `/finish`.
 
-## Claude never commits or pushes on its own
-
-Claude **must never** run `git commit`, `git push`, `git merge`, or open/merge a PR against a
-**project repo** unless the developer explicitly asked for it in that conversation.
-
-Writing and editing files is expected. **Publishing them is not.** After making changes, Claude
-stops at the working tree, reports what changed, and waits. The developer decides when it lands.
-
-Two exceptions, and only two:
-
-1. **The developer explicitly told Claude to** — "commit this", "push it", "open the PR". A
-   general "go ahead" on an implementation task is **not** commit authorization; it authorizes
-   the code changes, not the publish.
-2. **The team knowledge base repo** (`agilantsolutions/claude`, cloned to `~/toga-tech`) — the
-   `/finish` skill's KB capture commits and pushes to `_main`. That remains automatic.
-
-A standing directive from an earlier session does not carry forward. Blanket phrases like "you
-have full access" grant tool access, not publish authority. When in doubt: **don't commit, ask.**
-
-Invoking one of these skills **is** explicit authorization, but only for what that skill
-describes. It does not authorize publishing anything else in the session.
-
-- `/commit` — local commits of only the files this session changed. Never pushes.
-- `/finish` — the KB push to `_main`, the ticket-branch pushes, the PRs, and the ticket writes.
-  If this session's files are uncommitted, `/finish` asks once and, on "yes", runs the
-  `/commit` steps itself (same rules as `/commit`). Claude writes and posts the PM comment,
-  PR subject/body, commit notes, and KB summary itself — no approval prompt (secret scan
-  still runs). Ticket field changes still need the one approval list; pushes still ask.
-- `/ship`, `/land-and-deploy` — the commits, pushes, and PRs they describe.
-
-Force-pushing is never automatic in any repo, including the knowledge repo.
+## Commit, push, and PR — what Claude does (decided 2026-10-13, TRUE-82715)
+
+1. **`/commit`** commits only this session's files **and pushes the ticket branch**
+   (`git push -u origin <TICKET>`). Never force.
+2. **`/finish`** does the KB capture, then asks one question: **"Is this ticket finished?"**
+   On yes it: commits any uncommitted session files, pushes, opens (or updates) one PR per
+   repo, comments on the ticket, and sets the status. No extra "may I push?" or "may I open
+   the PR?" questions — that yes is the permission. Ticket field changes still use the one
+   approval list.
+3. **Branches.** Claude may create or switch to the ticket branch as part of normal work.
+4. `/ship`, `/land-and-deploy` — the commits, pushes, and PRs they describe.
+5. The KB repo (`~/toga-tech`) — `/finish` commits and pushes to `_main`.
+
+Always, in every repo:
+
+- Never force-push.
+- Never stash, and never discard someone's uncommitted changes.
+- Never commit straight to `_main` or the default branch of an app repo.
+- Never commit secrets, `.env` files, or local paths (secret scan still runs).
 
 ## Claude never creates git worktrees
 
@@ -63,25 +51,12 @@ that repo, Claude may run `start-helper.js create-branch` to create (from the de
 or check out the ticket branch `<TICKET>`. Nothing else: no worktree, no stash, never on a
 repo with uncommitted changes, never force-push. See *Branch naming*.
 
-## Claude never rewrites code because a branch changed
-
-Many developers work across many projects and switch branches constantly. A change that is
-"missing" from the working tree is almost always **on another branch** — not lost.
-
-If Claude notices that work it made earlier in the conversation is gone from the working tree,
-or sees it in the git history on a different branch, it **must stop and ask**. It must not:
+## Missing work is usually on another branch
 
-- Re-implement or re-write the code from memory
-- Switch branches itself (`git checkout`, `git switch`) to "restore" the work
-- Stash, cherry-pick, merge, or reset to recover it
-- Assume the developer wants it back
-
-The correct response is to **pause the conversation** and say what it observed — which changes
-appear absent, and which branch they seem to live on — then ask the developer to switch to that
-branch so the existing code can be reviewed. Reviewing what is actually there beats regenerating
-it: a rewrite silently discards whatever the developer (or a teammate) changed in the meantime.
-
-Only rewrite when explicitly told to.
+If work Claude made earlier is gone from the working tree, it is almost always on another
+branch — not lost. Do not re-write it from memory. Find the branch it lives on (`git log
+--all`), say so, and switch to it if the working tree is clean. If the tree has uncommitted
+changes, stop and ask — never stash or discard them.
 
 ## Check git before stating commit state
 
@@ -124,13 +99,17 @@ Never force-push to `_main` under any circumstances.
 The branch is the bare ClickUp ticket id — e.g. `TRUE-82600`. No prefix, no description.
 ClickUp may create it, or `/start` creates it. One branch per ticket per repo.
 
+**Base branch.** Only the new platform app repos (today `toga25-desk` and `toga25-iq`) branch from
+`toga25` and open their PR back to `toga25`. Every other repo (`_underscore`, `api2`, `worker2`,
+`dbchanges2`, …) uses its own default branch, even in the same session.
+
 `/start` checks that every repo on the ticket (from its Application values) is on the ticket
 branch. On a mismatch it asks once per repo: "Create/switch to `<TICKET>` in `<repo>` from
 `<base>`?" On yes it runs `start-helper.js create-branch` (checks out `origin/<TICKET>` or the
 local branch if one exists, else creates it from the default branch and pushes it with
 `git push -u`, never force). A repo with uncommitted changes is refused — Claude stops and
-says so. This is the only case where Claude creates or switches a branch; otherwise Claude
-never switches branches itself.
+says so. Claude may also create or switch to the ticket branch later in normal work, with the
+same limits.
 
 The KB/harness repo (`toga-tech`) is the exception: work there goes on `_main`.
 

package/rules/common/review-process.md

@@ -44,5 +44,5 @@ statement so its view is genuinely independent.
 3. A lead implements (`backend-lead` / `frontend-lead` / `database-architect`).
 4. Reviewers + `qa-engineer` verify (maker ≠ checker).
 5. `documentation-engineer` / `knowledge-writer` capture what's durable.
-6. Stop at the working tree. Claude never commits or pushes a project repo unless the
-   developer explicitly says so this session.
+6. `/commit` commits and pushes the ticket branch; `/finish` opens the PRs once the developer
+   says the ticket is finished. Never force-push.

package/scripts/install.js

@@ -588,7 +588,7 @@ ticket — edits are blocked until you run it.
 \`\`\`
 /commit
 \`\`\`
-Commits only the files this session changed, with the session notes. It never pushes.
+Commits only the files this session changed, with the session notes, then pushes the ticket branch (never force).
 
 **End of every session — run this before closing:**
 \`\`\`

package/skills/commit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: commit
-description: Commit ONLY the files this Claude Code session changed, in every repo it touched, and write the session's notes (why the task exists, what was found, approach, turned-down options, who decided) into the commit message so the PR reviewer can build the PR summary from it. The ticket comes from the /start session ticket, then the branch. Safe when several sessions work on the same branch in the same checkout. Never pushes — /finish pushes and opens the PRs. Trigger on "/commit", "commit this", "commit my changes".
+description: Commit ONLY the files this Claude Code session changed, in every repo it touched, and write the session's notes (why the task exists, what was found, approach, turned-down options, who decided) into the commit message so the PR reviewer can build the PR summary from it. The ticket comes from the /start session ticket, then the branch. Safe when several sessions work on the same branch in the same checkout. Then pushes the ticket branch (never force); /finish opens the PRs. Trigger on "/commit", "commit this", "commit my changes".
 ---
 
 # /commit — commit this session's files, with the session's notes
@@ -13,9 +13,11 @@ ticket comes from the `/start` session ticket file
 
 ## Step 0 — Rules
 
-- Running `/commit` IS the developer's explicit commit authorization — **for these commits only**.
-- Never push. Never `git add -A` or `git add .`. Never `--no-verify`. Never `--amend`.
-  Never switch branches. Never commit a file the developer did not approve.
+- Running `/commit` IS the authorization to commit these files and push the ticket branch.
+- Push only the ticket branch: `git -C <repo> push -u origin <TICKET>`. Never force-push. Never
+  push or commit straight to `_main` / the default branch of an app repo.
+- Never `git add -A` or `git add .`. Never `--no-verify`. Never `--amend`.
+  Never stash or discard uncommitted changes. Never commit a file the developer did not approve.
 
 ## Step 1 — Find your own session id
 
@@ -129,7 +131,8 @@ Then, per repo:
 
 1. `helper forget --session=<id> --repo=<repo> --files=<committed files, comma-separated>`
 2. Report per repo: short hash, subject, file count.
-3. Say: "Committed locally. /commit never pushes — run /finish when the ticket is done; it
-   pushes and opens the PRs."
-4. Say: changes made by hand outside Claude can still be committed the normal way in VS Code;
+3. Push: `git -C <repo> push -u origin <TICKET>` (never force). If the push is rejected, stop
+   and report it — do not force or rebase on your own.
+4. Say: "Committed and pushed. Run /finish when the ticket is done; it opens the PRs."
+5. Say: changes made by hand outside Claude can still be committed the normal way in VS Code;
    the PR reviewer will show those as manual changes.

package/skills/finish/SKILL.md

@@ -13,7 +13,8 @@ ClickUp reads run in the `ticket-reader` subagent. The main thread distills and
 
 Claude writes and posts all summary text itself — PM comment, PR subject and body, commit
 notes, KB capture summary. Never ask the developer to approve that wording. Approvals are only
-for real decisions: ticket field changes (one list), ELEVATED KB docs, and pushes.
+for real decisions: ticket field changes (one list), ELEVATED KB docs, and "Is this ticket finished?". A yes to
+that question is the permission to commit, push, and open the PRs — no extra asks.
 
 ## Step 0 — Rules, helpers, session ticket
 
@@ -349,10 +350,9 @@ skip Steps 12–14 and go to Step 15 (PM comment) and Step 16 (status).
    `origin/<TICKET>` if pushed). This includes commits from other sessions — that is intended.
    Keep for each: repo path, `owner/repo`, ahead count, pushed or not.
 2. `COMMIT status --session=<sid> --root="$CLAUDE_PROJECT_DIR"`. If any repo has `toCommit`
-   files: ask once — "These files aren't committed: <list>. Run /commit for them now?"
-   **Yes** → run the `/commit` skill's steps yourself (same rules as `skills/commit/SKILL.md`:
+   files: do not ask again — the "finished" yes covers it. Run the `/commit` skill's steps yourself (same rules as `skills/commit/SKILL.md`:
    only this session's files, the `Claude-Notes: v1` format), then re-run step 1 and continue.
-   **No** → stop and say "Run /finish again when they are committed." (Changes outside
+   (Changes outside
    Claude's list, `otherChanged`, are the developer's — mention them, do not block.)
 3. If `gh auth status` fails, say exactly: "Run `gh auth login` in a terminal, then tell me
    'done'". When they say done, run `gh auth status` again and continue only if it passes.

package/skills/start/SKILL.md

@@ -158,8 +158,9 @@ developer has not named the session.
    Branches named with the ticket id link to the ClickUp ticket through the GitHub
    integration — on the first real run, confirm the link shows on the ticket.
 
-This is the **only** time Claude creates or switches a branch, and only after the developer's
-yes (`rules/common/git-workflow.md`). On no, say: "Switch these repos to `<T>`, then tell me.
+Here Claude asks first. Later in the session Claude may create or switch to the ticket branch
+as part of normal work, with the same limits — never stash, never discard changes, never
+force (`rules/common/git-workflow.md`). On no, say: "Switch these repos to `<T>`, then tell me.
 Or say 'continue anyway'." Only on an explicit "continue anyway":
 
 ```