toga-ai 1.0.134 → 1.0.135

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-17
+updated: 2026-06-18
 owners: ["dfranks"]
 files:
   - worker2/Worker/Netsuite.php
@@ -90,7 +90,15 @@ second, independently-gated concern in the same handler.
 
 1. `findClickupTaskByOpportunityNumber($tranId)` — GET the list filtered by the `Opportunity #`
    custom field (`include_closed=true&include_archived=true&custom_fields=[{field_id,operator:'=',value}]`).
-2. **Match → `updateTask()`**: **diffs first, writes only what changed** (change-detection backstop,
+2. **Match → `updateTask()` — but ONLY when `UPDATE_CLICKUP === true`.** `const UPDATE_CLICKUP = false`
+   ([Opportunity.php](worker2/Worker/Netsuite/Opportunity.php)) is a **deliberate one-way guard, NOT a
+   temporary backstop to flip**: once a ClickUp opportunity task exists, ClickUp is the source of truth
+   for it, and a NetSuite edit must **not** clobber edits made on the ClickUp side. With the flag false
+   (its production value), a match returns `skipped update (update disabled)` and ClickUp is left
+   untouched — so the *designed, correct* behavior of a NetSuite edit to an opportunity that already has
+   a task is: **Forecast upserts, ClickUp unchanged.** Do not "enable updates" by flipping it. The
+   change-detection logic below only runs in the (currently-off) update path. When enabled, it:
+   **diffs first, writes only what changed** (change-detection backstop,
    since 2026-06-17). PUT name/description **only if** one differs; POST **only** the custom fields
    that differ (each to `/task/{id}/field/{fieldId}` — ClickUp has no bulk custom-field set). When
    nothing differs it writes nothing and returns `task unchanged`. This kills the no-op-write echo: a
@@ -204,6 +212,13 @@ None — platform-wide Forecast sync.
   (`https://webhook.togahub.com/netsuite`) with `debugWrap` off. Also flip the enqueuer deployment
   `Testing → Released` (Testing fires only for the deploying user). Full checklist in
   `DEPLOY_RUNBOOK.md` §6.
+- **ClickUp's `=` custom-field filter is substring/prefix, NOT strict equality.** `findClickupTaskByOpportunityNumber($tranId)`
+  filters the `Opportunity #` field with `operator:'='`, but for a short-text custom field ClickUp matches
+  loosely: a lookup for `74266` still returns a task whose value is `74266--` (confirmed live 2026-06-18).
+  So **appending** to the dedup value does NOT defeat the match — to force a dedup *miss* (e.g. to exercise
+  the create branch) you must change the **leading** content or clear the field entirely. Verified both ways
+  on opp 74266/internalId 7161054: `74266--` → matched (update branch, skipped); field removed → missed
+  (create branch, new task `868k2rfj8`).
 - **ClickUp dedup keys on the `Opportunity #` field, not a DB column.** We deliberately did NOT add
   a `clickupTaskId` column — the dedup lookup queries ClickUp itself by `Opportunity #` (= tranId).
   Consequences to know:
@@ -262,6 +277,16 @@ same **skip-if-unchanged** compare on the extracted values, and **actor-identity
 trigger a CU→NS write. The NS→CU change-detection above is the complementary backstop, not a substitute.
 
 ## Change history
+- 2026-06-18 — **Verified live in production** (no code change): real NetSuite SuiteScript webhooks
+  (`user-agent: NetSuite/2026.1`) arrive at `webhook.togahub.com/netsuite` and process successfully
+  (e.g. opp 6926224 PUT). Clarified that **`UPDATE_CLICKUP = false` is an intentional one-way guard**
+  (NS edits must not overwrite ClickUp-side edits), not a flag to flip — so "NS edit → Forecast upserts,
+  existing ClickUp task untouched" is the *designed* behavior. Documented that ClickUp's `=` custom-field
+  filter is **substring/prefix**, not exact (a `74266` lookup matched `74266--`); confirmed both dedup
+  branches on opp 74266/internalId 7161054. Testing note: the webhook needs the **internalId**, not the
+  opportunity number — resolve it via `Forecast.Opportunities.netsuiteOpportunityInternalId` for a given
+  `opportunityNumber` (tranId). Fire a manual test with
+  `curl -X POST https://webhook.togahub.com/netsuite -d '{"recordType":"opportunity","eventType":"edit","internalId":<id>}'`. (dfranks)
 - 2026-06-17 — ClickUp **change-detection backstop** added to `updateTask()`: diff before write, skip
   no-op syncs (`task unchanged`), PUT name/description only when changed, POST only changed custom
   fields. `findClickupTaskByOpportunityNumber()` now returns the full task object; added

package/package.json

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