docs(uipath-maestro-flow): decompile omits a version pin the SDK does not bundle

[tmatup]

Do not merge before UiPath/builder-sdk#1159 merges. This doc describes that PR's behaviour.

Summary

Short version: references/brownfield.md says decompile keeps a version pin the SDK does not bundle, so compile refuses it until you drop the { version }. UiPath/builder-sdk#1159 changes that. Decompile now omits such a pin and warns, the node compiles at the SDK's default, and merge --baseline keeps the untouched node at the file's version with the file's definition. This PR resyncs the paragraph.

Example: uip maestro flow node add writes uipath.human-in-the-loop.quick-form@1.6, and the SDK bundles 1.0 and 1.1.

before: .step("review1", hitl({...}), { version: "1.6" })   -> compile: "... resolves only ...quick-form@1.0"
after:  .step("review1", hitl({...}))                        -> compiles; merged node stays at 1.6

What changed

• skills/uipath-maestro-flow/references/brownfield.md, decompile warnings list:
  • The unbundled-pin bullet now covers any type the SDK bundles at some version, not only core.*.
  • It says the pin is omitted, that an untouched node keeps its version through merge --baseline, and that an edited node moves to the SDK's version.
  • --strict now turns each of the three warnings into an error.
• The text is synced from website/reference/brownfield.md on the SDK branch.

Tests

• pytest tests/tasks/uipath-maestro-flow/_shared: 1410 passed.
• node scripts/check-skill-links.mjs: all links resolve.
• python3 scripts/check-skill-verbs.py --json skills/uipath-maestro-flow: 0 blocking findings.

🤖 Generated with Claude Code
Co-Authored-By: Claude

[github-actions]

Claude finished @tmatup's task in 1m 26s —— View job

---

PR Review: docs(uipath-maestro-flow) — decompile unbundled version pin

• Read review criteria and project conventions
• Read PR diff and full changed file
• Check links, cross-skill refs, secrets
• Post review

---

Summary

Updates one bullet in references/brownfield.md's decompile-warnings list to reflect new SDK behavior (UiPath/builder-sdk#1159): decompile now omits unbundled version pins instead of keeping them, broadens the scope from core.* to any type the SDK bundles at some version, and documents the merge --baseline preservation semantics. Also corrects --strict to cover all three warnings equally.

Change-by-Change Review

1. skills/uipath-maestro-flow/references/brownfield.md — decompile warnings rewrite

Severity: OK

The diff is clean and well-scoped:

• Line 111: --strict scope change from "first and third" → "each of them" — simpler and now correct per the SDK change. Good.
• Lines 119–126: Replacement of the old core.*-only unbundled-pin bullet. The new text:
  • Broadens scope correctly (any type the SDK bundles at some version, not just core.*).
  • Gives a concrete example (uipath.human-in-the-loop.quick-form@1.6 vs SDK's 1.0/1.1) — helpful for agents.
  • Explains the three outcomes clearly: source omits { version } → node compiles at SDK default; merge --baseline keeps untouched nodes at file's version; edited nodes move to SDK's version.
  • Carves out the types the SDK bundles at no version (connectors, published processes/agents) — these keep their pin. Clear and necessary distinction.
  • Prose follows the repo's terse style (no filler, prescriptive, front-loaded facts).
  • No cross-skill references, no secrets, no broken links.

No issues found in the changed content.

What's Missing

Nothing identified. The PR is a narrow doc sync for a single reference file — no new skill, no new CLI workflow, no structural changes.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Unchanged; still valid
E2E Tests	OK	No new capabilities introduced — existing tests in tests/tasks/uipath-maestro-flow/ cover brownfield workflows
Skill Body	OK	SKILL.md unchanged
References & Assets	OK	Scoped rewrite; no broken links; no orphaned files
Repo Hygiene	OK	No secrets, no cross-skill deps, single-file change matches commit scope

Issues for Manual Review

• Upstream dependency: PR description states this should not merge before UiPath/builder-sdk#1159. Verify that SDK PR is merged before landing this, otherwise the doc will describe behavior users can't reproduce.
• Domain accuracy: The three-way split (omit pin for bundled-at-other-versions types / keep pin for zero-version types / merge --baseline preservation) matches the SDK PR description, but the exact semantics should be confirmed against the SDK implementation.

Conclusion

Clean, well-scoped docs-only change. No issues found. Approve once the upstream SDK PR (UiPath/builder-sdk#1159) has merged.

---

[tmatup]

Rebased onto main (8f43abf). Conflict was in references/brownfield.md: #3858 had rewritten the same bullet to add the NODE_VERSION_UNREGISTERED check code. Resolution keeps this PR's text (decompile omits the unbundled pin) and adds one line from #3858: a pin written back by hand is still refused by check as NODE_VERSION_UNREGISTERED. That code still exists on builder-sdk#1159 (check.ts), so the line stays true after it merges.

🤖 Generated with Claude Code
Co-Authored-By: Claude

[rockymadden]

🟡 Commented: the paragraph matches builder-sdk#1159, but it leaves the agent without an action for the one case that hurts (editing such a node), and the check claim is wrong for its own example.

What

• Resyncs the decompile-warning bullet in references/brownfield.md with builder-sdk#1159: an unbundled { version } pin is now omitted, not kept, and --strict refuses it.
• Example and behaviour confirmed against #1159's decompile.ts verClause and serialize.ts refusal text.

Overall findings

• None.

Notes (not findings)

• #1159 is still open. Merging this first documents behaviour main does not have. The PR body already says so.
• Flavor check: skill-flavors/studioweb/uipath-maestro-flow has no brownfield.md and no override of this text. No drift.

tl;dr

• Accurate sync, one major: say what to do when the edit target is a node whose pin got dropped, or the agent silently downgrades it.
• One minor: check does not report this for quick-form.

[rockymadden]

🟢 Approved: both earlier findings are fixed at c807a52d7. No new findings.

What

• brownfield.md: decompile drops a version pin the SDK doesn't bundle for a type it bundles at other versions. The doc now covers what merge --baseline keeps and what to do when that node is the edit target.

Earlier findings

• ✅ Fixed, major: the edit-target case now has an action ("edit that node's JSON in the .flow directly, or tell the user the edit moves it…").
• ✅ Fixed, minor: NODE_VERSION_UNREGISTERED is now limited to "a registered family", and compile is named as the gate for quick-form.

Notes (untagged)

• The intro ("--strict turns each into an error") now matches skills#3899's rebased text. Both PRs edit the same block, so the second to merge gets a trivial conflict.
• builder-sdk#1159 is still open. Merge after the SDK release that ships it.
• No flavor drift: studioweb has no brownfield.md.

tl;dr
Both findings are fixed and the doc matches #1159. Land it after that SDK release.

[tmatup]

CI after the review push: two red checks, neither from this doc change.

1. "Build and inspect every skill package" fails on main too: fix(uipath-maestro-bpmn): pick the connector object whose parameters fit the task #3497 renamed a heading in skills/uipath-maestro-bpmn/references/registry-workflow.md and left two SKILL.md links on the old anchor, which the link check enforces. Fix in fix(uipath-maestro-bpmn): point SKILL.md at the renamed "Picking the object" heading #3926 (green there). Every PR is red on this job until it lands.
2. "Run skill smoke tests": 25/28 (89.3%, gate 95%). datafabric-smoke-update is the same Pre-run command timed out after 60s: python3 _setup/ensure_entity.py setup error (iterations=0) as earlier rounds; hitl-smoke-completed-port and voice-inbound-call timed out. This PR edits only references/brownfield.md.

🤖 Generated with Claude Code
Co-Authored-By: Claude