toga-ai 1.0.443 → 1.0.444

package/knowledge/1.0/apps/togadesk/INDEX.md

@@ -3,11 +3,12 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Desk Architecture](architecture.md) | TOGa Desk is the staff-facing support desk **and field-service platform** (analysts work at `/desk/`). | desk/index.php, desk/includes/loader.php, desk/config.php, desk/includes/controllers/actions.php, desk/includes/controllers/data.php, desk/includes/controllers/modals.php, desk/includes/classes/class.app.php, desk/includes/classes/class.ticket.php, desk/api/index.php, desk/api/resources/tickets.php, crons/tickets.php |
-| [Email-to-Ticket Intake (crons/tickets.php)](features/email-to-ticket-intake.md) | TOGa Desk ingests support email into tickets through a cron-driven IMAP poller (`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). | crons/tickets.php, crons/tickets_prod.php, crons/pipe.php, desk/includes/classes/class.ticket.php |
+| [Email-to-Ticket Intake (crons/tickets.php)](features/email-to-ticket-intake.md) | TOGa Desk ingests support email into tickets through a cron-driven IMAP poller (`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). | crons/tickets.php, crons/tickets_prod.php, crons/pipe.php, desk/includes/classes/class.ticket.php, vendor/classes/class.imap.php |
 | [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairorder.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
 | [Managed Service Order Create Flow (New MSO modal → tickets/add)](features/managed-service-order-create.md) | The **Managed Service Order (MSO) create flow** is how a TOGa Desk user manually creates a managed service order: pick an End User (or a Client Location), choos | desk/includes/controllers/actions/tickets/add.php, desk/template/modals/tickets/addNew.php, desk/template/pages/managed.php, desk/template/pages/getinfo.php, desk/template/footer.php, library/app/model/togadesk/repairorder.php |
 | [Ticket Email Notifications (notifications table)](features/notifications.md) | Which TOGa Desk emails fire for a given client is driven **entirely by data**, not code: the `TOGaDeskSupport.notifications` table holds one row per `(clientid, | desk/includes/classes/class.notification.php, crons/tickets.php, crons/tickets_prod.php |
 | [REST API (RPC-over-POST) & API-Key Auth](features/rest-api.md) | TOGa Desk exposes a programmatic API at `desk/api/`. | desk/api/index.php, desk/api/resources/tickets.php, desk/api/resources/assets.php, desk/api/resources/authenticate.php, desk/includes/classes/class.apikey.php, desk/includes/functions.php |
 | [SMB Contract Editing & the clientMspId Corruption Trap](features/smb-contract-editing.md) | The SMB contracts page (`/desk/?route=toga/smbcontracts&togaClientId=<id>`) edits `TOGA_*.SMBContracts` rows via a modal. | desk/template/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/edit.php |
 | [Ticket Lifecycle (class.ticket.php)](features/ticket-lifecycle.md) | All TOGa Desk ticket creation and reply handling funnels through `Ticket` in `desk/includes/classes/class.ticket.php`. | desk/includes/classes/class.ticket.php, desk/includes/controllers/actions.php, desk/includes/controllers/actions/tickets/addReply.php, desk/api/resources/tickets.php, desk/api/resources/ticket_replies.php, crons/tickets.php, crons/pipe.php, desk/includes/controllers/actions/tickets/merge.php |
+| [Reverting a TOGa Desk _production Deploy (revert-forward)](workflows/production-revert-forward.md) | How to cleanly and verifiably roll back a single ticket's changes from the togadesk `_production` branch. |  |
 | [Standalone PHP Test Script Bootstrap (TOGa Desk)](workflows/standalone-test-scripts.md) | How to write a standalone CLI PHP script that bootstraps the TOGa Desk framework for read-only testing of desk classes (e.g. |  |

package/knowledge/1.0/apps/togadesk/features/email-to-ticket-intake.md

@@ -6,13 +6,14 @@ project: TOGa Desk
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-27
 owners: ["jcardinal", "dfranks", "mhammontree"]
 files:
   - crons/tickets.php
   - crons/tickets_prod.php
   - crons/pipe.php
   - desk/includes/classes/class.ticket.php
+  - vendor/classes/class.imap.php
 related:
   - 1.0/apps/togadesk/architecture.md
   - 1.0/apps/togadesk/features/ticket-lifecycle.md
@@ -84,6 +85,17 @@ config framework**: noise filtering is ad-hoc inline guards in the crons (the ha
   (`E_ALL` + `App_Error::handleError`), so an intake cron could **halt**. Hardened to
   `return $matches[0] ?? '';` (TRUE-79975) — important because `isSuppressedNoiseEmail` routes
   nullable/malformed sender input through `extractEmail`, putting this latent bug on the hot path.
+- **`class.imap.php` duplicate trap — the OPPOSITE direction from `class.ticket.php`.** Two
+  copies of `class.imap.php` exist with different contents: root-level
+  `vendor/classes/class.imap.php` and `desk/vendor/classes/class.imap.php`. For the
+  email-intake path the **root-level `vendor/classes/class.imap.php` is the LIVE file** — the
+  one the intake cron uses and the one PR edits/reverts must target (confirmed: TRUE-80116's
+  attachment MIME-walker rewrite, and its revert, both touched `vendor/classes/class.imap.php`;
+  the `desk/vendor/...` copy has a different blob and was never touched). This is the reverse of
+  the `class.ticket.php` rule (where `desk/includes/classes/` is live and the repo-root copy is
+  dead). Verifying the wrong copy gives a false "byte-identical across commits" result because
+  the untouched copy trivially matches. Prior guidance naming `desk/vendor/classes/class.imap.php`
+  as live is wrong for intake.
 - Attachments are deleted locally immediately after the S3 upload with **no retry** if S3 fails.
 - **`adminid` clobber on reply routing:** after `emailToTicket()` sets `$data['adminid']` from
   the FROM address (~line 1407), an asset lookup (~line 1437-1442) overwrites it with the
@@ -93,6 +105,9 @@ config framework**: noise filtering is ad-hoc inline guards in the crons (the ha
   classification. See the ticket-lifecycle doc.
 
 ## Change history
+- 2026-07-27 — corrected the live IMAP-class location: root-level `vendor/classes/class.imap.php`
+  is the file the intake cron uses (NOT `desk/vendor/classes/class.imap.php`), the opposite of the
+  `class.ticket.php` duplicate rule; added it to `files:` (dfranks)
 - 2026-07-09 — added `Ticket::isSuppressedNoiseEmail()` noise suppression (no-reply sender + "Staples PO"
   subject) wired into both feeders before ticket creation; hardened `extractEmail()` no-match to
   `''`; documented the `tickets_defaultdepartment` → "Support Desk" catch-all fall-through

package/knowledge/1.0/apps/togadesk/workflows/production-revert-forward.md

@@ -0,0 +1,67 @@
+---
+title: Reverting a TOGa Desk _production Deploy (revert-forward)
+framework: "1.0"
+repo: togadesk
+project: TOGa Desk
+client: shared
+type: workflow
+status: active
+updated: 2026-07-27
+owners: ["dfranks"]
+files: []
+related:
+  - 1.0/apps/togadesk/architecture.md
+  - 1.0/apps/togadesk/features/email-to-ticket-intake.md
+---
+
+## Summary
+How to cleanly and verifiably roll back a single ticket's changes from the togadesk
+`_production` branch. Deploys land on `_production` as **two-parent merge commits**, so a
+rollback is a `git revert -m 1` of the merge — and when later tickets have since touched the
+same file, the correct rollback is a per-hunk revert (not a whole-file restore), verified with
+`git patch-id`.
+
+## The deploy model
+Changes reach `_production` as merge commits in one of two shapes:
+- PR merge commit — `Merge pull request #NNN from agilantsolutions/TRUE-XXXX`
+- Automated merge — `Merged from TRUE-XXXX to _production (automated)`
+
+Both have two parents: parent 1 is the prior `_production` tip, parent 2 is the ticket branch.
+
+## Steps
+1. Identify the merge commit SHA for the ticket to roll back (`git log --merges` /
+   `--grep=TRUE-XXXX`).
+2. Revert it keeping the `_production` mainline:
+   ```
+   git revert -m 1 <merge-sha>
+   ```
+   `-m 1` keeps first parent (`_production`) and undoes the branch's changes. Git reverses only
+   that ticket's hunks and auto-merges around any commits that landed later.
+3. **Do not** do a whole-file restore (e.g. `git checkout <old-sha> -- path`) when a later
+   ticket has since modified the same file — that would also wipe the later ticket's work.
+
+## Verifying the revert is exact
+- **File untouched by any later ticket:** whole-file blob/byte equality vs. the pre-ticket
+  version is a valid check.
+- **File changed by later tickets:** blob equality is meaningless (line offsets shifted). Prove
+  the revert is the precise inverse of the original change with `git patch-id`:
+  ```
+  # inverse of the original merge's diff for the file
+  git show <merge-sha> -- <file> | ...invert... | git patch-id --stable
+  # our revert's diff for the file
+  git show <revert-sha> -- <file> | git patch-id --stable
+  ```
+  Equal patch-ids prove the revert change is the exact inverse of the original regardless of
+  line-offset shifts from intervening commits.
+
+## Gotchas
+- Confirm you are targeting the **live** copy of any duplicated file before verifying — e.g.
+  the email-intake IMAP class is root-level `vendor/classes/class.imap.php`, while the live
+  ticket class is `desk/includes/classes/class.ticket.php` (opposite duplicate directions). A
+  verification against the wrong (untouched) duplicate falsely reports "identical". See the
+  email-to-ticket-intake feature doc.
+- `_production` is the deploy target for togadesk (not `_main`).
+
+## Change history
+- 2026-07-27 — documented the revert-forward rollback + `git patch-id` precision check for the
+  togadesk merge-commit deploy model (dfranks)

package/knowledge/INDEX.md

@@ -7,7 +7,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **library** (Library) _(framework core)_ — 14 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 15 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
-- **togadesk** (TOGa Desk) — 9 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
+- **togadesk** (TOGa Desk) — 10 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)

package/package.json

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