feat(bpmn): derive package metadata with refresh

[DevMomo]

Summary

This layer makes uip maestro bpmn refresh <project-path> --output json the explicit boundary between authored BPMN source and generated package metadata:

author BPMN → validate source → refresh metadata → pack or operate

pack consumes refreshed files; it does not own their generation.

What refresh generates

File	Derived purpose
entry-points.json	Root manual-start entry points and their public input/output schemas
bindings_v2.json	Package resources, including supported V1 Integration Service Connection resources derived from authored root bindings
operate.json	Packaged BPMN main path, project identity, and content type
package-descriptor.json	BPMN and generated-file mappings included in the package

The supported source has exactly one project-root .bpmn file, one or more root processes, and at least one root manual start event overall. Every root manual start event must have exactly one valid GUID uipath:entryPointId; refresh emits one entry point for each.

Why

The skill previously referred only to an unspecified metadata-regeneration path. That left room to hand-author generated JSON, assume pack would create missing metadata, or operate on package files that no longer matched the BPMN.

This layer gives those four files one clear owner and one explicit regeneration command.

Failure and repeat-run behavior

Refresh validates the proposed four-file set before replacing files. Changed files are staged and replaced as one operation; if a later replacement fails, already changed files are restored and temporary files are removed.

Running refresh again without source changes is idempotent. A failure is treated as a BPMN or project precondition failure: fix the source, validate again, and rerun refresh rather than editing generated JSON.

Scope

Refresh is local, offline, and provider-neutral. It does not log in, discover or import tenant resources, choose a connection, invoke a connector operation, edit BPMN source, or upload/publish/deploy/debug/run the process. It derives only from identities already authored into the project.

Stack and dependencies

• Skills stack: #2371, directly above #2381. This layer updates the Integration Service guide introduced there, while the refresh workflow applies to any supported BPMN project.
• UiPath/cli#3331 provides the atomic, idempotent four-file refresh command.
• UiPath/cli#3356 extends refresh to derive supported V1 Integration Service Connection resources in bindings_v2.json.

Verification

• Current-head smoke suite: 12/12 passed; 100% pass rate.
• Focused BPMN contract suite: 9/9
  • 3 metadata-refresh tests;
  • 3 project-scaffold tests;
  • 2 public-I/O tests;
  • 1 ScriptTask test.
• The metadata guard checks validation-before-refresh ordering, all four generated files, provider-neutral scope, refresh-before-pack ordering, generated-file ownership, idempotence, atomic failure behavior, and the actual multi-process/multi-entry-point CLI contract.
• CLI-verb audit: no blocking or uncertain findings.
• Workflow YAML parsing and git diff --check: passed.

[github-actions]

Claude finished @DevMomo's task in 2m 41s —— View job

---

PR Review: feat(bpmn): derive package metadata with refresh

• Read review criteria and project conventions
• Analyze PR diff against base branch
• Read full changed files for context
• Check skill structure and cross-skill rules
• Verify links, tests, and CODEOWNERS
• Post review findings

---

Summary

This PR introduces uip maestro bpmn refresh <project-path> --output json as the explicit, atomic boundary between authored BPMN source and four derived package files (entry-points.json, bindings_v2.json, operate.json, package-descriptor.json). It updates the SKILL.md workflow from 4 to 5 steps, revises all downstream references (metadata guide, project layout, ship, operate capability, IS activity guide) to delegate generation to refresh instead of pack, and adds a 3-test contract guard with a matching CI job.

Change-by-Change Review

1. skills/uipath-maestro-bpmn/SKILL.md — step 5 addition

Severity: OK

The new step 5 slots cleanly after validation (step 4) and before operate. The command block uses the correct --output json convention. Scope constraints (offline, provider-neutral, not a substitute for uip solution resources refresh) are explicit. Failure handling and the CLI-unavailable fallback are clearly stated. The "Work the five steps" count is updated at line 76.

One observation: the step 5 prose in SKILL.md overlaps substantially with the metadata guide's introductory paragraph and safe-workflow section — both describe the command as "authoritative local source-to-derived-state boundary," both list "offline and provider-neutral," both describe the four generated files, atomic writes, idempotence, and the CLI-unavailable fallback. This is a deliberate choice for SKILL.md (the entry point an agent loads first), and the metadata guide is loaded on demand. Given that SKILL.md is the top-level contract agents see first and the guide is a deep reference, this duplication is borderline acceptable but worth noting for future drift risk.

