toga-ai 1.0.789 → 1.0.790

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

@@ -45,7 +45,7 @@
 | [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`). |
+| [QA/QC Review Pipeline (ClickUp review chain, QC batch + defect/client-review)](features/qa-qc-review-pipeline.md) | The ClickUp-driven review + promotion chain for the platform-wide QA/QC dev process (per the approved `QA-QC Plan.txt`), moving a task through **Development → Q |
 | [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. |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. |

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: draft
-updated: 2026-09-08
+updated: 2026-09-09
 owners: [jcardinal]
 files:
   - worker2/Worker/Team/Github.php
@@ -25,9 +25,12 @@ than per-repo GitHub Actions. **Not deployed yet** — on the `feature-qa-qc` br
 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`.
+3. **The single guarded door to `_production`** — `MergeTaskToProduction`, the only path a merge
+   can reach `_production`, plus `FanProductionOut` and a hardened public `Merge()`.
 
-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).
+All three feed the QA/QC review flow: a denied review routes a task to Rework and reverts its code;
+an approved Task/Hotfix/Feature deploys through `MergeTaskToProduction` — see
+[QA/QC review pipeline](./qa-qc-review-pipeline.md).
 
 ## How it works
 
@@ -54,6 +57,22 @@ see [QA/QC review pipeline](./qa-qc-review-pipeline.md).
   merge-commit revert (and revert-of-revert) break there — rebuild-from-ledger is the only
   correct undo.
 
+### The single guarded door to `_production` (`MergeTaskToProduction`)
+
+- **`_production` is reachable ONLY through `_Worker_Team_GitHub::MergeTaskToProduction`.** It
+  groups a task's PRs by repo and merges each — used by the Hotfix flow and the Stage cron.
+- Two layers stop a double-deploy when a webhook re-fires:
+  1. a **per-repo `GET_LOCK`**, and
+  2. a **persisted deploy-claim** — a row in `EnvironmentBranchMerges` with `branch='_production'`.
+     A re-fired webhook or a cron re-run sees the claim and resumes instead of re-merging.
+- **Public `Merge()` is split** so no queue message can reach prod by accident:
+  - the public `Merge()` is a **thin wrapper that refuses any non-mirror merge to `_production`**;
+  - a private `performMerge()` is the actual engine.
+- **`FanProductionOut`** merges `_production` **into the rebuildable branches** after a deploy, to
+  keep them current.
+- **Reverts are rebuild-from-ledger, never a merge-commit revert** (see below) — this holds for
+  `_production`-carrying branches too.
+
 ### Safety rules (load-bearing)
 
 - **Force-push is gated to `REBUILDABLE_BRANCHES` only.** Mirror targets and `_production` are
@@ -70,13 +89,20 @@ see [QA/QC review pipeline](./qa-qc-review-pipeline.md).
 - **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).
+- **Nothing merges to `_production` except `MergeTaskToProduction`.** Public `Merge()` refuses a
+  non-mirror `_production` merge, so a stray queue message can't deploy. Re-fires are stopped by
+  the per-repo `GET_LOCK` + the persisted deploy-claim (`EnvironmentBranchMerges` `branch='_production'`).
 
 ## Change history
