fix(maestro-case): centralize the create-on-missing 'already exists' adopt contract (two live-run gaps)

[song-zhao-25]

Summary

Two gaps in the create-on-missing "already exists" adopt path, surfaced by the api-workflow L4 suite (T2b: on-disk-unregistered residual) and root-caused live on CLI 1.198. Both affect the already-merged agent leg too. Docs-only, 2 files.

1. Kind-check blind spot. The adopt path must confirm the colliding project's kind before adopting, but registry list --local enumerates only .uipx-registered projects — an unregistered on-disk residual (the exact case the residual handles) is invisible to it. Fixed: two-step kind-check — registered name → list --local Category; unregistered dir → on-disk project.uiproj ProjectType.
2. project add stale-decl refusal. uip solution project add refuses Project name already exists even when the name is absent from .uipx Projects[] — its collision check keys on stale resource declaration files left by a prior registration, not the manifest. Verified live: deleting resources/solution_folder/package/<Name>.json + the kind's process/<category>/<Name>.json makes the same command succeed ("Added successfully"); resources refresh regenerates them. (Arguably a CLI bug — the collision check could key on the manifest; docs carry the remediation either way.)

Structure

The corrected contract now lives once, kind-agnostically, as registry-discovery.md § Create-on-Missing 3b ("Already exists" = adopt). agent/planning.md's residual blockquote shrinks to a pointer + agent-specific tokens (error verbs, kind markers). This removes the duplication that let each new creatable-kind leg re-author (and re-break) the same recovery logic.

Downstream

Merge-first by design: the open create-on-missing legs — #1802 (api-workflow), #1803 (rpa), #1723 (agentic) — inherit on their next rebase and should slim their per-type residual blockquotes to the same pointer shape. Future legs link §3b instead of re-authoring.

Runtime evidence: case_coding_agent_tests/create-on-missing-api-workflow-test/T2b-ondisk-unregistered/run-log.md + results.md (adopt completed end-to-end via the corrected procedure: project add "Added successfully" → refresh → rediscover Source:local → validate Valid).

🤖 Generated with Claude Code

[github-actions]

Claude finished @song-zhao-25's task in 2m 7s —— View job

---

PR Review: fix(maestro-case): centralize create-on-missing adopt contract

• Read review criteria and project conventions
• Analyze the diff
• Read full changed files for context
• Verify relative links resolve
• Check for cross-skill references and secrets
• Post review findings

---

Summary

Centralizes the "already exists" adopt contract for the create-on-missing path into registry-discovery.md §3b (kind-agnostic, authoritative), and slims the agent-specific blockquote in planning.md to a pointer plus agent-specific tokens. Fixes two live-run gaps: a kind-check blind spot for unregistered residuals and a project add stale-declaration refusal.

Change-by-Change Review

1. skills/uipath-maestro-case/references/registry-discovery.md (+10 lines)

Severity: OK

New §3b inserted between §3 (Register) and §4 (Rediscover). Content is well-structured:

• Step 1 covers the two-step kind-check (registered via list --local Category, unregistered via on-disk project.uiproj ProjectType). This directly addresses the blind-spot gap where --local can't see unregistered residuals.
• Step 2 documents the stale-resource-declaration workaround for project add refusing even when the name is absent from .uipx Projects[], with the specific remediation (delete declaration files, re-run, refresh). CLI version (1.198) cited as live verification.
• Step 3 is a clean forward-pointer to §4.
• The closing line ("Per-type error verbs and kind markers live in each type plugin's § Failure blockquote") establishes the intended pointer contract for downstream legs.

Heading numbering (3b) slots cleanly between existing §3 and §4. Section placement is logical — adopt is a sub-case of registration.

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

Severity: OK

The old blockquote inlined the full adopt procedure (inline "register it, then rediscover + bind"). The replacement keeps only:

• A link to the authoritative §3b in registry-discovery.md
• Agent-specific error verbs (uip agent init "directory exists / not empty", project add "Project name already exists")
• Agent-specific kind markers (Category: "agent", on-disk project.uiproj ProjectType / agent.json presence)
• The behavioral directive (never Retry/Skip, never rebuild; clear stale declarations if needed)

This follows Reference Pointer Discipline correctly — the blockquote carries only bridge content and agent-specific tokens; the mechanism lives in the linked file. The relative link ../../../registry-discovery.md#create-on-missing-build-and-rediscovery resolves correctly (3 levels up from plugins/tasks/agent/ → references/).

What's Missing

• No test coverage for the adopt path. No existing test tasks in tests/tasks/uipath-maestro-case/ cover create-on-missing or the "already exists" adopt flow. The PR description mentions runtime evidence (case_coding_agent_tests/...T2b.../run-log.md), but that's external to the repo's coder_eval framework. Severity: Medium — the adopt path is a recovery contract that agents must follow precisely; a coder_eval task exercising it would catch regressions if the procedure changes.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Not modified
E2E Tests	Medium	No coder_eval task covers the adopt path (existing skill, not blocking)
Skill Body	OK	Not modified
References & Assets	OK	New §3b is well-placed, correctly linked, no duplication
Repo Hygiene	OK	No secrets, no cross-skill refs, changes scoped to one skill

Issues for Manual Review

• CLI behavior accuracy. The stale-resource-declaration workaround (§3b step 2) — deleting resources/solution_folder/package/<Name>.json and resources/solution_folder/process/<category>/<Name>.json before re-running project add — is documented as "verified live, CLI 1.198." Future CLI versions may fix this collision-check behavior, which would make the deletion step unnecessary but harmless. Worth watching.
• Downstream leg adoption. The PR description notes that open legs (feat(maestro-case): build missing API workflows inline during planning #1802, feat(maestro-case): add RPA process leg to create-on-missing #1803, feat(maestro-case): build missing agentic processes inline (stacked on #1622) #1723) should slim their per-type blockquotes to the same pointer shape on next rebase. Reviewers familiar with those PRs should confirm the contract is compatible.

Conclusion

Clean, well-scoped docs-only fix. The centralization removes a duplication vector that would otherwise re-break with each new creatable-kind leg. The two gaps (kind-check blind spot, stale-declaration refusal) are clearly root-caused and the remediation is specific. Approve — the missing test task is a medium gap but doesn't block this fix.

---