fix(maestro-case): structured filter tree docs, reference-ID reuse warning (#426)

1. Structured filter tree (MST-8802 / Skills#304):
   - connector-trigger-common.md §7: replace flat JMESPath table with
     structured filter tree shape, operators (13 listed + SDK enum ref),
     examples (single, multi-AND, nested AND/OR)
   - essentialConfiguration: filter is now <filter-tree-or-null>
   - Input body: CLI auto-generates JMESPath from tree
   - What NOT to Do: "don't hand-write JMESPath" + "don't use filterExpression"
   - Dynamic =vars.X limitation documented

2. Reference-ID reuse warning (Skills#348):
   - connector-trigger-common.md + connector-activity/impl-json.md:
     "Never reuse reference IDs across connections"

3. connector-integration.md: add structured tree note to Filter Syntax section

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: song-zhao-25

skills/uipath-maestro-case/references/connector-integration.md

@@ -92,6 +92,8 @@ Input keys come from the `describe` response (Step 4): typically `body`, `queryP
 
 ## Filter Expression Syntax
 
+> **Note:** The direct JSON write path uses structured filter trees (see [connector-trigger-common.md §7](connector-trigger-common.md#7-build-input-values-and-filter)) instead of flat filter expressions. The CLI internally converts event parameters to a structured filter tree.
+
 Trigger `data.filter` (or `node.data.uipath.filter` for event triggers) uses the connector's filter DSL. Common patterns:
 
 | Pattern | Example |

skills/uipath-maestro-case/references/connector-trigger-common.md

@@ -82,14 +82,83 @@ If an SDD input matches an `eventParameters` field name, it's an event parameter
 {"parentFolderId": "AAMkADNm..."}
 ```
 
-**filter** — translate SDD filter criteria using `filterFields` from Step 3. Use JMESPath syntax. Supports `=vars.X` for runtime case variable references:
+**filter** — translate SDD filter criteria using `filterFields` from Step 3. Build a **structured filter tree** (NOT a flat JMESPath string). The CLI converts the tree to a JMESPath expression automatically.
 
-| Pattern | JMESPath |
+#### Filter tree shape
+
+```json
+{
+  "groupOperator": 0,
+  "index": 0,
+  "filters": [
+    {
+      "id": "<fieldName from filterFields>",
+      "operator": "<PascalCase operator>",
+      "value": { "value": "<literal>", "rawString": "\"<literal>\"", "isLiteral": true }
+    }
+  ],
+  "groups": []
+}
+```
+
+- `groupOperator`: `0` (And) or `1` (Or) — combines sibling filters and groups
+- `filters[]`: leaf conditions. `id` must be a field name from `filterFields` (Step 3)
+- `groups[]`: nested sub-trees for mixed AND/OR logic (empty for simple cases)
+
+#### Operators
+
+| Pattern | Operator |
 |---|---|
-| Exact match (static) | `(fieldName == 'value')` |
-| Exact match (dynamic variable) | `(fieldName == '=vars.variableName')` |
-| Substring match | `(contains(fieldName, 'value'))` |
-| Multiple conditions | `(fieldA == 'x' && fieldB == 'y')` |
+| Exact match | `"Equals"` |
+| Not equal | `"NotEquals"` |
+| Substring match | `"Contains"` |
+| Does not contain | `"NotContains"` |
+| Starts with | `"StartsWith"` |
+| Greater than | `"GreaterThan"` |
+| Less than | `"LessThan"` |
+| Is empty | `"IsEmpty"` |
+| Is not empty | `"IsNotEmpty"` |
+| One of (multi-value) | `"In"` |
+| Not one of | `"NotIn"` |
+| Is null | `"IsNull"` |
+| Is not null | `"IsNotNull"` |
+
+> See the IS SDK `FilterOperator` enum for the complete list (includes `Like`, `NotLike`, datetime operators, etc.).
+
+#### Examples
+
+Single filter (AND with one leaf):
+```json
+{ "groupOperator": 0, "index": 0, "filters": [
+    { "id": "subject", "operator": "Contains", "value": { "value": "urgent", "rawString": "\"urgent\"", "isLiteral": true } }
+], "groups": [] }
+```
+
+Multiple conditions (AND):
+```json
+{ "groupOperator": 0, "index": 0, "filters": [
+    { "id": "project", "operator": "Equals", "value": { "value": "PROJ", "rawString": "\"PROJ\"", "isLiteral": true } },
+    { "id": "issuetype", "operator": "Equals", "value": { "value": "Bug", "rawString": "\"Bug\"", "isLiteral": true } }
+], "groups": [] }
+```
+
+Nested AND/OR (e.g., "status is Open AND (priority > 3 OR assignee is null)"):
+```json
+{ "groupOperator": 0, "index": 0, "filters": [
+    { "id": "status", "operator": "Equals", "value": { "value": "Open", "rawString": "\"Open\"", "isLiteral": true } }
+], "groups": [
+    { "groupOperator": 1, "index": 1, "filters": [
+        { "id": "priority", "operator": "GreaterThan", "value": { "value": 3, "rawString": "\"3\"", "isLiteral": true } },
+        { "id": "assignee", "operator": "IsNull", "value": null }
+    ], "groups": [] }
+] }
+```
+
+No filter (trigger fires on all events): omit `filter` from the tasks.md entry entirely.
+
+#### Dynamic variable limitation
+
+The filter tree only supports `isLiteral: true` values. When a filter requires runtime case variable references (`=vars.X`), write the `body.filters.expression` JMESPath string directly and leave `essentialConfiguration.filter` as `null`. This is a known SDK limitation shared with flow-tool.
 
 Only use field names that appear in `filterFields`. If a filter cannot be translated unambiguously, **AskUserQuestion**.
 
@@ -183,16 +252,16 @@ Every context entry MUST include `"type": "string"` (or `"type": "json"` for met
 ### essentialConfiguration
 
 ```
-=jsonString:{"essentialConfiguration":{"instanceParameters":{"connectorKey":"<connector-key>","objectName":"<object-name>","activityType":"CuratedWaitFor","version":"<Config.version>","eventOperation":"<enrichment.operation>","eventMode":"<event-mode>","supportsStreaming":<Config.supportsStreaming>},"objectName":"<object-name>","packageVersion":"<Config.version>","connectorVersion":"<enrichment.connectorVersion>","executionType":null,"httpMethod":null,"path":null,"filter":null}}
+=jsonString:{"essentialConfiguration":{"instanceParameters":{"connectorKey":"<connector-key>","objectName":"<object-name>","activityType":"CuratedWaitFor","version":"<Config.version>","eventOperation":"<enrichment.operation>","eventMode":"<event-mode>","supportsStreaming":<Config.supportsStreaming>},"objectName":"<object-name>","packageVersion":"<Config.version>","connectorVersion":"<enrichment.connectorVersion>","executionType":null,"httpMethod":null,"path":null,"filter":<filter-tree-or-null>}}
 ```
 
 > **Critical:** `activityType` MUST be `"CuratedWaitFor"` — NOT `Config.activityType` (which is `"CuratedTrigger"`).
 
-> `filter` is always `null` in essentialConfiguration. The filter goes in `inputs[].body.filters.expression` only.
+> When a structured filter tree is provided (from §7), store it in `essentialConfiguration.filter` so Studio Web can round-trip the filter UI. The derived JMESPath expression goes in `inputs[].body.filters.expression`. When no filter is needed, `filter` stays `null`.
 
 ### Input body (from tasks.md values)
 
-If `input-values` has event parameters, convert to JMESPath + combine with `filter`:
+If `input-values` has event parameters, the CLI auto-generates the JMESPath expression from the structured filter tree. The body contains:
 
 ```json
 {
@@ -225,7 +294,9 @@ After writing root bindings, populate IS connection cache per [bindings-v2-sync.
 ## What NOT to Do (shared)
 
 - **Do NOT use `CuratedTrigger`** in essentialConfiguration. It MUST be `CuratedWaitFor`.
-- **Do NOT put filter in `essentialConfiguration.filter`.** It stays `null`. Filter goes in `body.filters.expression`.
+- **Do NOT hand-write JMESPath filter expressions.** Build a structured filter tree (§7); the CLI derives the expression automatically.
+- **Do NOT use `filterExpression` as a CLI input.** The CLI rejects raw `filterExpression` strings (MST-8802).
+- **Never reuse a reference ID from a prior case or session.** Reference IDs (mailbox folders, Slack channels, Jira projects) are scoped to the authenticated account behind each connection. Always resolve fresh via `uip is resources execute list` against the current `--connection-id`.
 - **Do NOT add `body.parameters`.** Only `body.filters.expression` + `body.queryParams`.
 - **Do NOT auto-inject `entryConditions`** (for tasks). Step 10 handles them.
 

skills/uipath-maestro-case/references/plugins/tasks/connector-activity/impl-json.md

@@ -280,6 +280,7 @@ All issues appended to the shared issue list per [logging/impl-json.md](../../lo
 - **Do NOT omit `file` input** when `enrichment.multipartParameters` has a file entry. Include it even when empty.
 - **Do NOT add `data.name`.** The FE does not use it for connector tasks.
 - **Do NOT auto-inject `entryConditions`.** Step 10 handles them — injecting here creates duplicates.
+- **Never reuse a reference ID from a prior case or session.** Reference IDs (e.g., Jira project keys, Slack channel IDs) are scoped to the authenticated account behind each connection. Always resolve fresh via `uip is resources execute list` against the current `--connection-id`.
 
 ## Known Limitation