2. skills/uipath-maestro-bpmn/references/shared/local-metadata-regeneration-guide.md

Severity: OK

The most substantively changed file. Key improvements:

• New introductory paragraph establishing refresh as the authoritative boundary.
• Safe workflow reordered: validate → refresh → verify → pack (previously: validate → verify → pack).
• Explicit CLI contract requirements (one .bpmn, ≥1 root process, ≥1 root manual start event, GUID uipath:entryPointId).
• Atomic failure semantics documented.
• "Root start event" consistently qualified as "root manual start event."
• Drift handling updated: all three drift paths now route through BPMN refresh.

The post-failure paragraph (lines 93–103) is well-structured and clearly explains the atomicity guarantee, preconditions, and the CLI-unavailable fallback.

3. skills/uipath-maestro-bpmn/references/shared/project-layout.md

Severity: OK

Adds the refresh command block after the generated-files list with a clear bridge sentence. The pack note follows naturally. Links to local-metadata-regeneration-guide.md for the full contract — proper reference-pointer discipline.

4. skills/uipath-maestro-bpmn/references/integration-service-activity-authoring-guide.md

Severity: OK

Minimal, targeted change at lines 171–173: adds a bridge sentence pointing to the refresh command after the existing "never hand-create or edit" rule. Does not duplicate the refresh contract — just names it and states its purpose. Clean reference-pointer discipline.

5. skills/uipath-maestro-bpmn/references/operate/CAPABILITY.md

Severity: OK

Critical rule 4 updated from "Refresh or regenerate" to "Refresh package metadata before cloud actions" with an explicit instruction to "run the local BPMN refresh command." Concise and actionable.

6. skills/uipath-maestro-bpmn/references/operate/references/ship.md

Severity: OK

Pre-flight step 4 now includes the actual command block (previously just prose). Pack section correctly states "Pack should consume the refreshed files rather than own their generation." Import/package correlation and failure handling sections updated to route through refresh. All changes are consistent with the new ownership model.

7. tests/scripts/test_bpmn_metadata_refresh_contract.py

Severity: OK

Well-structured contract guard with three tests:

1. test_skill_orders_validate_before_refresh_and_scopes_it_to_packages — validates step 5 exists, ordering, scope prose, and all four generated file names.
2. test_metadata_guide_makes_refresh_the_atomic_source_boundary — validates command presence, ordering (validate < refresh < pack), atomicity, precondition, and entry-point generation prose.
3. test_lifecycle_guides_delegate_generation_to_refresh_not_pack — validates that project-layout, IS activity guide, and ship all reference refresh and delegate generation correctly.

The _commands() helper that joins backslash-continued lines is a good pattern for matching multi-line command blocks. The _prose() helper normalizes whitespace for cross-line phrase matching.

8. .github/workflows/test-helpers.yml

Severity: OK

New bpmn-metadata-refresh-contract-guard job follows the exact pattern of the existing bpmn-script-task-contract-guard job: checkout → setup-python 3.13 → install pytest → run. Consistent and correct.

What's Missing

Nothing identified. The PR updates every file that references package metadata generation, adds contract tests covering all changed files, and registers the CI job. CODEOWNERS already covers the skill path. No new skill folder was added, so no additional test tasks are required.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No changes; existing frontmatter is valid
E2E Tests	OK	3 contract guard tests added; existing task suite covers the skill
Skill Body	OK	Step 5 cleanly integrated; count updated
References & Assets	OK	All 5 references consistently updated; links verified
Repo Hygiene	OK	CODEOWNERS present; no secrets; no cross-skill refs; CI job added

Issues for Manual Review

• CLI contract accuracy: The review cannot verify that uip maestro bpmn refresh actually exists with the documented behavior (atomic four-file writes, idempotence, GUID validation, deduplication). The PR description references UiPath/cli#3331 and UiPath/cli#3356 — confirm those are merged or will merge before this skill layer ships.
• "root manual start event" qualifier: The guide now consistently says "root manual" rather than just "root." Confirm this matches the CLI's actual filter — i.e., that refresh truly skips non-manual (e.g., message, timer, signal) root start events.

Conclusion

Clean PR. The refresh command is consistently documented across all 5 reference files with proper ownership boundaries, and the contract guard covers the key invariants (ordering, scope, atomicity, delegation). No issues found that require changes. Approve.

---