fix(uipath-maestro-case): distinguish missing registry cache from empty results

[song-zhao-25]

Summary

• preserve the existing contract that the approved sdd.md is authoritative and trusted as written
• make login plus uip maestro case registry pull an unconditional Phase 1 gate before cache inspection, carryover reuse, resolution, or artifact writes
• distinguish a missing cache before a successful pull (refresh precondition failure) from a genuine empty lookup after a successful pull
• ensure staged registry-resolved.json carryover cannot cause Phase 1 to skip the refresh

Why

In the failed registry_handoff_action_case_sdd_only run, the agent checked ~/.uip/case-resources, observed CACHE_ABSENT, and treated that as if the tenant had no matches. It retained the concrete Action binding from the authoritative SDD and emitted placeholders for the two <UNRESOLVED> resources, but never attempted the required registry pull.

The SDD behavior was correct; the cache-state interpretation was not. A missing cache means discovery has not been refreshed on that machine. Only after a successful pull can an empty exact-name match set enter the normal empty-resource/placeholder flow.

Prior passing run: https://github.com/UiPath/skills/actions/runs/29624029348

Validation

• skill-creator quick_validate.py
• git diff --check
• parsed SKILL.md YAML frontmatter
• checked relative Markdown links in changed files

[github-actions]

Claude finished @song-zhao-25's task in 3m 30s —— View job

---

PR Review: fix(uipath-maestro-case): require fresh registry before binding

• Read review criteria and project conventions
• Analyze full diff
• Read all changed files in full context
• Check relative links resolve
• Check for cross-skill references
• Check for secrets/tokens/personal paths
• Post review findings

---

Summary

This PR hardens the uipath-maestro-case skill so that Phase 1 authentication and uip maestro case registry pull is an unconditional hard gate before any cache inspection, carryover reuse, resolution, or artifact writes. It also strengthens the distinction between SDD design intent and live registry evidence across SKILL.md, planning.md, registry-discovery.md, and four per-plugin planning docs (action, agent, api-workflow, case-management). The change is motivated by a coder-eval run that skipped the registry pull and copied SDD identifiers directly into resolved bindings.

Change-by-Change Review

1. skills/uipath-maestro-case/SKILL.md (+9/−7)

Severity: OK

• Rule 2 updated to clarify SDD is "sole source of design intent — NOT registry evidence" and that concrete SDD IDs/folders are lookup constraints, never proof of current presence. Adds the key prohibition: "MUST NOT be copied into matches or selected without current cache evidence." Clear, well-scoped.
• Rule 3 elevated to "PHASE 1 HARD GATE" with explicit login-then-pull sequence, failure semantics (stop Phase 1), and the distinction between pre-pull missing cache (precondition failure) vs post-pull missing index (genuine zero). Correct.
• Rule 9 adds provenance constraint: matches from freshly pulled cache, selected must be one of those matches or null. "Never synthesize either field from sdd.md" — exactly the invariant the failing test violated.
• Rule 14 rewritten to add binding-sidecar parity checks. This is a separate concern from the registry gate fix (bindings_v2.json parity) but was bundled. Correctly scoped to Phase 4 entry and pre-resources refresh.
• Phase 2 steps renumbered 7→8→9 (was 7→8) to insert the new bindings_v2 regeneration step. Step references are internally consistent.
• Phase 3 adds step 6 for mandatory bindings_v2 parity reconciliation.
• Phase 4 step 1 adds the parity precondition before full validate.

All changes are internally consistent. Frontmatter unchanged and valid.

2. skills/uipath-maestro-case/references/planning.md (+8/−6)

Severity: OK

