toga-ai 1.0.784 → 1.0.785

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,12 +6,13 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-09-04
-owners: [bala, kyalamarthi, apeterson, ajean]
+updated: 2026-09-08
+owners: [bala, kyalamarthi, apeterson, ajean, jcardinal]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
   - dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql
   - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
+  - dbchanges2/Core/2026-09-08e - Insert QcBatch CronJob.sql
 related:
   - ../architecture.md
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
@@ -185,6 +186,20 @@ Copying one gives you a file that duplicates the job on a second run. Three mech
   pre-generated v4 literal makes the file **deterministic and reviewable**, and re-running it inserts
   nothing anyway because of the guard.
 
+Three more mechanics, confirmed writing `Core/2026-09-08e - Insert QcBatch CronJob.sql`:
+
+- **Reference `CronJobs` UNQUALIFIED in a `Core/` file** — write `INSERT INTO CronJobs …`, not
+  `Core.CronJobs`. A `Core/` file runs against the `Core` database, and a cross-database
+  `Core.` prefix is exactly the cluster reference that breaks in prod (same rule as `Client_*`
+  files never reaching into `Core`).
+- **⚠ Always set `dtCreated = NOW()` explicitly — a missing `dtCreated` writes a ZERO date, silently.**
+  This cluster's `sql_mode` is `''` (empty), so MySQL does **not** reject a `NOT NULL DATETIME`
+  with no value; it coerces it to `0000-00-00 00:00:00`. Nothing errors. Include `dtCreated` in
+  every `CronJobs` insert (and any other timestamped seed here).
+- **Guard on `uuid = <literal> OR action = '<action>'`.** Using both in the `NOT EXISTS` makes the
+  file a no-op whether a prior run inserted the row by its (pre-generated) uuid literal or an
+  earlier hand-written row already registered the same action.
+
 Decide `isActive` deliberately, and say why in the file header: `isActive = 1` is correct when the
 action has **no prerequisites** (e.g. an upsert-only sync that never deletes), and `0` when a human
 must sequence it. Give the job a `maxExecutionTime` and **place its schedule relative to its
@@ -295,6 +310,12 @@ concluding a migration is production-safe.
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-09-08 — Extended the **`Core.CronJobs` registration** shape with three mechanics confirmed on
+  `Core/2026-09-08e - Insert QcBatch CronJob.sql`: reference `CronJobs` **unqualified** in a `Core/`
+  file (a `Core.` prefix is a cross-database reference that breaks in prod); **always set
+  `dtCreated = NOW()`** because this cluster's `sql_mode` is `''` and a missing value silently writes
+  a `0000-00-00` zero date instead of erroring; and guard on **`uuid = <literal> OR action = '<action>'`**
+  so a re-run is a no-op by either key. (jcardinal)
 - 2026-09-04 — Sharpened the index guard: check `information_schema.STATISTICS` on **`COLUMN_NAME` +
   `SEQ_IN_INDEX = 1`**, not on `INDEX_NAME` — an existing index under a different name goes
   undetected by a name-based guard and you add a duplicate. Found while sizing (and then dropping)

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

@@ -9,6 +9,7 @@
 | [Automated PR Merger — Concurrent Force-Push Clobber Race](features/automated-pr-merger-force-push-race.md) | The automated PR merger `_Worker_Team_GitHub::Merge` (`worker2` `Worker/Team/Github.php`) merges approved PRs to `_production` by **force-pushing from a clone t |
 | [Callback Scheduling ("call me back") — worker2 AI-BDR](features/callback-scheduling.md) | The **AI-BDR callback path**: what happens between a prospect saying *"call me back later"* on a Vapi call and the dialer actually placing that second call. |
 | [ClickUp Connectivity Watchdog](features/clickup-connectivity-watchdog.md) | A cron watchdog that emails when the ClickUp integration looks disconnected during business hours. |
+| [ClickUp Custom-Field Conventions (constant IDs, runtime option values, Task Type migration)](features/clickup-custom-field-conventions.md) | How worker2 code must reference ClickUp custom fields. |
 | [ClickUp Design Sprint Automation (Final Design Outcome)](features/clickup-design-sprint-automation.md) | `_Worker_Clickup_Design` is meant to drive the design-sprint workflow in ClickUp via the API, replacing a set of native ClickUp automations. |
 | [ClickUp General Automation (Sub-Environment reservation, Has UI / Has Code roll-ups)](features/clickup-general-automation.md) | `_Worker_Clickup_GeneralAutomation` reacts to ClickUp custom-field changes on a Task. |
 | [ClickUp GitHub-tab Auto-linking & Ticket-id Branch Naming](features/clickup-github-autolink.md) | How ClickUp surfaces branches/PRs/commits in a ticket's **GitHub tab**, and the branch / PR-title naming convention that triggers it. |
