toga-ai 1.0.458 → 1.0.460

package/knowledge/1.0/apps/library/features/elite-freshservice-sync.md

@@ -6,13 +6,14 @@ project: Library
 client: elite
 type: client-feature
 status: active
-updated: 2026-07-10
+updated: 2026-07-28
 owners: ["snaredla"]
 files:
   - library/app/api/toga2.php
 related:
   - clients/elite/profile.md
   - 2.0/apps/worker2/features/elite-freshservice-sync.md
+  - 1.0/apps/worker/features/elite-togadesk-attachment-sync.md
 ---
 
 ## Summary
@@ -135,6 +136,12 @@ Direction: **TOGA 2 → TOGaDesk**
    - Write to disk: `/var/www/html/ontrack/desk/uploads/{fileId}-{name}`
    - `UPDATE files SET file='{fileId}-{name}', filetype=?, filesize=? WHERE id=?`
 
+⚠ **`data.files.data` is null for Freshservice-originated files.** Files that entered
+TOGA 2 via the inbound Freshservice sync store their binary in S3 and expose a `sourceUrl`
+(presigned URL) instead of a base64 `data` field. This method silently skips those files.
+For Elite, a separate standalone cron handles them:
+→ see [`1.0/apps/worker/features/elite-togadesk-attachment-sync.md`](../../../1.0/apps/worker/features/elite-togadesk-attachment-sync.md)
+
 ### `syncTogadesk1NoteFilesIntoToga2(int $togadeskReplyId, string $ticketNoteUuid)`
 Direction: **TOGaDesk → TOGA 2**
 
@@ -211,3 +218,4 @@ The Elite team lookup block inside `syncTogaDesk1TicketIntoToga2Ticket` must use
 ## Change history
 - 2026-06-10 — Documented `App_Api_Toga2::syncWithTogadesk` orchestration (bidirectional TOGA 2 ↔ TOGaDesk ticket/note/file sync, watermarks, `ticketNoteFiles` gotcha). (snaredla)
 - 2026-07-10 — Added Elite-specific section: department reverse-lookup via `c_togadeskDepartmentId`, timestamp guard, reply status badge mapping fix (`case 2` → Open), variable pollution gotcha. (snaredla)
+- 2026-07-28 — Added gotcha to `syncToga2NoteFilesIntoTogadesk1`: `data.files.data` is null for Freshservice-originated files (sourceUrl approach handled by standalone cron). Added cross-link to `elite-togadesk-attachment-sync.md`. (snaredla)

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