• Step 1 heading changed from "Check login and pull registry" to "HARD GATE: check login and pull registry" — consistent with Rule 3 language.
• Step 1 body now explicitly says "unconditional on every Phase 1 run, including SDD-only handoffs and runs with a staged tasks/registry-resolved.json" — directly addresses the failing test scenario.
• Post-pull guidance rewritten: "Do not inspect ~/.uip/case-resources/ first to decide whether the pull is necessary" — prevents the exact shortcut the agent took.
• Step 2's SDD description changed from "sole required input" to "sole source of design intent, not proof of live registry state" — consistent with Rule 2.
• New "Current-cache provenance — mandatory" blockquote added before the carryover section. This overlaps with the "Provenance invariant" paragraph added to registry-discovery.md (change chore: compact skills #7) but serves as a bridge: it states the invariant in the planning context and registry-discovery.md has the authoritative detail. The overlap is a single-paragraph restatement, not a multi-step duplication — acceptable as bridge content.
• Carryover section tightened: prior selection retained only when "present in that current match set" — adds the crucial freshness check that was missing.
• Output matches is always "the full current exact-name match set, never the carried-over array" — prevents stale array propagation.

3. skills/uipath-maestro-case/references/plugins/tasks/action/planning.md (+1/−1)

Severity: OK

Single-line change in Registry Resolution: Action App ID now "records whether the prior phase claimed to resolve the app; it is not current registry proof and never bypasses the Phase 1 pull/direct-cache lookup." Adds "populate matches/selected only from action-apps-index.json; never construct an Action App object from those SDD fields." Consistent with the invariant.

4. skills/uipath-maestro-case/references/plugins/tasks/agent/planning.md (+1/−1)

Severity: OK

Wording change: "SDD is untrusted sole input" → "SDD supplies design intent, not build approval" — more precise and consistent with Rule 2's new language.

5. skills/uipath-maestro-case/references/plugins/tasks/api-workflow/planning.md (+1/−1)

Severity: OK

Same wording change as agent/planning.md. Consistent.

6. skills/uipath-maestro-case/references/plugins/tasks/case-management/planning.md (+1/−1)

Severity: OK

Registry Resolution step 3 expanded: SDD Folder Path / Resource Identity are "current-cache constraints when concrete; they are not registry proof and never bypass the Phase 1 pull/direct-cache lookup." Adds "Populate matches/selected only from caseManagement-index.json; never construct a child-case object from SDD fields." Consistent with the invariant.

7. skills/uipath-maestro-case/references/registry-discovery.md (+3/−1)

Severity: OK

• Prerequisites section strengthened: "Phase 1 hard gate, not a conditional refresh: never inspect the cache first and use its absence to skip the pull. Login/pull failure stops Phase 1 before planning artifacts are written." Consistent with Rule 3 and planning.md Step 1.
• New "Provenance invariant" paragraph added after the registry-resolved.json field listing — the authoritative statement of the invariant. matches and selected are "registry evidence, not design fields." Concrete SDD fields "constrain and disambiguate the lookup but MUST NOT be assembled into cache-shaped objects." Well-placed as the section already defines those fields.

What's Missing

Nothing identified. The PR is tightly scoped to the registry-gate hardening. The bundled Rule 14 / bindings_v2 parity changes are related (they gate other artifact-write points), and the existing test task (registry_handoff_action_case_sdd_only) directly covers the scenario that motivated this fix — no new test task is needed. All relative links in changed files resolve. No cross-skill dependencies introduced. CODEOWNERS already covers this path.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Unchanged and valid; name matches folder, description under 1024 chars
E2E Tests	OK	Existing registry_handoff_action_case_sdd_only task covers the motivating scenario
Skill Body	OK	Rules 2, 3, 9, 14 updated consistently; phase steps renumbered correctly
References & Assets	OK	All 6 reference files updated with consistent invariant language; all links resolve
Repo Hygiene	OK	No secrets, no cross-skill imports, CODEOWNERS in place, changes scoped to one skill

Issues for Manual Review

• Domain accuracy of Rule 14 (bindings_v2 parity). The parity-check addition (Rule 14, Phase 2 step 7, Phase 3 step 6, Phase 4 step 1) is a separate concern from the registry-gate fix. It appears correct, but domain experts should verify the bindings-v2-sync.md § Check 7 reference and the claim that resources refresh only consumes bindings_v2.json and never generates it.
• Planning.md "Current-cache provenance" vs registry-discovery.md "Provenance invariant." Both state the same rule. The overlap is small (one paragraph each) and the planning.md version serves as a bridge in context, but if the invariant evolves, two locations must be updated. Worth watching for drift.

Conclusion

Clean, well-scoped change that addresses a real agent failure mode. The invariant is stated precisely and repeated consistently across all the right touchpoints. No issues found — approve.