+- 2026-09-09 — Added the single guarded door to `_production` (draft, `feature-qa-qc`, not
+  deployed): `MergeTaskToProduction` (per-repo `GET_LOCK` + persisted deploy-claim in
+  `EnvironmentBranchMerges` `branch='_production'`, groups a task's PRs by repo); public `Merge()`
+  split into a wrapper that **refuses** any non-mirror `_production` merge + a private
+  `performMerge()` engine; `FanProductionOut` merges `_production` into the rebuildable branches.
+  (jcardinal)
 - 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

@@ -6,15 +6,20 @@ project: Worker
 client: shared
 type: feature
 status: draft
-updated: 2026-09-08
+updated: 2026-09-09
 owners: [jcardinal]
 files:
   - worker2/Worker/Clickup/QaReview.php
   - worker2/Worker/Clickup/QcReview.php
   - worker2/Worker/Clickup/QcBatch.php
+  - worker2/Worker/Clickup/StageBatch.php
+  - worker2/Worker/Clickup/FeatureReview.php
+  - worker2/Worker/Clickup/BeReview.php
   - worker2/Worker/Clickup.php
+  - worker2/Worker/Github.php
   - _underscore/Component/Api/Clickup/Clickup.php
-  - dbchanges2/Core/2026-09-08e - Insert QcBatch CronJob.sql
+  - dbchanges2/Core/2026-09-09a - Insert StageBatch CronJob.sql
+  - dbchanges2/Team/2026-09-09a - Add isApproved to PullRequests.sql
 related:
   - ./clickup-general-automation.md
   - ./qa-qc-branch-automation.md
@@ -23,17 +28,31 @@ related:
 
 ## Summary
 
-The ClickUp-driven **QA then QC** review chain for the platform-wide QA/QC dev process (per the
-approved `QA-QC Plan.txt`). Three **new** workers plus a new entry point in the shared ClickUp
-webhook handler. **Not deployed yet** — on the `feature-qa-qc` branch working tree.
+The ClickUp-driven review + promotion chain for the platform-wide QA/QC dev process (per the
+approved `QA-QC Plan.txt`), moving a task through **Development → QA → QC → (Client Review) →
+Stage → Production**. Several **new** workers plus entry points in the shared ClickUp webhook
+handler. **Not deployed yet** — on the `feature-qa-qc` branch working tree.
 
-- `_Worker_Clickup_QaReview` — the UI → FE → BE review chain.
-- `_Worker_Clickup_QcReview` — QC defect review + client review.
+- `_Worker_Clickup_QaReview` — the UI → FE → BE review chain (branches by Task Type; Hotfix
+  BE-approve jumps straight to QC-Hotfix).
+- `_Worker_Clickup_QcReview` — QC defect review + client review; also handles the **Hotfix**
+  defect gate and its `DeployHotfix` entry.
 - `_Worker_Clickup_QcBatch` — a weekday 4:30pm Central CRON that batches QA-Approved tasks into QC.
+- `_Worker_Clickup_StageBatch` — the **Wed 4:30pm Central** CRON that ships "To Deploy" tasks to
+  production (the Task-flow prod-deploy piece; replaces the retired legacy status-driven merge).
+- `_Worker_Clickup_FeatureReview` — the **Feature** flow: rolls a multi-subtask feature through the
+  same gates as a unit, advancing only when **all** subtasks clear a gate.
+- `_Worker_Clickup_BeReview` — **auto** BE-approve driven by GitHub PR reviews (removes the manual
+  BE-review step).
+
+**Scope gate — only fires in one ClickUp folder.** The whole automation is gated to the dedicated
+**"(TEST) True Dev Sprints"** folder (id `90116585845`, list `901111612373`) via
+`_Worker_Clickup::QA_QC_FOLDER_ID` + `isTaskInQaQcScope`, so it never touches live sprints.
 
 When a review is **denied**, the task is routed to **Rework** and its code changes are **reverted**
 from the QA/QC branch — see [QA/QC branch automation](./qa-qc-branch-automation.md) for how the
-revert (rebuild-from-ledger) works.
+revert (rebuild-from-ledger) works, and for the single guarded door to `_production`
+(`MergeTaskToProduction`) that the Stage cron and Hotfix flow deploy through.
 
 ## How it works
 
@@ -63,6 +82,52 @@ code triggered when a task *left* a status; the QA/QC entry must be on entering
   - **any Show Stopper** → **Rework** + revert;
   - otherwise route to **Stage (To Deploy)** or **Client-<letter> (Client Review)**.
 - **Client review webhook:** **Approved** → Stage / To Deploy; **Denied** → **Rework** + revert.
+- QC entry **sets Environment to `QC-<letter>`** (the plan's "clear" wording was a slip).
+
+### BE auto-approve from a GitHub PR (`_Worker_Clickup_BeReview::FromPr`)
+
+- Removes the manual BE-review step. `worker2/Worker/Github.php` gains a `pull_request_review`
+  case: it records each PR's approval in `PullRequests.isApproved`, parses the task custom id from
+  the PR title (`prTitleToCustomId` — first token, colon stripped), and dispatches `BeReview/FromPr`.
+- `FromPr` sets the task's **BE Review** field **Approved only once ALL of the task's `_production`
+  PRs are approved**; a changes-requested on any PR → **Denied**. Multi-repo task = one decision.
+- **PR → task lookup:** `PullRequests.title` (custom id) maps to a ClickUp task via
+  `Team.Tasks.customClickupIdentifier ↔ clickupIdentifier`.
+- Setting the BE Review field then drives `QaReview` (Task / Hotfix) or `FeatureReview` (Feature).
+
+### Hotfix flow (`QaReview` + `QcReview`)
+
+- Expedites a **single** task straight to production, **skipping Stage**.
+- `QaReview::handleBeReview` branches by Task Type; a **Hotfix** BE-approve → **QC-Hotfix**.
+- `QcReview` handles the Hotfix defect gate and exposes a `DeployHotfix` entry.
+- The merge to `_production` runs from the worker with **no human at the merge moment** — the
+  guard chain (task type + status + all-defects-reviewed + no-show-stopper + deploy-claim + lock)
+  makes that safe. The actual prod merge goes through `MergeTaskToProduction` — see
+  [QA/QC branch automation](./qa-qc-branch-automation.md).
+
+### Stage cron (`_Worker_Clickup_StageBatch`)
+
+- The **Wed 4:30pm Central** batch (`'30 16 * * 3'`, seeded by
+  `Core/2026-09-09a - Insert StageBatch CronJob.sql`) that ships **"To Deploy"** tasks to production.
+- `Process` loops `Team.Tasks` "to deploy" rows and dispatches **one `DeployTask` per task**, so
+  each stays under the 300s worker cap and a re-run **resumes via the deploy-claim** (no double
+  deploy). `DeployTask` ships via `MergeTaskToProduction` then the shared finalize
+  (`markProductionDeployed` + `releaseSubEnvironment`).
+- Replaces the **retired** legacy status-driven prod-merge (the old `to deploy` / `hotfix review`
+  switch cases in `Worker/Clickup.php`).
+
+### Feature flow (`_Worker_Clickup_FeatureReview`)
+
+- A large **Feature** is reviewed and deployed **as one unit**: it is **one feature branch**, with
+  PRs keyed by the **feature** custom_id; **subtasks are review-only (no code)**.
+- 5 phases: DevFinished QA-entry; UI + FE roll-ups; BE roll-up → QC; QC-defect + Client-review
+  roll-ups. Each phase advances the **feature** only when **all subtasks** clear that gate.
+- Runs under a **per-feature `GET_LOCK`** on the feature custom_id with a **fresh-in-lock status
+  re-fetch**, so two sibling subtask reviews can't double-advance.
+- `QaReview` / `QcReview` **skip** a Feature task or a Feature subtask (via a `parentIsFeature`
+  check) so `FeatureReview` owns them; `StageBatch` ships a Feature as one feature branch and
+  finalizes its subtasks (and skips subtasks in the batch scan).
+- The feature's own **BE Review is a MANUAL field for now** (jcardinal + CTO decision).
 
 ## Gotchas
 
@@ -71,12 +136,20 @@ code triggered when a task *left* a status; the QA/QC entry must be on entering
 - **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 conventions](./clickup-custom-field-conventions.md).
+- **The automation only fires inside the "(TEST) True Dev Sprints" folder.** `isTaskInQaQcScope`
+  gates the fan-out, `handleDevelopmentFinished`, and `QcBatch`. A task outside that folder is
+  ignored — verify the folder before expecting the flow to run.
+- **A Feature advances only when ALL subtasks clear a gate** — a single lagging subtask holds the
+  whole feature. Subtasks carry no code; only the feature branch does.
+- **`_underscore CLICK_UP_CUSTOM_FIELD_ID__CLIENT_REVIEW` was repointed** to the "(TEST) True Dev
+  Sprints" folder's field (`2c4ab51a-…`); all field ids were verified against that folder.
 
 ## Known security gaps (discovered, not yet fixed — separate tickets)
 
-- **ClickUp and GitHub webhooks are NOT signature-verified today.** Verification must live at the
-  **ingestion Lambda over the raw request body** — the worker only ever sees a **transformed**
-  payload and cannot re-verify a signature. Do not try to add verification in the worker.
+- **ClickUp and GitHub webhooks are NOT signature-verified today.** Verification (incl. the GitHub
+  HMAC check) must live at the **ingestion Lambda over the raw request body** — the worker only
+  ever sees a **transformed** payload and cannot re-verify a signature. Do not try to add
+  verification in the worker.
 - **`_Component_Api_Clickup::ACCESS_TOKEN` is a hardcoded, committed ClickUp token.** It must be
   **rotated and moved to an environment variable**. (Only the location is recorded here — never the
   value.) See also [ClickUp credential rotation](../workflows/clickup-credential-rotation.md).
@@ -84,6 +157,16 @@ code triggered when a task *left* a status; the QA/QC entry must be on entering
   separate ticket to escape/cast them.
 
 ## Change history
+- 2026-09-09 — Added the remaining flows (draft, on `feature-qa-qc`, not deployed): **Hotfix**
+  (QaReview branches by Task Type → QC-Hotfix; QcReview `DeployHotfix`), **Stage cron**
+  (`_Worker_Clickup_StageBatch`, Wed 4:30pm Central, one `DeployTask` per task, resumes via
+  deploy-claim; retired the legacy `to deploy`/`hotfix review` switch cases), **Feature** roll-up
+  (`_Worker_Clickup_FeatureReview`, one feature branch keyed by feature custom_id, subtasks
+  review-only, per-feature GET_LOCK + fresh-in-lock re-fetch), and **BE auto-approve from PR**
+  (`Github.php` `pull_request_review` → `BeReview::FromPr`; all `_production` PRs approved →
+  Approved; `PullRequests.isApproved`). Scoped the whole automation to the "(TEST) True Dev
+  Sprints" folder (`isTaskInQaQcScope`); repointed CLIENT_REVIEW field; QC entry sets
+  Environment `QC-<letter>`; UI Review N/A advances. (jcardinal)
 - 2026-09-08 — Initial (draft, on `feature-qa-qc`, not deployed): new QA chain (`_Worker_Clickup_QaReview`,
   UI→FE→BE, approve advances / deny → Rework+revert), QC batch (`_Worker_Clickup_QcBatch`, weekday
   4:30pm Central, QA-Approved → QC-Task, skips while QC busy) and QC defect/client review

package/package.json

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