@@ -5,6 +5,7 @@
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
 | [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
 | [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php |
+| [Elite TOGA 2.0 → TOGaDeskSupport Standalone Attachment Sync](features/elite-togadesk-attachment-sync.md) | `sync_togadesk_elite_attachments.php` is a standalone cron (every 5 minutes) that syncs file attachments from TOGA 2.0 into TOGaDeskSupport for Elite. | worker/crons/toga2/elite/sync_togadesk_elite_attachments.php, worker/crons/toga2/elite/test_sync_togadesk_elite_attachments.php |
 | [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/checker.php, worker2/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/reconcile_drift_2023plus.php, test/@dave/probe_invoice_gap_2026.php, test/@dave/probe_creditmemo_gap_detail.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
 | [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, library/app/api/netsuite/rest.php, library/app/systemmonitor/netsuiteintegration.php |
 | [OneUptime external uptime monitoring for 1.0 workers](features/oneuptime-worker-uptime-monitoring.md) | Every 1.0 worker box self-reports its liveness to an external OneUptime monitor once per minute by curl-POSTing to a per-worker "Incoming Request" heartbeat URL | library/app/worker.php, worker/crons/worker/worker_heartbeat.php |

package/knowledge/1.0/apps/worker/features/elite-togadesk-attachment-sync.md

@@ -0,0 +1,143 @@
+---
+title: Elite TOGA 2.0 → TOGaDeskSupport Standalone Attachment Sync
+framework: "1.0"
+repo: worker
+project: Worker
+client: elite
+type: client-feature
+status: active
+updated: 2026-07-28
+owners: ["snaredla"]
+files:
+  - worker/crons/toga2/elite/sync_togadesk_elite_attachments.php
+  - worker/crons/toga2/elite/test_sync_togadesk_elite_attachments.php
+related:
+  - clients/elite/profile.md
+  - 1.0/apps/library/features/elite-freshservice-sync.md
+  - 2.0/apps/worker2/features/elite-freshservice-sync.md
+---
+
+## Summary
+
+`sync_togadesk_elite_attachments.php` is a standalone cron (every 5 minutes) that syncs
+file attachments from TOGA 2.0 into TOGaDeskSupport for Elite. It supplements — but does
+not replace — the `syncWithTogadesk()` orchestration in `library/app/api/toga2.php`.
+
+**Why this exists**: `syncWithTogadesk()` has a built-in helper `syncToga2NoteFilesIntoTogadesk1()`
+that reads `data.files.data` (base64-encoded file content) from the TOGA 2.0 `/files/{uuid}`
+endpoint. For files that originated in Freshservice, this field is `null` — the file binary
+lives in S3 and is accessed via `sourceUrl` (a presigned URL). This standalone cron handles
+that path: it downloads from `sourceUrl` directly via cURL and writes the binary to disk.
+
+## Key files / entry points
+
+| File | Purpose |
+|------|---------|
+| `worker/crons/toga2/elite/sync_togadesk_elite_attachments.php` | Production cron — runs every 5 min |
+| `worker/crons/toga2/elite/test_sync_togadesk_elite_attachments.php` | 7-section test script |
+| `worker/crons/toga2/elite/sync_togasupply_elite.php` | Prerequisite — must run first (creates tickets + tickets_replies rows) |
+
+## How it works
+
+1. Query TOGaDeskSupport for recently active Elite tickets that have a `referenceId` (TOGA2 UUID):
+   ```sql
+   SELECT DISTINCT t.id AS deskTicketId, t.referenceId AS toga2Uuid
+   FROM tickets t
+   INNER JOIN tickets_replies tr ON tr.ticketid = t.id
+   WHERE t.clientid = 163
+     AND t.referenceId IS NOT NULL
+     AND tr.timestamp >= '<7 days ago>'
+   LIMIT 200
+   ```
+
+2. For each ticket: `GET /tickets/{toga2Uuid}?depth=3` to fetch the ticket with embedded notes and `ticketNoteFiles`.
+
+3. Walk every `isExternal = true` note that has `ticketNoteFiles`.
+
+4. Match each note to the TOGaDeskSupport `tickets_replies` row via `referenceid = note.uuid` (the dedup join key set by `syncWithTogadesk()`).
+
+5. For each `ticketNoteFile` (JOIN record), resolve the actual file UUID:
+   - `GET /ticket-note-files/{tnfUuid}` → `data.ticketNoteFiles.file.uuid`
+   - **Note**: `ticketNoteFiles[].uuid` in a depth-3 ticket is the JOIN RECORD uuid, not the file uuid. Must call `/ticket-note-files/{tnfUuid}` to get the real file object.
+
+6. Dedup: `SELECT id FROM files WHERE ticketreplyid = $replyId AND name = '$fileName'` — skip if already saved.
+
+7. Get download URL: `GET /files/{fileUuid}` → `data.files.sourceUrl` (Freshservice S3 presigned URL stored at inbound sync time).
+
+8. Download binary via cURL, write to `TOGADESK_UPLOADS_DIR` with a `{timestamp}_{filename}` prefix.
+
+9. `INSERT INTO files SET clientid=163, ticketreplyid=$replyId, name='...', file='...', projectid=0, assetid=0`.
+
+## Key constants
+
+```php
+const TOGADESK_ELITE_CLIENT_ID = 163;
+const TOGADESK_UPLOADS_DIR     = '/var/www/html/ontrack/desk/uploads/';
+const SYNC_LOOKBACK_DAYS       = 7;
+const TOGA2_TICKET_DEPTH       = 3;
+```
+
+## Data model
+
+TOGaDeskSupport tables touched:
+
+| Table | Columns read | Columns written |
+|-------|-------------|-----------------|
+| `tickets` | `id`, `referenceId`, `clientid` | — |
+| `tickets_replies` | `id`, `ticketid`, `referenceid` | — |
+| `files` | `id` (dedup check) | `clientid`, `ticketreplyid`, `name`, `file`, `projectid`, `assetid` |
+
+TOGA 2.0 API calls:
+- `GET /tickets/{uuid}?depth=3` → `data.tickets.ticketNotes[].ticketNoteFiles[]`
+- `GET /ticket-note-files/{tnfUuid}` → `data.ticketNoteFiles.file.{uuid,name}`
+- `GET /files/{fileUuid}` → `data.files.{uuid,name,size,sourceUrl}`
+
+## Dedup mechanism
+
+Two layers:
+1. **DB dedup**: `SELECT id FROM files WHERE ticketreplyid = ? AND name = ?` — skips files already saved for that reply.
+2. **URL dedup**: If `sourceUrl` is empty or expired (S3 presigned URLs have a TTL), the download is skipped with an `error_log` entry and the run continues.
+
+## Test script
+
+`test_sync_togadesk_elite_attachments.php` — run on the worker EC2:
+
+```bash
+# Read-only state check:
+php test_sync_togadesk_elite_attachments.php
+
+# Run sync then verify:
+php test_sync_togadesk_elite_attachments.php --sync
+```
+
+Sections:
+1. TOGA 2.0 note/file counts (confirms ticketNoteFiles exist)
+2. TOGaDeskSupport replies exist for test tickets (prereq check)
+3. Pre-sync file count (baseline)
+4. Run `sync_togadesk_elite_attachments.php` via `exec()`
+5. Post-sync file count reconciliation (`TOGaDeskSupport >= TOGA2`)
+6. Spot-check: `referenceid` set on replies, files on disk
+7. Dedup check: second run adds 0 files
+
+**Test ticket IDs** (safe sandbox tickets):
+
+| Label | Freshservice id | TOGaDeskSupport `tickets.id` | TOGA2 uuid |
+|-------|----------------|------------------------------|------------|
+| INC-65 | 65 | **213254** | `f4fac245-8bb2-8df4-dc1a-34dd28b67dc6` |
+| INC-66 | 66 | **213267** | `550df55f-32c2-1fbb-4a59-e21c86588e93` |
+
+The `tickets.id` values (213254/213267) are TOGaDeskSupport auto-increment IDs.
+They are **not** the TOGA2 integer ticket IDs (33/34) — using those returns 0 rows.
+
+## Gotchas / known issues
+
+**sourceUrl expiry**: S3 presigned URLs expire. For recently synced Freshservice files the URL stored in TOGA2 is still valid. For files synced weeks ago the URL may have expired — the script logs and skips those rather than failing.
+
+**Depends on `sync_togasupply_elite.php` running first**: The `tickets_replies.referenceid` join key is set by `syncWithTogadesk()`. If that cron is delayed, this script finds no matching reply rows and silently skips those notes.
+
+**`ticketNoteFiles[].uuid` is the JOIN RECORD uuid, not the file uuid**: Calling `GET /files/{tnfUuid}` returns 404. Must call `GET /ticket-note-files/{tnfUuid}` first to resolve to `data.ticketNoteFiles.file.uuid`.
+
+**depth=3 ticket fetch**: `ticketNoteFiles` are embedded at depth=3. Depth=1 or depth=2 returns the notes but not the file links.
+
+## Change history
+- 2026-07-28 — Created `sync_togadesk_elite_attachments.php` and test script. `sourceUrl` approach required because `data.files.data` is null for Freshservice-originated files. (snaredla)

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **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)
+- **worker** (Worker) — 16 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) — 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.458",
+  "version": "1.0.460",
   "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

@@ -1,5 +1,53 @@
 # Git Workflow Rules
 
+> **These rules apply to every layer of development** — front-end, back-end, Talos, database,
+> infrastructure, schema changes, everything. There is no layer that is exempt.
+
+## 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
+   `/capture` skill's whole model is commit-and-push 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 a skill whose documented job is to publish — `/work-ticket`, `/ship`,
+`/land-and-deploy`, `/capture` — **is** explicit authorization, but only for the commits and
+pushes that skill describes. It does not authorize publishing anything else in the session.
+
+Force-pushing is never automatic in any repo, including the knowledge repo.
+
+## 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:
+
+- 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.
+
 ## Branch protection
 
 Never commit directly to `_main`. All changes go through feature branches and pull requests.