docs(maestro-flow): retire the dynamic-entity FilterBuilder workaround, document the silent-drop hazard

[jiyangzh]

Why

The dynamic-entity FilterBuilder limitation this skill documented no longer exists. cli#2924 (commit 0273928c8, merged 2026-07-29, DAP integration ENGCE-59465) removed the --detail.filter rejection. The skill still routed agents onto the retired workaround — hand-Edit inputs.detail on a CLI-owned node, injecting both filter halves by hand. That path is now unnecessary and dangerous: it is a re-configure hazard and it bypasses the compiler. It cost two nightly failures (2026-08-11 and 2026-08-12 — hand-written CEQL grammar defects on a path the compiler should own).

Live-proven end to end (2026-08-12, uip 1.201.0): a filter tree with a dynamic operand ({"value": "=js:$vars.start.output.invoiceNumber", "isLiteral": false}) on Data Service entity BillingDisputeERP compiles all three halves —

queryExpression:  "invoiceNumber = '{var_bc8545cc}'"
filterVariables:  { "var_bc8545cc": "=js:$vars.start.output.invoiceNumber" }
savedFilterTrees: real tree (not the empty husk)

— validates clean, and flow debug completes with the entity's 8 known rows for the test invoice. Requirement: pathParameters.entityName set in the same node configure call (it drives the automatic schema fetch).

The successor hazard, now documented

A tree leaf whose field id does not match the entity schema is dropped silently — matching is case-sensitive (InvoiceNumber vs invoiceNumber). node configure reports Success and writes queryExpression: "" (single bad leaf → filter gone → the query returns all records) or a dangling … AND (mixed leaves → runtime fault). No CLI guard exists yet; a fix is planned (guard on the compiled output).

Changes

• connector/impl.md Step 6a: deleted the CLI-limitation paragraph, the "only sanctioned Edit" blockquote, and the 4-step workaround. Replaced with the current contract — pass --detail.filter, always set the entity name, match field ids exactly (schema via uip df entities list → uip df entities get).
• connector/impl.md Common Errors: new row for the silent-drop hazard.
• connector-trigger/impl.md: the error row citing the removed message and Debug Tip 8 claimed a configure-time guard that no longer runs — rewritten for the trigger case (unmatched leaf drops from the compiled filterExpression; the trigger fires on events the filter should exclude).
• Two adjacent claims that the CLI "validates" a filter against IS metadata corrected to "compiles".

"Hand-authored CEQL strings" section and anchor unchanged — the whole-value =js: path remains sanctioned (MST-13005). No SKILL.md frontmatter change.

[github-actions]

Claude finished @jiyangzh's task in 2m 21s —— View job

---

PR Review: docs(maestro-flow) — retire FilterBuilder workaround

• Read review criteria (.github/code_review.md)
• Read full diff (git diff origin/main...HEAD)
• Read changed files in full context
• Check relative links, cross-skill refs, secrets
• Post review findings

---

Summary

Retires a now-unnecessary (and dangerous) hand-Edit workaround for dynamic-entity FilterBuilder on Data Service connectors, replacing it with the current --detail.filter contract. Documents a new silent-drop hazard where the CLI drops filter-tree leaves with unmatched field ids without error. Changes span two files: the connector and connector-trigger implementation references.

Change-by-Change Review

1. skills/uipath-maestro-flow/references/author/references/plugins/connector/impl.md

Severity: OK

The 14-line removal (the CLI-limitation paragraph, the "sanctioned Edit" blockquote, and the 4-step workaround) is clean — no stale references to the old workaround remain anywhere in the skill (CLI-limitation, sanctioned.*Edit, re-configure hazard all grep-clean). The replacement paragraph at line 246 is well-structured: states the current contract, explains the pathParameters.entityName requirement, documents the case-sensitivity hazard, and routes to Common Errors.

Specific notes:

• Line 252: "compiles the CEQL for you" correctly replaces the old "validates it against IS metadata" — accurate and consistent with the PR description's "validates → compiles" correction.
• Line 721: New Common Errors row for the silent-drop hazard is thorough — covers both failure modes (empty query string from single bad leaf, dangling AND from mixed leaves) and gives the exact diagnostic steps.
• Line 722: Existing [102003] error row updated — "builds the expression for you" replaces "validates the expression" — consistent with the terminology change.
• All internal anchor links (#hand-authored-ceql-strings, #common-errors) resolve correctly within the file.

2. skills/uipath-maestro-flow/references/author/references/plugins/connector-trigger/impl.md

Severity: OK

Two targeted edits:

• Line 497 (Common Errors table): Old error row referenced a configure-time rejection message (Filter references field '<name>' which is not present in trigger metadata) that no longer fires. Replaced with the new runtime symptom — trigger fires on events the filter should exclude. The cause/fix columns are accurate: documents the silent drop, prescribes comparing leaf ids against filterFields.fields[].name, and notes case-sensitivity.
• Line 514 (Debug Tip 8): Updated from "The CLI rejects trees that reference unknown fields" to "The CLI no longer rejects … it drops that leaf." Clear contrast with the old behavior, and the consequence ("surfaces as a trigger that fires on events the filter should exclude, not as an error") gives agents a diagnosable symptom.

Both changes are internally consistent — the error table and the debug tip tell the same story without contradiction.

What's Missing

Nothing identified. The PR is tightly scoped to the two files where the workaround and the outdated guard were documented. Existing test tasks (connector_features/ceql_where.yaml, connector_trigger/trigger_with_filter.yaml) cover filter-tree behavior and are not invalidated by these documentation changes. No new CLI workflows were introduced that would warrant new tests. The SKILL.md frontmatter is unchanged. No cross-skill references were introduced. No secrets or personal paths in the diff.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Unchanged
E2E Tests	OK	Existing filter tests (ceql_where.yaml, trigger_with_filter.yaml) still cover the behavior
Skill Body	OK	SKILL.md unchanged
References & Assets	OK	Both changed files are internally consistent; all links resolve
Repo Hygiene	OK	No secrets, no cross-skill deps, changes scoped to the affected skill

Issues for Manual Review

• Silent-drop hazard accuracy: The PR documents that the CLI silently drops unmatched filter-tree leaves (producing queryExpression: "" or a dangling AND). This behavior was live-verified on uip 1.201.0 per the PR description. A reviewer familiar with the CLI internals should confirm this matches the current node configure semantics and that the documented diagnostic path (uip df entities list → uip df entities get) is the right way to surface the field mismatch.

Conclusion

Clean, well-scoped documentation correction that removes a dangerous workaround and replaces it with accurate guidance for the current CLI behavior. The silent-drop hazard is documented consistently across both connector and connector-trigger references (error tables and debug tips). No issues found — recommend approve.

---