@@ -43,6 +44,7 @@
 | [OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)](features/oneuptime-incident-clickup-sync.md) | An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for **currently-open** incidents and ensures a ClickUp task exists for eac |
 | [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. |
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- |
+| [QA/QC Branch Automation (auto-mirror + rebuild-from-ledger revert)](features/qa-qc-branch-automation.md) | Two CTO-approved (AGREE) pieces of GitHub branch automation, centralized in **worker2** rather than per-repo GitHub Actions. |
 | [QA/QC Review Pipeline (ClickUp review chain, QC batch + defect/client-review)](features/qa-qc-review-pipeline.md) | The ClickUp-driven **QA then QC** review chain for the platform-wide QA/QC dev process (per the approved `QA-QC Plan.txt`). |
 | [Service Request → Sales Order → Purchase Order generation (Sync/ServiceRequest)](features/service-request-sales-order-generation.md) | `_Worker_Sync_ServiceRequest` turns a **Service Request into a Sales Order, and then into one Purchase Order per vendor**, for **any** tenant. |
 | [SSO Stability Monitor (Monitor/Operations/SsoStability)](features/sso-stability-monitor.md) | `_Worker_Monitor_Operations::SsoStability(): string` is the **reporter half** of the SAML uptime monitor. |

package/knowledge/2.0/apps/worker2/features/clickup-custom-field-conventions.md

@@ -0,0 +1,60 @@
+---
+title: ClickUp Custom-Field Conventions (constant IDs, runtime option values, Task Type migration)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: draft
+updated: 2026-09-08
+owners: [jcardinal]
+files:
+  - _underscore/Component/Api/Clickup/Clickup.php
+related:
+  - ./clickup-general-automation.md
+  - ./qa-qc-review-pipeline.md
+---
+
+## Summary
+
+How worker2 code must reference ClickUp custom fields. Two rules that keep automation from
+breaking when ClickUp field/option ids change, plus the in-flight **Task Type** field migration.
+
+## How it works
+
+### Field IDs are constants; option VALUES are resolved at runtime
+
+- Custom-field IDs are named constants on `_Component_Api_Clickup`
+  (`CLICK_UP_CUSTOM_FIELD_ID__*`). **Reference the constant, never a raw id string.**
+- Dropdown option **values** are resolved at **runtime** from the field's
+  `type_config->options` — read by `orderindex`, set by option id. **Never hardcode** an
+  option's numeric value; ClickUp reassigns them.
+
+### Task Type migration — two separate fields
+
+There are currently **two** Task Type fields, mid-migration:
+
+- **OLD** `093170c3` = `CLICK_UP_CUSTOM_FIELD_ID__TASK_TYPE` — still used by the **Design
+  iteration carry**. Design tasks carry **only** the OLD field.
+- **NEW (QA/QC)** `dc9f15da` = `CLICK_UP_CUSTOM_FIELD_ID__TASK_TYPE_NEW`.
+
+## Gotchas
+
+- **Do NOT repoint the shared `CLICK_UP_CUSTOM_FIELD_ID__TASK_TYPE` constant to the new
+  field** while Design tasks carry only the OLD field — it breaks the Design iteration carry.
+  New QA/QC code reads `..._TASK_TYPE_NEW`; leave the OLD constant pointing at `093170c3`.
+- **Never hardcode a dropdown option value** — resolve it from `type_config->options` at runtime.
+
+## Security
+
+The ClickUp webhook-signature gap and the hardcoded `_Component_Api_Clickup::ACCESS_TOKEN` are
+captured (with the rotation plan) in [QA/QC review pipeline](./qa-qc-review-pipeline.md) — see
+its *Known security gaps* section rather than duplicating them here. Never paste the token value.
+
+## Change history
+- 2026-09-08 — Initial (draft, on `feature-qa-qc`, not deployed): documented constant-ID /
+  runtime-option-value rule and the two-field Task Type migration (OLD `093170c3`
+  `..._TASK_TYPE` still used by Design iteration carry; NEW `dc9f15da` `..._TASK_TYPE_NEW`). Do
+  not repoint the shared constant while Design tasks carry only OLD. (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/worker2/features/clickup-general-automation.md

@@ -15,7 +15,7 @@ files:
 related:
   - ./qa-qc-review-pipeline.md
   - ./clickup-work-type-automation.md
-  - ../../standards/clickup-custom-fields.md
+  - ./clickup-custom-field-conventions.md
 ---
 
 ## Summary
@@ -65,7 +65,7 @@ Entry: `_Worker_Clickup::Webhook` inspects the field change and fans out to
   the `CLICK_UP_CUSTOM_FIELD_ID__*` constants in `_Component_Api_Clickup`; dropdown option values
   are read at runtime from `type_config->options` (by `orderindex`, set by option id) — never
   hardcode an option's numeric value. See
-  [ClickUp custom-field handling](../../standards/clickup-custom-fields.md).
+  [ClickUp custom-field conventions](./clickup-custom-field-conventions.md).
 
 ## Change history
 - 2026-09-08 — Initial (draft, on `feature-qa-qc`, not deployed): new `_Worker_Clickup_GeneralAutomation`

package/knowledge/2.0/apps/worker2/features/qa-qc-branch-automation.md

@@ -0,0 +1,82 @@
+---
+title: QA/QC Branch Automation (auto-mirror + rebuild-from-ledger revert)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: draft
+updated: 2026-09-08
+owners: [jcardinal]
+files:
+  - worker2/Worker/Team/Github.php
+  - worker2/Worker/Github.php
+  - dbchanges2/Team/2026-09-08a - Create EnvironmentBranchMerges table.sql
+related:
+  - ./qa-qc-review-pipeline.md
+  - ../architecture.md
+---
+
+## Summary
+
+Two CTO-approved (AGREE) pieces of GitHub branch automation, centralized in **worker2** rather
+than per-repo GitHub Actions. **Not deployed yet** — on the `feature-qa-qc` branch working tree.
+
+1. **Branch auto-mirror** — keep certain branches a byte-for-byte copy of a source branch.
+2. **Rebuild-from-ledger revert** — undo one task's changes on a QA/QC branch by rebuilding the
+   branch from its merge ledger, not by `git revert`.
+
+Both feed the QA/QC review flow: a denied review routes a task to Rework and reverts its code —
+see [QA/QC review pipeline](./qa-qc-review-pipeline.md).
+
+## How it works
+
+### Branch auto-mirror
+
+- `MIRROR_MAP` declares target ← source pairs:
+  - `_sandbox-client` ← `_production`
+  - `_demo` ← `_production`
+  - `_security-qc` ← `_stage`
+  - `_performance-qc` ← `_stage`
+- Driven by GitHub `push` webhooks; one `runTask` per target.
+- A mirror = **hard-reset the target to the source + `git push --force-with-lease`**. This is
+  safe **only** because a mirror target holds no work of its own — it is a pure copy.
+
+### Rebuild-from-ledger revert
+
+- Pieces: `RevertTask` / `RebuildBranch` / `recordMerge`, the `REBUILDABLE_BRANCHES` allowlist,
+  and the `Team.EnvironmentBranchMerges` ledger (created by
+  `2026-09-08a - Create EnvironmentBranchMerges table.sql`).
+- To undo one task's changes on a QA/QC branch, **rebuild** the branch: reset to `_production`,
+  then re-merge the remaining good tasks from the ledger (all recorded merges **minus** the
+  failed task).
+- This replaces `git revert -m 1`. QA/QC env branches also carry `_production` merges, so
+  merge-commit revert (and revert-of-revert) break there — rebuild-from-ledger is the only
+  correct undo.
+
+### Safety rules (load-bearing)
+
+- **Force-push is gated to `REBUILDABLE_BRANCHES` only.** Mirror targets and `_production` are
+  excluded from rebuild force-push.
+- **A per-repo+branch MySQL `GET_LOCK` serializes a merge against a rebuild** so they never
+  interleave on the same branch.
+- **Conflicts skip + email** — a conflicted rebuild/merge is skipped and reported, never pushed
+  half-built.
+
+## Gotchas
+
+- **A mirror target must hold no work of its own.** The force-push mirror overwrites it whole;
+  any local-only commits on a mirror target are lost.
+- **Never `git revert` a QA/QC env-branch merge.** Env branches carry `_production` merges too,
+  so merge-commit revert / revert-of-revert break. Use `RebuildBranch` (reset + re-merge from
+  the ledger).
+
+## Change history
+- 2026-09-08 — Initial (draft, on `feature-qa-qc`, not deployed): centralized GitHub branch
+  automation in worker2. Auto-mirror via `MIRROR_MAP` (hard-reset + force-with-lease, push
+  webhook-driven); rebuild-from-ledger revert (`RevertTask`/`RebuildBranch`/`recordMerge`,
+  `REBUILDABLE_BRANCHES`, `Team.EnvironmentBranchMerges`) replacing `git revert -m 1`. Force-push
+  gated to rebuildable branches; `GET_LOCK` serializes merge vs rebuild; conflicts skip+email.
+  (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/worker2/features/qa-qc-review-pipeline.md

@@ -18,7 +18,7 @@ files:
 related:
   - ./clickup-general-automation.md
   - ./qa-qc-branch-automation.md
-  - ../../standards/clickup-custom-fields.md
+  - ./clickup-custom-field-conventions.md
 ---
 
 ## Summary
@@ -70,7 +70,7 @@ code triggered when a task *left* a status; the QA/QC entry must be on entering
   QA/QC entry point had to move to the entering event or the whole chain never starts.
 - **The unit-test gate is a stub (`runUnitTests()` returns true).** It does not block anything yet.
 - **Custom-field option VALUES are resolved at runtime, IDs are constants** — see
-  [ClickUp custom-field handling](../../standards/clickup-custom-fields.md).
+  [ClickUp custom-field conventions](./clickup-custom-field-conventions.md).
 
 ## Known security gaps (discovered, not yet fixed — separate tickets)
 

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 82 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 66 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 68 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 15 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 9 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/package.json

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